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

Cobrar um pedido

Inicia o pagamento de um pedido e acompanha a transação.

Com o pedido criado, o cliente paga. POST /payments escolhe a forma e dispara a cobrança; GET /payments/{id} acompanha o resultado. Ambas exigem o token do cliente dono do pedido. Para pagar sem token (visitante), veja os gateways em Gateways de pagamento.

Iniciar um pagamento

Cobra o pedido pela forma escolhida, no gateway configurado na loja: gera o Pix, o boleto ou autoriza o cartão. Formas offline e faturadas apenas registram uma transação pendente, sem chamar gateway. O pedido precisa ser do cliente do token.

POST/api/v1/storefront/paymentsCliente

Cobra o saldo de um pedido pela forma de pagamento escolhida

Corpo da requisição

order_iduuidobrigatório
Pedido a pagar.
payment_method_codestringobrigatório
code de uma forma elegível para o pedido (pix, boleto, credit_card...). Se vários métodos ativos tiverem o mesmo código, vale o que casa com o slug e tem gateway online.
amountintegerobrigatório
Valor em centavos. Tem de ser exatamente o saldo devido do pedido; qualquer outro valor é recusado.
currencystringobrigatório
Envie BRL.
customer_emailstringobrigatório
E-mail do pagador, enviado ao gateway.
customer_namestring
Nome completo do pagador. Se faltar, usa o nome do pedido.
customer_cpfstring
CPF do pagador (11 dígitos). CPF ou CNPJ, conforme o gateway exigir.
customer_cnpjstring
CNPJ do pagador (14 dígitos).
customer_phonestring
Telefone com DDD. O Pagar.me exige para Pix; se faltar, é lido do pedido.
billing_addressobject

Endereço de cobrança. O Pagar.me exige para boleto; se faltar, vem do pedido.

line_1string
Rua e número.
line_2string
Complemento.
citystring
Cidade.
statestring
UF.
zip_codestring
CEP, com ou sem máscara.
installmentsinteger
Parcelas do cartão.
card_referencestring
Id de cartão salvo (cartão na carteira) ou token de cartão do gateway. Nunca envie o número do cartão.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/payments" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
    "payment_method_code": "pix",
    "amount": 22500,
    "currency": "BRL",
    "customer_email": "maria.souza@example.com",
    "customer_name": "Maria Souza",
    "customer_cpf": "12345678909",
    "customer_phone": "11987654321"
  }'

Resposta

201Pagamento iniciado (Pix)
json
{
  "id": "baf48a29-9120-4729-93ef-3adc1738a6cc",
  "tenant_id": "",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "payment_method_id": "02000000-0000-0000-0000-000000000001",
  "status": "P",
  "amount": 22500,
  "currency": "BRL",
  "transaction_id": "ch_Kx9QzR2mVn3LdY7a",
  "pix_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540522.505802BR5913MINHA LOJA6009SAO PAULO62070503***6304ABCD",
  "pix_qr_code": "https://api.pagar.me/core/v5/transactions/tran_xxxx/qrcode?payment_method=pix",
  "expires_at": "2026-10-11T15:32:11Z",
  "created_at": "2026-10-11T15:02:11Z",
  "updated_at": "2026-10-11T15:02:11Z"
}

Campos da resposta

iduuid
Id da transação de pagamento (use em GET /payments/{id}).
tenant_idstring
Uso interno; pode vir vazio. Ignore.
order_iduuid
Pedido que está sendo pago.
payment_method_iduuid
Forma de pagamento usada.
statusstring
Estado, em uma letra: P pendente (aguardando o cliente ou o gateway), C concluído, F falhou, R reembolsado. A confirmação final costuma chegar depois, por webhook; releia a transação ou o pedido.
amountinteger
Valor cobrado, em centavos.
currencystring
Moeda (BRL).
transaction_idstring
Id da cobrança no gateway. Ausente nas formas offline.
gateway_responseobject
Resposta bruta do gateway; o formato depende dele. Não dependa da estrutura.
pix_codestring
Pix "copia e cola" (BR Code). Só em Pix.
pix_qr_codestring
QR Code do Pix (URL da imagem ou dados, conforme o gateway). Só em Pix.
boleto_urlstring
Link do boleto para imprimir. Só em boleto.
boleto_barcodestring
Linha digitável. Só em boleto.
expires_atstring
Quando o Pix ou boleto deixa de valer (RFC 3339).
paid_atstring
Quando foi pago (RFC 3339). Ausente enquanto não pago.
refunded_atstring
Quando foi reembolsado, se foi.
created_atstring
Criação (RFC 3339).
updated_atstring
Última atualização (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
400Falta order_id, payment_method_code ou amount maior que zero.{"error":"order_id is required"}
400amount diferente do saldo devido.{"error":"amount_mismatch","message":"amount must be the order's balance due","amount_due":22500,"amount_sent":20000}
401Sem token de cliente no cabeçalho Authorization.{"error":"missing authorization header"}
403O pedido é de outro cliente.{"error":"you do not have permission to create payments for this order"}
404Pedido inexistente.{"error":"order not found"}
409A forma não está disponível para este pedido.{"error":"payment_method_not_allowed","message":"payment method is not available for this order"}
409O pedido já está pago.{"error":"order_already_paid","message":"this order is already paid"}
500Falha no gateway, bloqueio antifraude ou forma de pagamento inexistente. A causa vem em detail.{"error":"failed to create payment","detail":"..."}
Repetir a chamada é seguro

Se já existe uma transação pendente para o mesmo pedido e a mesma forma, a plataforma devolve essa transação em vez de cobrar de novo (por exemplo, o mesmo QR Code do Pix). Trocar de forma de pagamento cria uma nova transação.

O corpo não manda no cliente nem no valor

O cliente cobrado é sempre o do token e o valor é conferido contra o pedido. Campos como customer_id enviados no corpo são ignorados.

Consultar um pagamento

Devolve uma transação criada em Iniciar um pagamento. Use para acompanhar um Pix ou boleto pendente (consultando a cada poucos segundos, com limite) até status virar C. Só funciona para transações de pedidos do próprio cliente.

GET/api/v1/storefront/payments/{id}Cliente

Estado de uma transação de pagamento

Parâmetros de caminho

iduuidobrigatório
Id da transação (id devolvido ao iniciar).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/payments/baf48a29-9120-4729-93ef-3adc1738a6cc" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Transação
json
{
  "id": "baf48a29-9120-4729-93ef-3adc1738a6cc",
  "tenant_id": "",
  "order_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
  "payment_method_id": "02000000-0000-0000-0000-000000000001",
  "status": "C",
  "amount": 22500,
  "currency": "BRL",
  "transaction_id": "ch_Kx9QzR2mVn3LdY7a",
  "pix_code": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-7890-abcd-ef1234567890520400005303986540522.505802BR5913MINHA LOJA6009SAO PAULO62070503***6304ABCD",
  "pix_qr_code": "https://api.pagar.me/core/v5/transactions/tran_xxxx/qrcode?payment_method=pix",
  "expires_at": "2026-10-11T15:32:11Z",
  "created_at": "2026-10-11T15:02:11Z",
  "updated_at": "2026-10-11T15:02:11Z",
  "paid_at": "2026-10-11T15:04:40Z"
}

Campos da resposta

(corpo)object
Mesmos campos de Iniciar um pagamento.

Erros

StatusQuandoCorpo de exemplo
401Sem token de cliente no cabeçalho Authorization.{"error":"missing authorization header"}
403A transação é de um pedido de outro cliente.{"error":"you do not have permission to view this transaction"}
404Transação inexistente.{"error":"transaction not found"}
500id que não é um UUID válido, ou falha de leitura.{"error":"failed to get transaction","detail":"..."}
'Pago' só depois da confirmação

Receber 201 significa que a cobrança começou. Pix e boleto ficam P até o cliente pagar; o gateway avisa a plataforma por webhook e o pedido muda sozinho. Não marque o pedido como pago no seu sistema só porque o POST deu certo.

Veja também

  • Formas de pagamento
  • Link de pagamento
  • Ids, dinheiro e datas
Anterior
Parcelas
Próxima
Link de pagamento
Nesta página
  • Iniciar um pagamento
  • Consultar um pagamento
  • Veja também