Gateways de pagamento
Como cobrar por Pix, Pagar.me e Braspag diretamente, inclusive para visitantes.
Um gateway é o serviço que realmente move o dinheiro: gera o Pix, autoriza o cartão, emite o boleto. A plataforma integra vários; cada loja liga os que usa, como módulos. Estas rotas falam direto com três deles. São abertas a visitantes porque o checkout deve funcionar sem conta, e por isso o valor cobrado nunca é o que o cliente envia.
Como funciona
O fluxo comum a todos os gateways:
- Escolher o gateway
Pelo
gatewayda forma de pagamento escolhida (veja formas elegíveis):pix,pagarmeoubraspag. - Criar a cobrança
- Acompanhar
Consulte o estado (veja as páginas de cada gateway) enquanto o cliente paga. A confirmação definitiva chega à plataforma por webhook do gateway, que atualiza o pedido.
Estado de cada gateway:
| Gateway | Campo | Valores |
|---|---|---|
| Pix | status | pending, paid, expired, failed |
| Pagar.me | status | pending, paid, authorized_pending_capture, failed, refused, canceled, refunded, chargeback |
| Braspag | status | NotFinished, Authorized, PaymentConfirmed, Denied, Voided, Refunded, Pending, Aborted, Chargeback |
Conceitos-chave
Visitante e cliente logado
Estas rotas ficam fora do bloco que exige login. Se você enviar o token do cliente, ele é usado para identificar o pagador (por exemplo, para ligar cartões salvos ao mesmo cliente); sem token, o pedido é a única referência. Para cobrar com token e conferência de dono do pedido, use Cobrar um pedido.
Valor sempre do pedido
Para evitar cobrança com valor adulterado, o servidor lê o total do pedido e o usa no lugar do amount do corpo. No Pix, o campo é ignorado. No Pagar.me e na Braspag, é sobrescrito quando o pedido é encontrado.
Cartão e PCI
Número e CVV de cartão são dados sensíveis (norma PCI). Prefira sempre tokenizar no navegador (Pagar.js, Silent Order Post da Braspag) e enviar só o token.
Pix expirado
O Pix tem prazo. Passado o prazo sem pagamento, o Pix vira expired e o pedido é cancelado.
Endpoints
| Método e caminho | Para quê | Autenticação | Página |
|---|---|---|---|
POST /api/v1/storefront/pix/payments | Gera o Pix de um pedido | Pública | Pix |
GET /api/v1/storefront/pix/payments/{txid} | Consulta um Pix pelo txid | Pública | Pix |
GET /api/v1/storefront/pix/payments/by-order/{orderId} | Pix mais recente de um pedido | Pública | Pix |
POST /api/v1/storefront/pagarme/charge | Cobra um pedido por cartão, boleto ou Pix | Pública | Pagar.me: cobrar e tokenizar |
POST /api/v1/storefront/pagarme/charges | Cria a cobrança pela rota antiga (/charges) | Pública | Pagar.me: cobrar e tokenizar |
POST /api/v1/storefront/pagarme/tokenize | Troca o cartão por um token (tok_...) | Pública | Pagar.me: cobrar e tokenizar |
GET /api/v1/storefront/pagarme/charges/{id} | Consulta uma cobrança da rota antiga pelo id | Pública | Pagar.me: consultar cobranças |
GET /api/v1/storefront/pagarme/charges/order/{orderID} | Cobrança Pagar.me mais recente de um pedido | Pública | Pagar.me: consultar cobranças |
POST /api/v1/storefront/braspag/payments | Cobra um pedido na Braspag (cartão ou boleto) | Pública | Braspag |
GET /api/v1/storefront/braspag/payments/{paymentId} | Consulta um pagamento Braspag | Pública | Braspag |