PostPay/Cash/ATM

PostPay in general are cash-based payments. This payment method gives the customer the possibility to select the product online, and pay for it later in a designated establishment. The delay between the initial order and the consumer completing their payment means that this does not always suit perishable goods and time-sensitive purchases. This is a very popular payment type throughout Latin America, with almost every country having its own version and peculiarities.

Available Payment Methods

Brazil

Boleto Bancário

Type: postpay

Sub-type: boleto

Boleto Bancário or just Boleto is a financial document issued by a bank that enables the customer to pay the exact specified amount to the receiving party.

Boleto always includes:

• Issuer bank information
• 44-digit ID field: it holds the same information as the bar code
• Bar code: it holds the same information as the ID field
• Payable amount value

The customer can pay a boleto at an ATM, a bank, an approved facility, or through their bank's online banking system. After the boleto is paid, the bank sends to PagSeguro a file confirming the payment. The confirmation is received in one business day. However, it may require up to 3-6 business days after the payment date in case of holidays. If a boleto has not been paid before the due date, the corresponding transaction remains open at PagSeguro MyAccount for 8 days.
When a Boleto payment is submitted, the PagSeguro payments platform returns a response with an URL in the payment-url field. The URL points to a page with an image of the boleto that the customer needs to proceed with their payment. The merchant can redirect the customer to that URL so that they can complete the payment at an ATM, a bank or an approved facility.

📘

The API supports registered boletos and API only provide Safra, Santander and Caixa Econômica Federal boletos.

Workflow

1 - Customer fills and submits all necessary payment information to the merchant server.

2 - The merchant submits to /transactions to create the transaction.

3 - PagSeguro creates an order and returns the transaction code, Boleto URL and barcode number to the merchant.

4 - The merchant displays the Boleto to the customer using the PagSeguro Boleto URL or provides the digitable-line to the customer.

Creating a Boleto Payment

To create a boleto payment method, make a POST request as the example.

Request

📘

Production URL:

https://api.boacompra.com/transactions

Method: POST

🚧

Sandbox URL:

https://api.sandbox.boacompra.com/transactions

Method: POST

Example of a request using boleto

{
  "transaction": {
    "reference": "REF-XXX-1234567890",
    "project-number": 1,
    "country": "BR",
    "currency": "BRL",
    "checkout-type": "direct",
    "notification-url": "https://billing.checkout.com/processing",
    "language": "pt-BR"
  },
  "charge": [
    {
      "amount": 100.00,
      "payment-method": {
        "type": "postpay",
        "sub-type": "boleto"
      }
    }
  ],
  "payer": {
    "name": "John Doe",
    "email": "[email protected]",
    "birth-date": "1988-12-25",
    "phone-number": "+5511987654321",
    "document": {
      "type": "CPF",
      "number": "00000000191"
    },
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 302",
      "district": "Bairro dos testes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    },
    "ip": "200.221.118.80"
  },
  "shipping": {
    "cost": 0,
    "address": {
      "street": "Rua Teste",
      "number": "1102",
      "complement": "AP 302",
      "district": "Bairro dos Testes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030000"
    }
  },
  "cart": [
    {
      "quantity": 1,
      "description": "Calça Jeans",
      "category": "Collectibles",
      "type": "physical",
      "unit-price": 1
    }
  ]
}

Request Parameter List

[1] Required when cart[].type is physical

Some considerations about the payer name:

• Maximum length of 50 characters
• Minimum two words
• Each word must be separated by ONE space
• The first and last word must have at least 2 characters long
• Middle words can have only one character
• Accepted characters: A to Z, uppercase and/or lowercase letters
• Special characters accepted: éíóúãõâêôàèìòùäëïöüçñÁÉÍÓÚÃÕÂÊÔÀÈÌÒÙÄËÏÖÜÇÑ&/'.-

Some considerations about the payer email:

• On the local-part (before the @), only alphanumeric characters and the special characters - + . _ are allowed.

Response

Example of a response using boleto

{
  "transaction": {
    "code": "111116875",
    "reference": "REF-XXX-1234567890",
    "amount": 100.00,
    "status": "PENDING",
    "currency": "BRL",
    "country": "BR",
    "payer-email": "[email protected]",
    "date-created": "2018-10-09T11:13:37.54658934-03:00",
    "barcode-number": "03399767800000001009853029700000167460590101",
    "digitable-line": "03399853012970000016874605901011976780000000100",
    "payment-url": "https://payment.boacompra.com/b/OXBJSUwzUUNwSm84aHVlbXdqaXRuQT09"
  }
}

📘

Response using boleto

The response body for this request is slighty different from others payment methods. The Merchant needs to either display the Boleto to the customer using the PagSeguro Boleto URL or provide the digitable-line given in the response body.

Response Parameter List

📘

About boleto

• The barcode-number response parameter can be used to generate and display the barcode in the own merchant website.
  It's in the Interleaved 2 of 5 (ITF) pattern, used by Brazilian Banks.
  The open-source library JsBarcode. can be used to generate the barcode image.

• The digitable-line response parameter could be used to offer the possibility for the end user to copy the digits equivalent to the barcode to make the payment in his bank website/app, without read the barcode.

Boleto best practices

When providing an alternative payment method like Boleto Bancário, it is required to include a confirmation page on the flow. Furthermore, on this page we can include some features to increase the payment method conversion, as well as informing the particularities of the payment method chosen to the customer.

Confirmation page example

1. In Brazil we still have a large population of people without bank accounts. It is recommended always offer to the customer the print Boleto option, with this they can make the payment at an ATM, a bank or an approved facility.

   INFO: To use this feature, use transaction.payment-url included in the response of the boleto transaction.

2. Brazillian banks Apps and some mobile wallets offer their users the option to make boleto payments scanning the bar codes in their smartphones. Providing the Barcode with a good resolution is a good practice to increase conversion with these users.

   INFO: To use this feature, use transaction.barcode-number included in the response of the boleto transaction and associate it with an open-source library like JsBarcode.

to generate the barcode image.

3. It is a good practice to offer the option of copying the payment code. This allows the customer to pay directly on their bank's internet banking. This feature is mandatory if want to increase conversion for mobile users.
   
   INFO: To use this feature, use transaction.digitable-line included in the response of the boleto transaction.