Receber pagamentos por voucher

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 disponível depende da configuração da conta, moeda e país. Não envie nomes de opções locais 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`	Transferência bancária SPEI	CLABE/conta, referência e instruções de transferência. `voucher.url` é sempre `null` em MXN.
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.

A disponibilidade depende dos países, moedas e métodos de pagamento habilitados na conta. Se o país e a moeda selecionados não estiverem habilitados, a criação do pagamento será recusada.

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`

Esta tabela lista os tipos de documento aceitos pela validação da API. A disponibilidade de pagamento em cada país ainda depende da configuração de pagamento habilitada para a empresa.

Exibir as instruções

A resposta da transação expõe o objeto normalizado voucher.

{
  "id": "018f1f2e-7b44-7c9a-8d3e-1a2b3c4d5e71",
  "status": "pending",
  "method": "voucher",
  "amount": 125000,
  "currency": "MXN",
  "voucher": {
    "barcode": "646180123456789012",
    "digitable_line": "646180123456789012",
    "url": null,
    "expiration_date": "2026-05-12T23:59:59.000Z",
    "instructions": "Pague usando a referência bancária antes do vencimento.",
    "receipt_url": null
  }
}

Em MXN (SPEI), a API nunca devolve URL hospedada de pagamento: voucher.url é sempre null e a CLABE em voucher.barcode é a instrução de pagamento. Nas demais moedas a URL continua vindo quando o meio de pagamento local fornece uma.

Campo	Significado
`voucher.barcode`	Código de barras, conta bancária, CLABE, código de pagamento ou referência, 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. Use como chamada principal quando existir. Sempre `null` em MXN.
`voucher.expiration_date`	Vencimento ou data de expiração da instrução de pagamento.
`voucher.instructions`	Instruções adicionais do banco ou do meio de pagamento.
`voucher.receipt_url`	URL de comprovante quando disponível. Normalmente aparece depois da confirmação do pagamento.

Os campos são nullable porque os meios de pagamento locais usam formatos diferentes de instrução. Monte o checkout para exibir todos os campos presentes, e não para depender de um formato fixo de Boleto.

Atualizações assíncronas

Alguns meios de pagamento locais 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 meio escolhido suportar reembolso.
Webhooks de pagamento	Receber eventos `transaction.pending`, `transaction.paid`, reembolso, expiração e chargeback.

Pagamentos

Checkout Links

Pix

Vouchers

Cartão

Significado por país

Criar a transação

Tipos de documento aceitos

Exibir as instruções

Atualizações assíncronas

Endpoints relevantes

Leia a seguir

​Significado por país

​Criar a transação

​Tipos de documento aceitos

​Exibir as instruções

​Atualizações assíncronas

​Endpoints relevantes

​Leia a seguir

Significado por país

Criar a transação

Tipos de documento aceitos

Exibir as instruções

Atualizações assíncronas

Endpoints relevantes

Leia a seguir