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

Link de pagamento

Abrir, pagar e imprimir a cobrança de um link de pagamento sem login.

O link de pagamento permite cobrar alguém sem login e sem carrinho. A loja (ou a Venddor Intelligence, a assistente da plataforma) cria o link no painel; quem paga abre /pay/{token}. Estas três rotas são o que essa página usa. O token é o segredo: quem o tem, paga.

Abrir um link de pagamento

Um link de pagamento é uma URL (/pay/{token}) que a loja cria para cobrar um valor fixo de alguém, mesmo sem pedido aberto ou sem conta: uma entrada, um saldo, uma cobrança avulsa ou uma cotação aprovada. Esta rota devolve o que a página de pagamento precisa mostrar. Nunca é guardada em cache, porque o estado muda fora desta chamada (pago, cancelado, expirado).

GET/api/v1/storefront/payment-links/{token}Pública

Dados públicos de um link de pagamento

Parâmetros de caminho

tokenstringobrigatório
Token secreto do link (último trecho da URL /pay/{token}).

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/payment-links/q7Nf2LxV9mRk4TcB8yHd3WsZ6aPj1GeU"

Resposta

200Link aberto
json
{
  "token": "q7Nf2LxV9mRk4TcB8yHd3WsZ6aPj1GeU",
  "description": "Entrada do pedido 1042",
  "amount_cents": 150000,
  "status": "open",
  "allowed_methods": [
    "pix",
    "boleto",
    "credit_card"
  ],
  "method_labels": {
    "pix": "PIX",
    "boleto": "Boleto",
    "credit_card": "Cartão de Crédito"
  },
  "max_installments": 6,
  "store_name": "Minha Loja",
  "expires_at": "2026-10-18T23:59:59Z"
}

Campos da resposta

tokenstring
O mesmo token da URL.
descriptionstring
O que está sendo cobrado.
amount_centsinteger
Valor fixo do link, em centavos.
statusstring
openpaidexpiredcancelled
Estado do link. Só open aceita pagamento. A expiração é aplicada na leitura.
allowed_methodsarray
Códigos das formas que o link aceita, já cruzados com as formas ativas da loja.
method_labelsobject
Nome amigável de cada código de allowed_methods.
max_installmentsinteger
Teto de parcelas no cartão.
store_namestring
Nome da loja.
expires_atstring
Validade do link (RFC 3339).

Erros

StatusQuandoCorpo de exemplo
404Token desconhecido (a resposta não revela se o token existiu).{"error":"payment link not found"}

Documento do boleto faturado

Para uma forma faturada (boleto faturado), não existe boleto de banco: a plataforma gera um documento de cobrança em HTML (loja, valor, vencimento, pedido, sacado) que o cliente imprime. É o destino do botão "Abrir boleto" e a URL já vem em boleto_url na resposta do pagamento. Formas com PSP (Pagar.me) trazem o boleto do próprio banco e não usam esta rota.

GET/api/v1/storefront/payment-links/{token}/boletoPública

Página HTML imprimível da cobrança faturada

Parâmetros de caminho

tokenstringobrigatório
Token do link.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/storefront/payment-links/q7Nf2LxV9mRk4TcB8yHd3WsZ6aPj1GeU/boleto"

Resposta

200Documento HTML
html
<!doctype html>
<html lang="pt-BR">
  ... documento de cobrança (Content-Type: text/html) ...
</html>

Erros

StatusQuandoCorpo de exemplo
404Link inexistente.{"error":"payment link not found"}

Pagar um link

Cobra o valor do link (o valor nunca vem do corpo) por uma das allowed_methods. Se o link não tem pedido, a plataforma cria um pedido mínimo de "Cobrança avulsa" no momento do pagamento; chamadas repetidas reaproveitam o mesmo pedido e a mesma transação pendente, então não há cobrança em duplicidade. Cartão aprovado marca o link como paid na hora; Pix e boleto ficam pendentes até a confirmação do gateway.

POST/api/v1/storefront/payment-links/{token}/payPública

Cobra o valor do link pela forma escolhida

Parâmetros de caminho

tokenstringobrigatório
Token secreto do link (último trecho da URL /pay/{token}).

Corpo da requisição

payment_method_codestringobrigatório
Um código presente em allowed_methods.
customer_emailstringobrigatório
E-mail do pagador (precisa conter @).
customer_namestring
Nome completo. Opcional, mas o Pagar.me recusa cobrança sem nome; sem ele a plataforma deriva um do e-mail.
customer_cpfstring
CPF (11 dígitos) ou CNPJ (14), com ou sem máscara. Opcional; se enviado e com tamanho errado, a chamada é recusada.
customer_phonestring
Telefone com DDD. Obrigatório na prática para Pix no Pagar.me.
installmentsintegerpadrão: 1
Parcelas do cartão. Acima de max_installments, é reduzido ao teto sem erro.
card_tokenstring
Token do cartão (obtido por tokenização). Cartão: obrigatório.
billing_line_1string
Rua e número do endereço de cobrança. Obrigatório para boleto no Pagar.me.
billing_line_2string
Complemento.
billing_citystring
Cidade.
billing_statestring
UF.
billing_zip_codestring
CEP com 8 dígitos. O endereço só é usado se billing_line_1 e um CEP de 8 dígitos vierem juntos.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/storefront/payment-links/q7Nf2LxV9mRk4TcB8yHd3WsZ6aPj1GeU/pay" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_code": "pix",
    "customer_email": "carlos.pereira@example.com",
    "customer_name": "Carlos Pereira",
    "customer_cpf": "12345678909",
    "customer_phone": "11988776655"
  }'

Resposta

200Pagamento iniciado
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": 150000,
  "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",
  "order_number": "1042"
}

Campos da resposta

(corpo)object
A transação, com os campos de Iniciar um pagamento, mais:
order_numberstring
Número do pedido para exibir ao cliente.

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido.{"error":"invalid request body","detail":"..."}
404Link inexistente (mensagem em português).{"error":"Link de pagamento não encontrado."}
409Link expirado, cancelado ou já pago.{"error":"Este link não pode mais ser pago (expirado, cancelado ou já pago)."}
409Forma fora de allowed_methods.{"error":"payment_method_not_allowed","message":"Esta forma de pagamento não está disponível neste link."}
422E-mail ausente/inválido ou CPF/CNPJ com tamanho errado (a mensagem completa pede um e-mail válido e, se houver documento, 11 ou 14 dígitos).{"error":"informe um e-mail válido ..."}
422Dado do pagador que o gateway exige (telefone, endereço, documento, nome, cartão) ou cobrança recusada pelo provedor. A mensagem, em português, diz qual.{"error":"Informe um telefone/celular com DDD para concluir o pagamento."}
502O gateway não respondeu. Tente de novo ou use outra forma.{"error":"Não foi possível iniciar o pagamento agora. Tente novamente em instantes ou escolha outra forma de pagamento."}
Mensagens vêm em português

Nesta rota o texto de error já é feito para o comprador e é devolvido em português, também nas lojas em outro idioma. Exiba-o diretamente. O erro técnico do gateway nunca é repassado.

Quem cria o link

A criação, a listagem e o cancelamento de links ficam na API de administração, fora desta seção. Um link só é criado se a loja tem um gateway de pagamento online ativo.

Veja também

  • Cobrar um pedido
  • Pix
Anterior
Cobrar um pedido
Próxima
Gateways de pagamento
Nesta página
  • Abrir um link de pagamento
  • Documento do boleto faturado
  • Pagar um link
  • Veja também