DocumentationAPI Reference
Documentation
Start typing to search…

Boleto (old)

Learn how to accept Boleto, a common payment method in Brazil.

Boleto is an official (regulated by the Central Bank of Brazil) payment method in Brazil.

To complete a transaction, customers receive a voucher stating the amount to pay for services or goods. Customers then pay the boleto before its expiration date in one of several different methods, including at authorized agencies or banks, ATMs, or online bank portals.

Payment typeCash-based
MarketBrazil
Customers currenciesBRL
Processing currenciesBRL
Settlement currenciesEUR
RefundsNo
CFTYes
RecurringNo

Step 1. Make a transaction request

From your server, make a POST /payment_preauthorize request.

https://sandbox.payabl.com/pay/backoffice/payment_preauthorize

Include in the request parameters below:

🚧

The below parameters are mandatory for Boleto.

  • merchantid: The merchant identification number.
  • orderid: The field orderid is optional and exclusively for the merchant's convenience.
  • amount: The amount field contains the transaction’s total amount. This is the amount that will be transmitted to the authorizing system.
  • currency: The currency field contains the alphanumeric currency code for the transaction, according to ISO 4217, e.g. BRL.
  • payment_method: The payment method id - 126.
  • signature: The signature field contains a 40-figure hexadecimal value. This signature value is a checksum designed to protect the merchant account from unauthorized access.
  • country: Customer country in ISO Alpha-2 format. Supported countries: BRA.
  • email: The customer's email address.
  • custom2: The name of payment method - boleto.
  • nationalid: National ID is 13 number characters.
    You can see a full list of parameters in Pre-Authorization.

Request example

merchantid=gateway_test&amount=70&currency=BRL&orderid=Payabl-Test&language=&lastname=Mann&street=Address+4&zip=&city=City&country=BRA&firstname=Muster&state=&email=test%40payabl.com&custom1=&custom2=&custom3=payment+reason&payment_method=126&phone=43543435435&bankname=341&accountnumber=0001&testmode=true&testmodecallbackstatus=FINISHED&nationalid=00183562658&accounttype=0001&accountagencynumber=8585&signature=249c85b8692404b20818dad506529738b1fcb338

Step 2. Handle the redirect

To complete the payment, you need to redirect the customer to the correct URL in the response.

Response

transactionid=215438976&transid=215438976&status=2000&errormessage=pending&errmsg=pending&amount=11.23&price=11.23&currency=BRL&orderid=Payabl-Test&payment_method=126&redirect_url=https%3A%2F%2Fapi.gateway.payretailers.com%2Fv2%2Fpublic%2Ftransactions%2Fgateway%2F1bac2e09-a5eb-4650-bf82-b261fdb5882d&user_id=289757

Step 3. Transaction states

If the customer successfully paid by using the Boleto invoice, you will receive a notification with confirmation.

Notification example (successful transaction):

"national_id=13475444534&timestamp=1666088946&acquirer_id=1bac2e09-a5eb-4650-bf82-b261fdb5882d&payment_method=126&errormessage=&payretailers_method_name=Boleto&errorcode=0&payment_state=APPROVED&security=006d6189680b4fd9bd67cbf51920d86b4846c56bae1d8062d39a8c4eedd44cd7&orderid=Payabl-Test&psp_transaction_id=XXXXXXXXXXXX2872&transactionid=215438976&type=capture" "https://www.notification_url"

Notification example with error:

payment_state=FAILED

"payment_state=FAILED&transactionid=215438977&orderid=Payabl-Test&psp_transaction_id=XXXXXXXXXXXX2916&timestamp=1666089637&payment_method=126&acquirer_id=8b8853fa-8e85-4c2e-a3ad-d333cdbeee1b&errorcode=-5002&security=9de4e59e78a41de50287060b18eb27db629e1c0fc9f789f9971f4684884b63e5&errormessage=Payment+failed&type=order&payretailers_method_name=Boleto&national_id=13475444534" "https://www.notification_url"

If the customer initiated the transaction but never completed it, you will receive a failed notification with payment_state=EXPIRED

"security=ca7446890c9522b2eaabf920233b64a94ebfb5d8f1590f65c6095386e190674d&acquirer_id=5b1ed573-fe6e-41b0-8d41-4e2f60271620&payretailers_method_name=Boleto&orderid=Payabl-Test&national_id=13475444534&errorcode=-5003&errormessage=Payment+aborted+by+customer&type=order&timestamp=1666089907&psp_transaction_id=XXXXXXXXXXXX2929&transactionid=215438978&payment_method=126&payment_state=EXPIRED" "https://www.notification_url"

Payouts

The method allows merchants to send funds to a bank account via wire transfer. In order for this to be done, the merchant needs to submit the bank details of the customer.

N.B.: Payouts can only be sent to the banks of this list: https://bank-codes.es/swift-code/brazil/

Include in request:

Field

Value Format

Accepted Values

merchantid

String

[A-Z][0-9]

amount

Float

0.00

currency

String

BRL

orderid

String

[0-9]

language

String

en

lastname

String

[A-Z]

street

String

zip

String

[A-Z][0-9]

city

String

[A-Z]

country

String

Country Code

firstname

String

[A-Z]

state

String

[A-Z]

email

String

[A-Z][0-9][-&_]@[A-Z][0-9].[A-Z]

custom1

optional

String

custom2

optional

String

custom3

optional payment reason

String

payment_method

String

126
Payment Method Id

phone

String

[0-9]

accounttype

String

Account Type

accountagencynumber

String

Account Agency

nationalid

String

[A-Z][0-9]

bankname

String

Bank Name

accountnumber

String

[A-Z][0-9]

testmode

only for testing

String

true

testmodecallbackstatus

only for testing

String

[PENDING-PROCESSED-ACCEPTED-FINISHED-ERROR]

signature

String

Request string:

POST /powercash21-3-2/backoffice/payment_cft

merchantid=ala&amount=70&currency=BRL&orderid=Inatec-Test&language=en&lastname=Mann&street=Address+4&zip=60322&city=Sao+Pablo&country=BRA&firstname=Muster&state=HE&email=test%40inatec.com&custom1=&custom2=&custom3=payment+reason&payment_method=126&phone=43543435435&accounttype=0001&accountagencynumber=8585&nationalid=134.754.445-34&bankname=341&accountnumber=0001&testmode=true&testmodecallbackstatus=FINISHED&signature=3b7ef21563379421b18492ef27376588b2de82c2
  1. Response:
transactionid=215439104&transid=215439104&status=2000&errormessage=pending&errmsg=pending&amount=70&price=70&currency=BRL&orderid=Inatec-Test&payment_method=126

1.1 Error

transactionid=215439105&transid=215439105&status=-6103&errormessage=Wrong%20currency&errmsg=Wrong%20currency&amount=70&price=70&currency=USD&orderid=Inatec-Test&payment_method=126

1.2 Pending

"transactionid=215437556&transid=215437556&status=2000&errormessage=pending&errmsg=pending&amount=1230&price=1230&currency=BRL&orderid=Inatec-Test&payment_method=126""
  1. Notification:

2.1 Notification example with Error:

Updated about 2 months ago