Boleto Bancário

Start accepting payments using Boleto Bancário, a favorite payment method in Brazil. Used as vouchers, it can process payments in US Dollars and Brazilian Real.

Before you can accept Boleto Bancário payments, you will need to arrange an agreement with our Boleto provider, dLocal, and create merchant details (specifically, x_login and x_trans_key) and a secret key with them. Share these details with our customer support team and we'll get you up and running. If you have already been onboarded for our other dLocal payment method, OXXO, you can use the same credentials.

Process a Boleto Bancário payment

For Boleto Bancário payments, funds are settled directly from dLocal to your account, with Checkout.com acting as a gateway.

Boleto Bancário payments follow a two-step process:

  1. Request a Boleto Bancário payment
  2. Redirect the customer or render the ticket

Step 1: Request a Boleto Bancário payment

The request

Use the details below to set up your request.

Endpoints

Live

https://api.checkout.com/payments

Sandbox

https://api.sandbox.checkout.com/payments

Header parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Body parameters

The table below describes the minimum recommended fields. You can find the full list, as well as complete request and response examples, in our API reference.

Field name
Description

source
Object
Required

Details about the payment source.

source.type
string
Required

The type of payment source. Set this to boleto.

source.integration_type
string
Required

The type of integration. Either direct or redirect.

  • direct: a ticket object is returned, which you can use to render a ticket to the customer. No redirect URL is returned.
  • redirect: a redirect URL is returned. Redirect the customer to this URL to proceed with the payment.

source.country
string
Required

The two-letter code (ISO 3166) of the customer's country. Should be BR.

source.payer
Object
Required

Details about the customer.

source.payer.name
string
Required

The full name of the customer.

source.payer.email
string
Required

The email address of the customer.

source.payer.document
string
Required

The customer's tax identification number. Either Cadastro de Pessoas Físicas (CPF) or Cadastro Nacional da Pessoa Jurídica (CNPJ).

source.description
string
optional

A description of the payment.

amount
String
required

The payment amount.

currency
String
Required

The three-letter currency code (ISO 4217). Should be BRL or USD.

Request examples

{
  "source": {
    "type": "boleto",
    "integration_type": "redirect",
    "country": "BR",
    "payer": {
      "name": "John Doe",
      "email": "[email protected]",
      "document": "53033315550"
    },
    "description": "boleto payment"
  },
  "amount": 100,
  "currency": "BRL"
}
{
  "source": {
    "type": "boleto",
    "integration_type": "direct",
    "country": "BR",
    "payer": {
      "name": "John Doe",
      "email": "[email protected]",
      "document": "53033315550"
    },
    "description": "boleto payment"
  },
  "amount": 100,
  "currency": "BRL"
}

If a customer ID or email is not provided in the request, then we automatically create a customer profile and return the customer id in the response.

The response

Whether you used the direct or redirect method, you should get a 202 response with the status field set to Pending. This means your request has been accepted.

Response examples

{
  "id": "pay_hcklpcd45ymepcr7thciirbdaa",
  "status": "Pending",
  "customer": {
    "id": "cus_kh6eqv276rou7ae5s3uwj4emnq"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_hcklpcd45ymepcr7thciirbdaa"
    },
    "redirect": {
      "href": "https://sandbox.dlocal.com/collect/pay/pay/M-8aaf7e50-682f-11ea-ab15-cd9dd592717d?xtid=CATH-ST-1584436398-2076616064"
    }
  }
}
{
  "id": "pay_gxw65fs6rijepgn4rb5tqqvp5u",
  "status": "Pending",
  "customer": {
    "id": "cus_6unw4ulqvrlenduk4xiurlbiyq"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_gxw65fs6rijepgn4rb5tqqvp5u"
    }
  }
}

Step 2: Redirect the customer or render the ticket

To complete the payment, you need to provide the customer with a Boleto Bancário ticket by following one of two flows:

Redirect the customer to Boleto Bancário

Redirect your customer to the Boleto Bancário ticket page using the redirect URL from the response.

On this page, the ticket is hosted, and can be viewed, downloaded or printed by the customer.

It will also have a button which the customer can click to return to your success page (or failure page, if the payment has expired).

Make sure that your customer has some means of returning to a summary of their order that contains a link to the hosted Boleto Bancário ticket, so they can still access the ticket if their connection drops out or they forget to print/download it. You could do so with an order summary email, or an area on their account where they can view past orders.

Render the Boleto Bancário ticket

Redirect your customer to your success page, where you should summarize their order and render the Boleto Bancário ticket so they can complete the payment.

To get the components necessary to render the ticket, use the 'get payment details' endpoint below. This will return dlocal_order_id, dlocal_payment_id and a ticket object, which you should use to display the ticket.

Tips for displaying the ticket:

  • Allow the customer to copy the ticket number. They need to enter this in their banking app/website to complete the payment.
  • Include the barcode. Customers who pay at a physical store or use a barcode reader will need this.
  • The barcode needs to be in the Interleaved 2 of 5 (ITF) format to be recognised by all Boleto Bancário barcode readers.
  • Include the amount and currency on the ticket.
  • Use the dd/mm/yyyy format for the expiry date, and make sure it is clear and visible.
  • You can also include a link to the full ticket with the source.ticket.image_url. It's not necessary for payment, but some customers prefer to have it.

Here's an example:

Get details about a Boleto Bancário payment

Use the payment id (for example, pay_hcklpcd45ymepcr7thciirbdaa) from the payment response with the following endpoint to retrieve details about a payment.

The request

Use the details below to set up your request.

Endpoint live

GEThttps://api.checkout.com/payments/{payment_id}

Endpoint sandbox

GEThttps://api.sandbox.checkout.com/payments/{payment_id}

Header and path parameters

Header
Value

Authorization
Required

secret key

Use the valid secret key of your Checkout.com account. You can find this in the Hub.

Content-Type
Required

application/json

Path
Value

payment_id
Required

The payment ID found in the response of the initial payment.

The response

The response will differ depending on which integration type (redirect or direct) you used in the initial payment request.

Response examples

{
  "id": "pay_hcklpcd45ymepcr7thciirbdaa",
  "requested_on": "2020-03-17T09:13:18Z",
  "source": {
    "type": "boleto",
    "dlocal_order_id": "430fa151c1034a8788950dcaf061c6b8",
    "dlocal_payment_id": "D-30150-39d14a21-f598-4163-b8d0-2befaf9acc29"
  },
  "amount": 100,
  "currency": "BRL",
  "payment_type": "Regular",
  "status": "Pending",
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_kh6eqv276rou7ae5s3uwj4emnq"
  },
  "_links": {
    "redirect": {
      "href": "https://sandbox.dlocal.com/collect/pay/pay/M-8aaf7e50-682f-11ea-ab15-cd9dd592717d?xtid=CATH-ST-1584436398-2076616064"
    },
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_hcklpcd45ymepcr7thciirbdaa"
    }
  }
}
{
  "id": "pay_gxw65fs6rijepgn4rb5tqqvp5u",
  "requested_on": "2020-03-17T09:14:17Z",
  "source": {
    "type": "boleto",
    "dlocal_order_id": "c0e6cc2bf24c43c79fbbee55df293f5c",
    "dlocal_payment_id": "D-30150-e59f330d-4b92-487c-a09a-3307be2184b7",
    "ticket": {
      "type": "custom",
      "number": "10499136581700010004400067492298882020000000100",
      "barcode": "10498820200000001009136517000100040006749229",
      "id": "14000000000674922",
      "expiration_date": "2020-03-23T02:59:00Z",
      "company_name": "dLocal",
      "provider_name": "caixa",
      "provider_logo_url": "https://static-sandbox.dlocal.com/images/providers/caixa.png",
      "ticket_url": "https://sandbox.dlocal.com/gmf/payments/M-ae4c2980-682f-11ea-ab15-cd9dd592717d"
    }
  },
  "amount": 100,
  "currency": "BRL",
  "payment_type": "Regular",
  "status": "Pending",
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_6unw4ulqvrlenduk4xiurlbiyq"
  },
  "_links": {
    "self": {
      "href": "https://api.sandbox.checkout.com/payments/pay_gxw65fs6rijepgn4rb5tqqvp5u"
    }
  }
}

Refund a Boleto Bancário payment

You can refund a Boleto Bancário payment using our refund API. Partial and multiple – as well as full – refunds are allowed.

The customer will get an email (the email address is taken from the source.payer.email property in the initial payment request) from dLocal asking for their banking details. Once the customer has provided their details, dLocal transfer the money to the customer's bank account.

The payment status will update to refunded and you will receive a payment_refunded (or payment_refund_declined, if unsuccessful) webhook notification.

A refund processing fee may apply.

Cancel a Boleto Bancário payment

You cannot cancel a Boleto Bancário payment, but it will expire after seven days (or more, if you have requested a longer period) if the customer fails to complete the transaction in this time. If the payment expires, we'll send you a payment_expired webhook.

Boleto Bancário webhooks

Webhook
Description

payment_pending

Sent when a payment request is successfully initiated.

payment_capture_pending

Sent when the acquirer is in the process of accepting the payment.

payment_captured

Sent when the customer has completed the payment with the ticket.

payment_expired

Sent when the ticket has expired.

payment_declined

Sent when there was a failure in creating the payment.

payment_refund_pending

Sent when a refund is successfully initiated.

payment_refunded

Sent when a refund is successfully processed.

payment_refund_declined

Sent when a refund is declined.

Testing Boleto Bancário

To start testing, you'll need to:

  • create a test account, and
  • contact your customer success manager or integrations engineer to activate Boleto Bancário payments in the sandbox environment.

  1. Create a Boleto Bancário transaction as above (following the redirect method), and follow the redirect link in the response. You should be presented with a page like the one below.


  2. Click PAY.

  3. Click RETURN.

  4. You should then be redirected to your predefined success page.

Testing Boleto Bancário refunds
To test a refund, create a refund request in sandbox with our API as normal, and then contact the dLocal team so they can complete the process from their side. You will then receive a payment_refunded notification.

Can we help?

Thanks for using Checkout.com. If you need any help or support, then message our support team at [email protected].

Updated 3 days ago

Boleto Bancário


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.