Payment intents

O payment intent é a intenção de cobrança na API Korbit. Você cria com o valor e o método de pagamento, e a Korbit orquestra o processamento, os estados e a conciliação até a confirmação final.

Estados

Estado	Significado
`REQUIRES_ACTION`	Aguardando o comprador: PIX gerado (QR/copia-e-cola) ou desafio 3DS pendente
`SUCCEEDED`	Pago e confirmado pelo provedor
`FAILED`	Recusado ou expirado
`CANCELED`	Cancelado

Transições de estado chegam via webhooks (payment.created.v1, payment.requires_action.v1, payment.succeeded.v1, payment.failed.v1) — nunca confie apenas em polling.

Criar um payment intent PIX

curl -X POST https://api.korbit.com.br/v1/payment-intents \
  -H "Authorization: Bearer kbt_live_EXEMPLO_NAO_USAR" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 14990,
    "currency": "BRL",
    "paymentMethod": "PIX",
    "description": "Pedido #1042",
    "externalReference": "pedido-1042",
    "expiresInSeconds": 900
  }'

A resposta em REQUIRES_ACTION traz o código PIX copia-e-cola (e QR Code) para exibir ao comprador:

{
  "id": "pi_…",
  "status": "REQUIRES_ACTION",
  "amount": 14990,
  "currency": "BRL",
  "paymentMethod": "PIX",
  "pix": { "copyAndPaste": "00020126…6304ABCD" }
}

No sandbox o código PIX vem com prefixo KORBIT_FAKE_PIX_ e você controla o desfecho com simulação.

Cartão de crédito

O fluxo recomendado para cartão é via checkout hospedado (link de pagamento ou sessão de checkout), onde os dados sensíveis do cartão são capturados diretamente pelo provedor em iframes seguros — sua aplicação nunca toca no número do cartão. Quando a operação exige autenticação 3D Secure, a sessão conduz o desafio automaticamente; o desfecho chega no payment intent (veja Cartão e 3DS).

Consultar e conciliar

curl https://api.korbit.com.br/v1/payment-intents/{id} \
  -H "Authorization: Bearer kbt_live_EXEMPLO_NAO_USAR"

Use externalReference para amarrar o payment intent ao seu pedido interno e fazer a conciliação do seu lado. O status retornado pela API é sempre a fonte autoritativa — replays de webhook não devem mudar o estado do seu sistema (veja Idempotência).

​Estados

​Criar um payment intent PIX

​Cartão de crédito

​Consultar e conciliar

Estados

Criar um payment intent PIX

Cartão de crédito

Consultar e conciliar