Fluxo completo (checkout próprio)

A ordem das chamadas com o seu front, o seu backend e o nosso SDK — do cartão ao webhook.

Este guia mostra o caminho inteiro de uma venda com checkout próprio: a sua tela, o seu backend e o nosso SDK. Cada peça já tem guia próprio; aqui está a ordem e quem chama quem.

As três partes

Seu front — coleta o cartão, mostra as parcelas e roda o desafio 3-D Secure com o nosso SDK. Nunca fala direto com a nossa API.
Seu backend — o único que usa a chave sk_. Tokeniza, simula parcelas, cobra e recebe webhooks.
Nossa API + SDK — a API é servidor-para-servidor; o SDK é um script no browser, hoje usado para o desafio 3-D Secure.

A chave sk_ é de servidor. Ela não pode aparecer em código de front, em variável de build do seu site nem numa chamada feita pelo browser — quem a tiver cobra em seu nome.

1. O cartão sai do seu front para o seu backend

O comprador digita o cartão na sua tela e você envia os dados para o seu backend por HTTPS. É o seu backend que troca o cartão por um token conosco — o cartão nunca vai do browser direto para a nossa API, porque isso exigiria a sk_ no browser.

Enquanto o cartão passa pelo seu servidor, o escopo de PCI é seu. Se você não quer esse escopo, use o link de pagamento: a página hospedada é nossa e o cartão não toca a sua infraestrutura.

2. Seu backend tokeniza

curl -X POST $API_BASE_URL/payment-methods/tokenize \  -H "Authorization: Bearer sk_live_xxx" \  -H "Content-Type: application/json" \  -d '{    "type": "card",    "card": {      "number": "4111111111111111",      "holder_name": "ADA LOVELACE",      "exp_month": 12,      "exp_year": 2030,      "cvv": "123"    }  }'

A resposta traz um tok_. Guarde-o para o passo 4; PAN e CVV são descartados aqui e não voltam mais.

3. Seu backend simula as parcelas — com o BIN daquele cartão

curl "$API_BASE_URL/installments?amount_cents=100000&max_installments=12&card_bin=411111" \  -H "Authorization: Bearer sk_live_xxx"

Devolve uma opção por parcela, com o valor de cada uma e o total. Renderize essa lista no seu front e deixe o comprador escolher.

Mande sempre o card_bin — os 6 primeiros dígitos do mesmo cartão que você vai cobrar. O total pode depender da bandeira, e a cobrança resolve a bandeira pelo token. Simular sem o BIN, ou com o BIN de outro cartão, faz o comprador ver um total e ser cobrado outro.

4. Seu backend cobra, mandando só a contagem

curl -X POST $API_BASE_URL/charges \  -H "Authorization: Bearer sk_live_xxx" \  -H "Idempotency-Key: pedido_10432" \  -H "Content-Type: application/json" \  -d '{    "amount": 100000,    "payment_method": "CREDIT_CARD",    "installments": 6,    "card_token": "tok_xxx",    "security_code": "123",    "buyer": {      "name": "Ada Lovelace",      "email": "ada@example.com",      "document": "12345678909"    }  }'

O amount é o preço à vista. O total do parcelado é sempre derivado por nós a partir das taxas do estabelecimento — não envie o total já com juros, e não confie num total vindo do browser. O Idempotency-Key deixa você repetir a chamada sem cobrar duas vezes.

5. Se a cobrança nascer requires_action, o SDK entra

Cartão pode exigir autenticação. Nesse caso a charge volta requires_action com um next_action: o seu front carrega o nosso SDK, roda o desafio e o seu backend conclui em POST /charges/{id}/confirm-3ds. O passo a passo está no guia 3-D Secure.

6. O desfecho chega por webhook

Não fique consultando a charge em laço. Assine os eventos de cobrança, valide a assinatura e trate o evento como a fonte do desfecho — inclusive para Pix e boleto, que confirmam depois da resposta HTTP.

Resumo da ordem

front  → seu backend : dados do cartãoseu backend → API   : POST /payment-methods/tokenize        → tok_seu backend → API   : GET  /installments?...&card_bin=411111 → opçõesfront  ← seu backend : lista de parcelasseu backend → API   : POST /charges (tok_ + contagem)   requires_action?  : front roda o SDK → backend confirma o 3-D SecureAPI    → seu backend : webhook com o desfecho