Skip to main content
POST
Esta é a rota central da API. Nela você define quanto cobrar, de quem, o que está sendo vendido e como o cliente vai pagar. A mesma chamada atende venda avulsa em loja virtual, compra de curso, recompra com cartão salvo, Apple Pay e venda com divisão de valores entre contas (split).

Quando usar

Antes de chamar

  • Tenha uma chave secreta gerada por usuário Owner ou Manager (Credenciais e ambientes). Chave de usuário com perfil Desenvolvedor recebe 403.
  • A sua conta precisa ter taxa configurada para o método e a moeda da cobrança. Sem ela, a API responde 422 Fees not configured, inclusive no Modo Teste.
  • Se algum item for physical, tenha o endereço de entrega.
  • Se vai usar split, as contas recebedoras precisam pertencer ao mesmo grupo Connect.
O valor vai em reais: "amount": 10 significa R$ 10,00. O mínimo é 1. Enviar 1000 pensando em R$ 10,00 gera uma cobrança de R$ 1.000,00.
A API não aceita cabeçalho de idempotência: cada chamada cria uma cobrança nova. Se a criação der timeout, não reenvie de imediato. Siga o procedimento para timeout: mande o número do seu pedido em metadata, recupere o id pelo webhook charge.created ou pela listagem e só crie outra cobrança se nada for encontrado.

Corpo da requisição

Campos obrigatórios: amount, currency, customer, paymentMethod e items.
number
required
Valor da cobrança em reais (ex.: 10 = R$ 10,00). Mínimo: 1.
string
required
Código da moeda no padrão ISO 4217. Ex.: BRL. Apple Pay e Pix aceitam só BRL.
object
required
Quem está pagando. Há dois caminhos: informar o id de um cliente já cadastrado (os outros campos ficam opcionais e o cadastro existente é usado como está) ou enviar name + email (ou phone) para a API criar ou localizar o cliente na mesma chamada.
object
required
Como o cliente vai pagar. Aceita quatro formatos, identificados pelo type e pelos campos que vêm junto. Veja Formas de pagamento abaixo.
object[]
required
Lista do que está sendo vendido. Todos os campos do item são obrigatórios.
object
Endereço de entrega. Obrigatório quando algum item é physical. Sem ele, a API responde 400 antes de criar a cobrança: nenhum id é gerado e nenhum webhook é enviado.
object
Dados de rastreio do envio.
object
Informações suas, em formato livre, que ficam guardadas na cobrança. Ex.: {"orderId": "ORD-123"}. Use chaves em camelCase, que voltam iguais em todos os canais. Chaves em snake_case voltam convertidas para camelCase nas respostas de GET e no charge.updated. Veja Metadata.
string
URL (formato uri) que recebe, de forma assíncrona, os eventos desta cobrança. Ela não muda a resposta da criação. Ex.: https://meusite.com.br/webhooks/finvia.A postbackUrl recebe os mesmos eventos de cobrança que os endpoints de webhook do painel, no envelope padrão (id, event, livemode, data): charge.created, charge.pending, charge.paid, charge.refused, charge.failed, charge.refunded, charge.pre_chargeback e charge.blocked. Não há filtro de eventos nesse canal. Ela recebe também o charge.updated legado, que vai só para a postbackUrl, em camelCase e sem id nem livemode. Veja a tabela de eventos por canal.
object[]
Divisão do valor entre contas do mesmo grupo Connect. Se você não enviar split, a API aplica a regra de split padrão da conta para aquela moeda e método, quando houver uma.
Para o negócio: por padrão, o percentual do split incide sobre o valor líquido da cobrança, isto é, o valor menos a taxa transacional (fixa + percentual). O uso do valor bruto é configurado pela Finvia, sob consulta. O repasse acontece a cada parcela liquidada. Prazos e exemplos em Split e Cálculo de split.

Formas de pagamento

Cartão de crédito

string
required
credit_card.
string
required
Número do cartão, só com dígitos e sem espaços. Ex.: 4444333322221111.
string
required
Nome impresso no cartão. Ex.: MARIA SOUZA.
string
required
Mês de validade com 2 caracteres (minLength 2, maxLength 2). Ex.: 10.
string
required
Ano de validade com 4 caracteres (minLength 4, maxLength 4). Ex.: 2028.
string
required
Código de segurança. Mínimo de 3 caracteres.
integer
required
Número de parcelas. Mínimo 1, máximo 12. Valor 0, negativo ou acima de 12 recebe 400.
string
Use managed para a Finvia conduzir a autenticação 3D Secure. Com esse valor, envie também browser e não envie threeDS.O 3DS só começa quando a política 3DS da sua conta dispara (3DS habilitado e obrigatório, ou valor igual ou acima do mínimo configurado). A partir daí:
  • Se o emissor pedir verificação do dispositivo ou desafio, a resposta vem com status authentication_required, reason Autenticação 3DS gerenciada necessária e authenticationUrl.
  • Na autenticação sem atrito (frictionless), a cobrança segue direto e a resposta já traz o status final.
  • Sem browser, ou se o serviço de 3DS falhar, a cobrança segue sem 3DS. Se o 3DS for obrigatório para a conta, ela é recusada.
Veja 3DS gerenciado.
object
Dados do navegador do comprador, usados na autenticação 3DS (schema BrowserInfo).
object
Resultado de uma autenticação 3DS feita por você antes da cobrança (schema CreditCardThreeDS), pelo SDK ou via API. Repasse o objeto recebido em POST /v1/three-ds/challenge-result. Nos campos opcionais, omita o campo quando não tiver valor e não envie null: o null é gravado e repassado ao adquirente.
O contrato também lista em threeDS os campos mode, deviceData e challenge.returnUrl. No 3DS da Finvia (SDK, via API ou gerenciado) eles não têm uso: não envie.

Cartão salvo

Usa um cartão guardado no cofre da Finvia. O cardTokenId é o campo id devolvido por POST /v1/cards.
O CVV do comprador é obrigatório em toda cobrança com cardTokenId. Sem ele, a API responde 400 CVV is required when using cardTokenId. Esta rota não faz cobrança com o comprador ausente. Para cobrar automaticamente a cada ciclo, use Assinaturas.
string
required
credit_card.
string
required
ID do cartão salvo (resposta de POST /v1/cards). Cartão revogado ou expirado recebe 400. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q.
string
required
Código de segurança, obrigatório mesmo para cartão salvo. Mínimo de 3 caracteres.
integer
required
Número de parcelas. Mínimo 1, máximo 12.
string
managed para 3DS gerenciado. Envie browser junto.
Os campos browser e threeDS também são aceitos, com as mesmas regras do cartão digitado.
No Modo Teste (sk_test_), a cobrança com cardTokenId é simulada e não movimenta dinheiro. O cofre de cartões é o mesmo para teste e produção: o mesmo cardTokenId usado com a chave de produção gera uma cobrança real. Veja Cartão salvo.

Apple Pay

Envie em wallet.token o objeto payment.token devolvido pelo Apple Pay JS no evento onpaymentauthorized, sem alterações. Com wallet, os campos do cartão (number, holderName, expirationMonth, expirationYear, cvv) não são exigidos.
  • Só a versão EC_v1 é aceita.
  • A moeda precisa ser BRL (erro APPLE_PAY_CURRENCY_NOT_SUPPORTED).
  • customer.document é obrigatório (erro APPLE_PAY_CUSTOMER_DOCUMENT_REQUIRED).
  • O 3D Secure não se aplica: a autenticação já vem no token. A Finvia não decifra o token, ele é repassado ao processador.
  • Antes de cobrar, registre e verifique o domínio (POST /v1/apple-pay/domains) e valide a sessão (POST /v1/apple-pay/validate-merchant). O passo a passo está no guia de Apple Pay.
string
required
credit_card.
integer
required
Número de parcelas. Mínimo 1, máximo 12, a mesma regra do cartão digitado.
object
required
Payload da carteira Apple Pay com o token seguro.

Pix

string
required
pix.
number
Validade em dias. Mínimo 1. Obrigatório se expirationInSeconds não for enviado.
number
Validade em segundos. Mínimo 900 (15 minutos). Obrigatório se expirationInDays não for enviado.
Como escolher a validade para cada cenário: veja o guia de Pix. No Modo Teste, o Pix é confirmado sozinho cerca de 5 segundos depois da criação.

Respostas

A resposta 201 tem sempre id, status, paymentDetails e reason. authenticationUrl e customerId aparecem só em alguns casos.
string
required
Identificador único da cobrança criada. Guarde este valor: ele é usado para consultar, estornar e conciliar a cobrança com os webhooks.
string
required
Situação da cobrança na criação: paid, pending, refused, failed, in_analysis ou authentication_required. Os status refunded, pre_chargeback e chargeback nunca saem na criação.
object | null
required
Detalhes específicos da forma de pagamento. Vem null em recusas e quando o status é authentication_required.
string | null
required
Motivo do status. Em recusas, explica a causa (ex.: card_declined, ou um texto iniciado em 3ds_ quando a recusa vem da autenticação). Em in_analysis, vem antifraud_manual_review. Em authentication_required no 3DS gerenciado, vem Autenticação 3DS gerenciada necessária.
string
Endereço para onde o comprador deve ir para concluir a autenticação. Vem só quando status é authentication_required. Use exatamente o valor recebido, sem montar nem alterar a URL. Além do 3DS gerenciado, alguns adquirentes também podem pedir autenticação do lado deles e devolver este campo.
string
ID do cliente criado ou reaproveitado na cobrança. Vem quando a cobrança chega ao adquirente ou é recusada por valor máximo. Não vem quando a cobrança é barrada antes: pelo antifraude (refused ou in_analysis), pela validação de 3DS obrigatório ou quando vai para o 3DS gerenciado (authentication_required).
Trate o erro pelo código HTTP (e pelo código APPLE_PAY_*, quando houver), não pelo texto: as mensagens da API misturam português e inglês.
Para o negócio: no cartão, aprovação e recusa voltam na própria resposta da criação. Se status vier refused, o campo reason explica o motivo e o checkout pode oferecer outra forma de pagamento sem sair da página. No Pix, a resposta traz o QR Code com status pending, e a confirmação do pagamento chega depois, por webhook.

Exemplos por caso de uso

Venda de um curso online. Produto digital, sem endereço de entrega. O Pix expira em 1 hora.
Libere o acesso ao curso só depois de receber charge.paid e confirmar o status com GET /v1/charges/{id}.

Erros comuns

Veja também

Consultar cobrança

Status atual e detalhes de uma cobrança.

Estornar cobrança

Estorno total de uma cobrança paga.

Webhooks de cobrança

Eventos do ciclo de vida da cobrança.

Homologação

Cenários CHG-01 a CHG-10 e SPL-01 a SPL-06.