VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Pagamentos

Como mostrar as formas de pagamento, cobrar um pedido e usar links de pagamento.

Depois do pedido criado, falta receber. Esta seção cobre a parte independente de gateway: descobrir quais formas de pagamento valem para o pedido, calcular parcelas, iniciar a cobrança e usar links de pagamento. Os detalhes de cada gateway (Pix, Pagar.me, Braspag) estão em Gateways de pagamento.

Pontos-chave
  • A lista de formas de pagamento é pública; cobrar um pedido com POST /payments exige o token do cliente dono do pedido.
  • Todo valor é inteiro em centavos. O valor cobrado é sempre o saldo devido do pedido, nunca um número livre.
  • Links de pagamento são públicos e usam um token secreto na URL.
  • 201 na cobrança quer dizer "começou". Quem confirma o pagamento é o gateway, depois, por webhook.

Como funciona

O caminho típico de um pagamento:

  1. Mostrar as formas

    Chame formas elegíveis com o total do pedido. Mostre também as parcelas do cartão.

  2. Cobrar

    Com o cliente logado, inicie o pagamento. A resposta traz o Pix (copia e cola e QR Code), o boleto (link e linha digitável) ou o resultado do cartão.

  3. Acompanhar

    Consulte a transação até status virar C, ou deixe o pedido refletir o pagamento via webhook.

Estados de uma transação (status, uma letra):

statusSignificado
PPendente: aguardando o cliente (Pix, boleto) ou o gateway.
CConcluída: o dinheiro foi confirmado.
FFalhou ou foi recusada.
RReembolsada.

Formas offline (pagamento na entrega, transferência) e invoiced (boleto faturado) ficam em P até a loja confirmar o recebimento.

Conceitos-chave

Tipos de forma de pagamento

online passa por um gateway (Pix, cartão, boleto bancário). offline não tem gateway: a loja confirma depois. invoiced é o boleto faturado B2B, que usa o limite de crédito do cliente.

O valor é do pedido

Mesmo que o corpo traga outro número, a cobrança usa o saldo devido do pedido no servidor. Na rota autenticada um valor diferente é recusado; nas rotas de gateway abertas a visitantes ele é substituído pelo total do pedido.

Parcelas

Duas rotas calculam parcelas: a da loja (usa a configuração dela) e o simulador do Pagar.me (usa parâmetros da consulta). Veja Parcelas.

Link de pagamento

Cobrança de valor fixo, com token secreto, sem login. Estados: open, paid, expired, cancelled.

Endpoints

Método e caminhoPara quêAutenticaçãoPágina
GET /api/v1/storefront/payment-methodsLista as formas de pagamento ativasPúblicaFormas de pagamento
GET /api/v1/storefront/payments/eligibleLista o que o cliente pode usar neste pedidoPúblicaFormas de pagamento
GET /api/v1/storefront/installmentsParcelas conforme a configuração da lojaPúblicaParcelas
GET /api/v1/storefront/pagarme/installmentsSimula parcelas Pagar.me (tabela Price)PúblicaParcelas
POST /api/v1/storefront/paymentsCobra o saldo de um pedidoToken do clienteCobrar um pedido
GET /api/v1/storefront/payments/{id}Consulta uma transação de pagamentoToken do clienteCobrar um pedido
GET /api/v1/storefront/payment-links/{token}Abre um link de pagamentoPúblicaLink de pagamento
GET /api/v1/storefront/payment-links/{token}/boletoDocumento imprimível do boleto faturadoPúblicaLink de pagamento
POST /api/v1/storefront/payment-links/{token}/payCobra o valor do linkPúblicaLink de pagamento

Erros comuns

O que costuma dar errado
  1. Chamar formas elegíveis sem order_total: o boleto, que tem mínimo, some da lista.
  2. Enviar em amount o total do carrinho em reais (225.00) em vez do saldo devido em centavos (22500).
  3. Marcar o pedido como pago ao receber 201. A confirmação vem pelo webhook; consulte a transação.
  4. Esconder o método com credit_blocked: true em vez de mostrá-lo desabilitado com o motivo.
  5. Usar o simulador do Pagar.me como se fosse a configuração da loja: as taxas podem ser diferentes das cobradas.
  6. Registrar a URL do link de pagamento em log público: o token é o segredo.

Próximos passos

Formas de pagamento
O que o cliente pode usar neste pedido.
Cobrar um pedido
Cobre o pedido e acompanhe.
Link de pagamento
Cobrança sem login por link.
Anterior
Proposta por link (sem login)
Próxima
Formas de pagamento
Nesta página
  • Como funciona
  • Conceitos-chave
  • Tipos de forma de pagamento
  • O valor é do pedido
  • Parcelas
  • Link de pagamento
  • Endpoints
  • Erros comuns
  • Próximos passos