Fluxo de cobrança (intenção de pagamento)
Toda cobrança nasce como uma intenção de pagamento e vira transação quando você confirma:
POST /v2/payment-intents— você diz valor, forma de pagamento, split e comprador. O vendedor é sempre a empresa dona da chave de API.- Só cartão: o cartão vai pro cofre da SwitchPay (
POST {vaultUrl}/tokenize), que devolve um token de uso único. O número do cartão nunca passa pela API nem pelo seu servidor de forma legível (ver Cartão: cofre e cifra). POST /v2/payment-intents/{id}/confirm— com o token (cartão) ou sem corpo (Pix/boleto). Nasce a transação; Pix devolve o QR Code, boleto devolve a linha digitável.
Pix e boleto usam o mesmo fluxo, só pulam o passo 2.
Pix e boleto numa chamada só
Mande confirm: true no passo 1 e a mesma chamada já confirma: a intenção volta CONFIRMED,
com a transação inteira no campo transaction (QR Code do Pix ou linha digitável do boleto).
Não precisa do passo 3. Uma Idempotency-Key só cobre a chamada toda.
Só vale pra Pix e boleto. Cartão precisa do token do cofre antes, então confirm: true com
cartão volta 400 VALIDATION_ERROR. Sem o campo (ou com false), tudo funciona em dois passos.
Situações da intenção
| Status | Significado | O que fazer |
|---|---|---|
REQUIRES_TOKEN | Cartão: esperando o token do cofre | passo 2 e depois confirm |
REQUIRES_CONFIRMATION | Pix/boleto criados sem confirm: true: esperando o confirm | confirm |
CONFIRMED | Virou transação (transactionId preenchido). Olhe a transação daqui em diante — inclusive cartão recusado, que vira transação FAILED | consulte GET /v2/transactions/{transactionId} |
FAILED | A adquirente não respondeu ou falhou na confirmação — no confirm ou na criação com confirm: true (502 PROVIDER_ERROR) | crie outra intenção |
EXPIRED | Passaram 5 minutos sem confirm | crie outra intenção |
CANCELED | Você cancelou antes de confirmar | — |