Documentation Index
Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
Use this file to discover all available pages before exploring further.
Use method: "voucher" quando o cliente vai pagar fora do fluxo de cartão ou Pix por meio de uma instrução local, referência bancária, redirecionamento ou documento pagável.
voucher é o método público da Pagou. O meio de pagamento local real é escolhido pela configuração de pagamento da empresa, moeda e país. Não envie nomes específicos de provedor como boleto, spei, mercadopago, webpay ou codi para a API de transações.
Significado por país
| Mercado do cliente | Meio de pagamento comum por trás de voucher | O que o cliente recebe |
|---|
Brasil, BRL | Boleto | Código de barras, linha digitável, vencimento e URL do boleto quando disponível. |
México, MXN | SPEI ou transferência bancária local | CLABE/conta, referência, URL de pagamento ou instruções de transferência. |
Argentina, ARS | Voucher local de caixa ou carteira, como Mercado Pago quando habilitado para a empresa | Referência, URL de redirecionamento ou instruções locais de pagamento. |
Chile, CLP | Webpay ou voucher local | URL de redirecionamento/pagamento ou instruções de pagamento. |
Colômbia, COP | PSE ou voucher local | URL de redirecionamento/pagamento ou instruções de pagamento. |
Peru, PEN | Voucher local ou transferência bancária | Referência, URL de pagamento ou instruções de pagamento. |
Criar a transação
Crie um pagamento por voucher com POST /v2/transactions.
{
"external_ref": "order_3001",
"amount": 125000,
"currency": "MXN",
"method": "voucher",
"buyer": {
"name": "Ada Lovelace",
"email": "ada@example.com",
"document": {
"type": "CURP",
"number": "LOLA800101MDFXXX09"
},
"address": {
"street": "Av. Paseo de la Reforma",
"city": "Cidade do Mexico",
"zipCode": "06600",
"country": "MX"
}
},
"products": [
{
"name": "Plano anual",
"price": 125000,
"quantity": 1
}
],
"notify_url": "https://example.com/webhooks/pagou"
}
amount e price dos produtos usam a menor unidade da moeda escolhida. Para BRL e MXN, envie centavos.
Em pagamentos LATAM por voucher, envie buyer.document e buyer.address.country sempre que possível. Algumas configurações SPEI conseguem criar o pagamento sem documento, mas a maioria dos meios por voucher/transferência valida o tipo de documento para o país selecionado.
Não inclua token. Tokens de cartão só são válidos para method: "credit_card".
Tipos de documento aceitos
Use estes valores em buyer.document.type quando o comprador pagar com method: "voucher". O país é lido de buyer.address.country quando esse campo é enviado; caso contrário, a Pagou pode inferir um país principal a partir de currency.
| País | Código do país | Tipos de documento aceitos |
|---|
| Argentina | AR | DNI, CUIT |
| Bolívia | BO | CI, CE, NIT |
| Brasil | BR | CPF, CNPJ |
| Chile | CL | RUT, RUN |
| Colômbia | CO | CC, NIT |
| Costa Rica | CR | CDI |
| Equador | EC | CI, PP, RUC, PAS |
| Guatemala | GT | DPI, CUI, NIT |
| México | MX | RFC, CURP |
| Panamá | PA | CE |
| Paraguai | PY | CI, RUC |
| Peru | PE | DNI, RUC |
| Uruguai | UY | CI, RUC |
Exibir as instruções
A resposta da transação expõe o objeto normalizado voucher.
{
"id": "tr_3001",
"status": "pending",
"method": "voucher",
"amount": 125000,
"currency": "MXN",
"voucher": {
"barcode": "646180123456789012",
"digitable_line": "646180123456789012",
"url": "https://provider.example/pay/order_3001",
"expiration_date": "2026-05-12T23:59:59.000Z",
"instructions": "Pague usando a referência bancária antes do vencimento.",
"receipt_url": null
}
}
| Campo | Significado |
|---|
voucher.barcode | Código de barras, conta bancária, CLABE, código de pagamento ou referência do provedor, conforme o meio de pagamento local. |
voucher.digitable_line | Linha digitável, referência de transferência, CLABE ou instrução equivalente para o cliente copiar. |
voucher.url | Página de pagamento, URL do boleto, URL de redirecionamento, imagem de QR code ou voucher hospedado no provedor. Use como chamada principal quando existir. |
voucher.expiration_date | Vencimento ou data de expiração da instrução de pagamento. |
voucher.instructions | Instruções adicionais do banco, provedor ou meio de pagamento. |
voucher.receipt_url | URL de comprovante quando o provedor retorna esse dado. Normalmente aparece depois da confirmação do pagamento. |
Atualizações assíncronas
Alguns provedores retornam todos os dados de voucher na resposta de criação. Outros retornam primeiro status: "pending" e entregam os campos de voucher por webhook logo depois.
Use esta sequência:
- Crie a transação com
method: "voucher".
- Se
voucher.url, voucher.digitable_line ou voucher.barcode vier preenchido, exiba imediatamente.
- Assine webhooks de pagamento e atualize a página do cliente quando a mesma transação receber as instruções de voucher.
- Reconcilie com
GET /v2/transactions/{id} se o worker perder um webhook ou se o cliente atualizar o checkout.
Meios de voucher com redirecionamento, como Webpay ou CODI, continuam sendo pagamentos voucher. Trate a URL como a ação de pagamento do voucher, não como um desafio 3DS de cartão.
Endpoints relevantes
| Endpoint | Uso |
|---|
POST /v2/transactions | Criar a transação voucher. |
GET /v2/transactions/{id} | Consultar o status e os campos de voucher mais recentes. |
GET /v2/transactions?paymentMethods=voucher | Listar transações voucher para reconciliação ou operação. |
PUT /v2/transactions/{id}/refund | Solicitar reembolso depois da confirmação de pagamento, quando o provedor e o meio de pagamento escolhido suportarem reembolso. |
| Webhooks de pagamento | Receber eventos transaction.pending, transaction.paid, reembolso, expiração e chargeback. |
Leia a seguir
