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

Payment MethodCountriesRefundsRecurringChargebacksTypeSub-Type
Boleto BancárioBRYesNoNopostpayboleto

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

651651

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

33353335

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": "+5511991234556",
    "document": {
      "type": "CPF",
      "number": "31192071280"
    },
    "address": {
      "street": "Rua dos Bobos",
      "number": "1102",
      "complement": "AP 302",
      "district": "Vinicius de Moraes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030010"
    },
    "ip": "200.221.118.80"
  },
  "shipping": {
    "cost": 0,
    "address": {
      "street": "Rua dos Bobos",
      "number": "1102",
      "complement": "AP 302",
      "district": "Vinicius de Moraes",
      "state": "PR",
      "city": "Maringá",
      "country": "BR",
      "zip-code": "87030010"
    }
  },
  "cart": [
    {
      "quantity": 1,
      "description": "Calça Jeans",
      "category": "Collectibles",
      "type": "physical",
      "unit-price": 1
    }
  ]
}

Request Parameter List

ParameterDescriptionTypeSizeMandatory
transactionSet of general transaction's informationObject-Yes
transaction.referenceMerchant transaction identifierStringUp to 64Yes
transaction.project-numberMerchant project identifier. Default value is 1Integer-No
transaction.countryCountry of the payment. Accepts only BRString2Yes
transaction.checkout-typeCheckout type of the transaction. Accepts only directString-Yes
transaction.notification-urlURL (must bind ports 80 or 443) used to send transaction statuses changes notifications by HTTPStringUp to 200Yes
transaction.languageLanguage used. Accepts pt-BR, en-US, es-ES, pt-PT and tr-TRString5Yes
charge[]Set of payments. Currently accepting just one (1) paymentArray1Yes
charge[].amountAmount of the transaction. Separating cents by point, with two decimal places. Amount sum must be equal to shipping.cost plus cart items valueNumberMin of 0.01Yes
charge[].payment-method.typePayment Method type (credit-card, postpay, e-wallet or eft)String-Yes
charge[].payment-method.sub-typePayment Method sub-type. Available payment methods (see more)String-Yes
payerSet of customer's informationObject-Yes
payer.nameCustomer nameStringUp to 50Yes
payer.emailCustomer e-mailStringUp to 60Yes
payer.birth-dateCustomer birth date. ISO-8601 Pattern (YYYY-MM-DD)String-No
payer.phone-numberCustomer phone number. e.g (+5544999884455)String-No
payer.document.typeCustomer document Type. accepts: cpf and cnpjString-Yes
payer.document.numberCustomer identification document. No special characters allowed.String-Yes
payer.ipCustomer IP. accepts IPv4 or IPv6String-Yes
payer.addressCustomer address objectObject-No[1]
payer.address.streetCustomer address streetString1-160Yes
payer.address.numberCustomer address numberString1-20Yes
payer.address.complementCustomer address complementStringUp to 40No
payer.address.districtCustomer address districtString1-60Yes
payer.address.stateCustomer address state or provinceString2Yes
payer.address.cityCustomer address cityString1-60Yes
payer.address.countryCustomer address country (country iso 2)String2Yes
payer.address.zip-codeCustomer address zip codeString8Yes
shippingSet of information that will be used to deliver the items in cart (see more)Object-No[1]
shipping.costShipping cost. Separating cents by dot, with two decimal placesDoubleMin of 0.01Yes
shipping.address.streetShipping address streetString3-160Yes
shipping.address.numberShipping address numberString1-20Yes
shipping.address.complementShipping address complementString5-40No
shipping.address.districtShipping address districtString4-60Yes
shipping.address.stateShipping address state or ProvinceString2Yes
shipping.address.cityShipping address cityString3-60Yes
shipping.address.countryShipping address country (country iso 2)String2Yes
shipping.address.zip-codeShipping address zip CodeString8Yes
cart[]Set of items (at least one Item)ArrayMin of 1Yes
cart[].quantityItem quantityIntegerMin of 1Yes
cart[].descriptionItem descriptionString1-200Yes
cart[].unit-pricePrice per unit. Separating cents by dot, with two decimal placesDoubleMin of 0.01Yes
cart[].typeItem type - must be one of the following: digital, physical, service, subscriptionString-Yes
cart[].categoryItem categoryString1-64No
[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

PropertyDescriptionTypeSizeFormat
transaction.codePagSeguro´s referenceStringUp to 36e.g.: 111181153
transaction.referenceMerchant´s referenceStringUp to 64XXX-XXX-XX-XXXXXXXXXX
transaction.amountTransaction AmountNumber-e.g.: 50.0
transaction.statusCurrent status (see more)String-e.g.: PAID
transaction.currencyCurrency transactionString3e.g.: BRL
transaction.countryCountry transactionString2e.g.: BR
transaction.payer-emailPayer emailStringUp to 60e.g.: [email protected]
transaction.date-createdDate of creationString-e.g.: 2018-10-10T14:39:32.991217999-03:00
transaction.barcode-numberBarcode numerical representationString44e.g.: 10496766600000101508745960000100040003898220
transaction.digitable-lineDigitable lineString47e.g.: 10498745956000010004400038982203676660000010150
transaction.payment-urlGenerated Boleto UrlString64e.g.: https://payment.boacompra.com/b/clhZYUVTRGZRdUNuKzZwR1grcEZsZz09

📘

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

11731173
  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.

  1. 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.