POST /v1/charges, e depois é acompanhada pela resposta da criação, pelos webhooks e pela consulta da cobrança. Com esse ciclo claro, a integração libera o pedido só quando ele foi pago e não deixa de liberar um pedido pago.
paymentMethod. O restante (valor, cliente, itens, endereço) é igual para todas.Quando usar
Formas de pagamento
O campopaymentMethod.type define a forma de pagamento. Cartão digitado, cartão salvo e Apple Pay usam o mesmo type (credit_card) e se diferenciam pelos campos que vão junto.
Qual escolher em cada situação
GET /v1/payment-methods. Para cobrar, a conta também precisa ter taxa configurada para o método e a moeda: sem ela, a API responde 422 Fees not configured.type (credit_card) e aceitam de 1 a 12 parcelas. O Pix é sempre à vista.
O desenho abaixo mostra o caminho comum a toda cobrança, da criação até a liberação do pedido, e o que fazer com cada status da resposta.
Depois de paid, a cobrança ainda pode ser bloqueada ou mudar para refunded, pre_chargeback ou chargeback. Por isso o receptor de webhooks continua ativo mesmo depois de liberar o pedido.
Como funciona
Seu servidor cria a cobrança
POST /v1/charges com a chave secreta, informando valor, moeda, cliente, itens e forma de pagamento. Guarde o id devolvido: ele identifica a cobrança em todas as etapas seguintes.A resposta síncrona diz o que fazer agora
paid, refused ou failed), ou in_analysis quando o antifraude manda para revisão manual. No Pix, traz o QR Code com status pending. Com 3D Secure gerenciado, pode vir authentication_required com a authenticationUrl para o comprador se autenticar.Os webhooks contam o que aconteceu depois
postbackUrl está na tabela de eventos por canal.Seu sistema confirma e libera o pedido
GET /v1/charges/{id}. Os webhooks não têm assinatura, então a consulta à API é a sua confirmação.Ciclo de vida da cobrança
paid e o bloqueio aparece em isBlocked na consulta e no evento charge.blocked. O detalhamento de cada status está em Status de cobrança.
O que vem na resposta e o que vem por webhook
id, status, paymentDetails e reason, mais authenticationUrl e customerId em alguns casos. Os detalhes completos da cobrança (valor líquido, cliente, metadata, split, datas) vêm na consulta e nos webhooks.
Regras de negócio
Itens físicos e digitais
Otype de cada item diz se você entrega algo pelo correio ou transportadora (physical) ou se entrega acesso, arquivo ou serviço online (digital).
- Produto digital (curso, ebook, software): envie
items[].typedigital, semshippingAddress. - Produto físico (roupa, eletrônico, cosmético): envie
items[].typephysicale oshippingAddress. Se quiser, envie tambémtrackingInfocom o código e a situação do envio (awaiting_shipment,on_the_wayoudelivered).
physical e o corpo não trouxer shippingAddress, a API responde 400 com a mensagem literal Shipping info must be provided for merchants selling physical items., antes de criar a cobrança. A regra depende só dos itens enviados.
Metadata
metadata é um objeto livre onde você guarda informações suas na cobrança, como o número do pedido. Ele volta na consulta e nos webhooks, o que ajuda a ligar o evento recebido ao pedido do seu sistema.
metadata em camelCase (orderId) ou com uma palavra só (pedido). Assim elas voltam iguais em todos os canais, e todos os exemplos desta documentação seguem essa regra.
order_id) mudam de formato conforme o canal. Nos webhooks do envelope padrão (charge.paid, charge.refunded e os demais), elas voltam exatamente como foram enviadas (order_id). Nas respostas de GET /v1/charges e GET /v1/charges/{id} e no charge.updated legado, voltam convertidas para camelCase (orderId). Se a sua integração já usa snake_case, leia os dois formatos.Timeout na criação
A API não aceita cabeçalho de idempotência e não busca cobranças pormetadata. Se a chamada de criação der timeout, siga esta ordem:
Não reenvie o POST de imediato
Procure o charge.created
charge.created chega assim que a cobrança é gravada e traz o id e a metadata como foram enviadas. É a forma mais confiável de recuperar o id.Busque na listagem
GET /v1/charges?createdAtStart=AAAA-MM-DD&createdAtEnd=AAAA-MM-DD&searchFor=<documento ou e-mail do comprador>&size=50, com a mesma chave usada na criação. Compare metadata e amount do seu lado.Só então crie de novo
postbackUrl
postbackUrl é uma URL sua, informada na própria cobrança, que recebe de forma assíncrona os eventos dessa cobrança. Ela não muda a resposta da criação.
- Recebe os mesmos eventos de cobrança que os endpoints do painel, no envelope padrão:
charge.created,charge.pending,charge.paid,charge.refused,charge.failed,charge.refunded,charge.pre_chargebackecharge.blocked. Não há filtro de eventos nesse canal. - Recebe também o
charge.updatedlegado, que vai só para apostbackUrl, em camelCase e semidnemlivemode. Ele avisa mudanças informadas depois pelo adquirente (pagamento, recusa ou falha assíncrona, estorno, chargeback), o fim do 3DS gerenciado com recusa, o bloqueio e o alerta de pré-chargeback. - Se a mesma URL estiver cadastrada como endpoint e como
postbackUrl, ela recebe cada evento duas vezes.
postbackUrl, você não recebe o desfecho de cobranças que ficaram em in_analysis nem o aviso de chargeback formalizado. Os formatos estão na tabela de eventos por canal.
Passo a passo
Exemplo de uma cobrança Pix para um produto digital, com metadata e postback.201:
paymentMethod. Os exemplos completos de cada forma estão nos guias específicos e em Criar uma cobrança.
Erros comuns
Perguntas frequentes
Preciso cadastrar o cliente antes de cobrar?
Preciso cadastrar o cliente antes de cobrar?
name e email (ou phone) dentro de customer e a API cria ou localiza o cliente na mesma chamada. O customerId da resposta traz o cliente usado, quando a cobrança chega ao adquirente. Se você já tem o cliente cadastrado, envie só o id dele. Veja Clientes.Posso usar só os webhooks do painel e ignorar a postbackUrl?
Posso usar só os webhooks do painel e ignorar a postbackUrl?
charge.updated, na postbackUrl: o desfecho de cobranças que ficaram em in_analysis ou pending no cartão e o status chargeback do chargeback formalizado (quando o valor é revertido do saldo, os endpoints recebem também charge.refunded). Se você não usa postbackUrl, consulte essas cobranças periodicamente.A cobrança paga pode mudar de status depois?
A cobrança paga pode mudar de status depois?
paid pode ser bloqueada (isBlocked: true, ainda paid) ou ir para refunded (estorno), pre_chargeback (alerta de contestação) ou chargeback. Mantenha o seu endpoint de webhook ativo e o pedido ligado ao id da cobrança.Como acho uma cobrança pelo número do meu pedido?
Como acho uma cobrança pelo número do meu pedido?
metadata. Grave o id assim que a criação responder. Se perdeu o id, use o charge.created ou a listagem com período e searchFor, como em Timeout na criação.Como sei quais formas de pagamento minha conta aceita?
Como sei quais formas de pagamento minha conta aceita?
GET /v1/payment-methods. O filtro currency mostra o que está disponível para uma moeda específica. Pix e Apple Pay aceitam somente BRL.Como testar
Use a chave de teste (sk_test_). No Modo Teste, o Pix é confirmado sozinho cerca de 5 segundos depois da criação e o resultado do cartão depende do número usado (cartões de teste). Execute os cenários da seção “Cobrança sem split” do roteiro de homologação:
- CHG-01 e CHG-02: cartão aprovado à vista e parcelado.
- CHG-03: cartão recusado, com
refusedna resposta e o webhookcharge.refused. - CHG-04 e CHG-05: Pix gerado e Pix pago.
- CHG-06: consulta da cobrança.
- CHG-07: estorno total.
- CHG-08 e CHG-09: recebimento e simulação de webhook.
- CHG-10: item físico sem endereço (
400) e com endereço (201).

