Processar pagamentos na Checkout API Supergasbras

A Checkout API da Supergasbras oferece suporte a múltiplos métodos de pagamento. Este guia mostra como consultar os métodos disponíveis para uma sessão e como iniciar o processo de cobrança.

Listar métodos de pagamento disponíveis

Antes de iniciar o pagamento, consulte os métodos disponíveis para a sessão de compra atual:

curl -X GET "https://checkout-ms.supergasbras.app/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/payments/methods" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

A resposta inclui os métodos habilitados para aquela sessão, que podem variar de acordo com o perfil do cliente e o valor do pedido.

Iniciar o pagamento

Após selecionar o método de pagamento, inicie a cobrança:

curl -X POST "https://checkout-ms.supergasbras.app/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/payments" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": "CREDIT_CARD",
    "paymentData": {
      "cardToken": "token-do-cartao"
    }
  }'

O campo paymentData varia de acordo com o método de pagamento selecionado. Consulte a referência de pagamentos para detalhes por método.

Acompanhar o status do pagamento

Após iniciar o pagamento, consulte o estado da sessão para verificar o status:

curl -X GET "https://checkout-ms.supergasbras.app/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

Completar o pedido

Quando o pagamento for aprovado, complete o pedido:

curl -X POST "https://checkout-ms.supergasbras.app/v1/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/complete" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI"

Tratamento de erros de pagamento

Código HTTP	Causa	Ação
`400 Bad Request`	Dados de pagamento inválidos ou ausentes	Verifique os campos obrigatórios
`402 Payment Required`	Pagamento recusado	Solicite ao cliente um novo método de pagamento
`404 Not Found`	Sessão não encontrada	Confirme o `sessionId`
`409 Conflict`	Pagamento já iniciado nesta sessão	Consulte o estado atual antes de tentar novamente

Implemente uma estratégia de retry com backoff exponencial para lidar com erros temporários durante o processamento do pagamento.

​Listar métodos de pagamento disponíveis

​Iniciar o pagamento

​Acompanhar o status do pagamento

​Completar o pedido

​Tratamento de erros de pagamento

Listar métodos de pagamento disponíveis

Iniciar o pagamento

Acompanhar o status do pagamento

Completar o pedido

Tratamento de erros de pagamento