Boleto Bancário
PPRO offers integrations with both Banco Bradesco and Banco Itaú for cash payments in Brazil. This section is an integration guide for both. Please refer to your PPRO contract for which banking partner to use.
Payment Method Properties
| Available country codes | BR |
| Processing (Presentation) currencies | BRL |
| Settlement currencies | BRL |
| Consumer currencies | BRL |
| Channel member tag | boletobradesco, boletoitau |
| Scheme name in the settlement file | Boleto Bradesco Direct, Boleto Itau Direct |
| Minimum transaction amount | BRL 0.02 |
| Maximum transaction amount | BRL 250,000.00 |
| Session timeout | Default: 5 days |
| Refund | Full and partial refunds are all available. |
| Refund Validity | 365 days |
| Chargeback | No |
| Integration Type | Asynchronous |
| Sandbox | PPRO-hosted |
Transaction Flow
- On the merchant's checkout page, the consumer selects Boleto Bancário as their preferred payment method.
- The consumer is presented with a slip containing the amount, payment identifier and information about the payment.
- The consumer prints the payslip or writes down the reference number.
- The consumer is redirected back to the merchant.
- At one of the supported locations, the consumer presents the payslip/reference number and pays the order amount.
- PPRO receives a payment confirmation and notifies the partner/merchant about the payment status.
- The merchant is notified of the payment status and can ship the goods.
Boleto Bancário Integration
Specific input parameters for the TRANSACTION call
| Field Name | M/O/C | Type | Description |
|---|---|---|---|
specin.beneficiary | O | utf-8 | Bradesco-only The beneficiary of the payment - for example, the merchant’s name and order number |
specin.billingcity | M | utf-8 | City of the billing address (2-30 characters) |
specin.billingpostcode | M | numeric | 8 digit post code of the billing address |
specin.billingstate | M | ascii | Brazilian state of the billing address; 2 letter-code |
specin.billingstreet | M | utf-8 | Street of the billing address (2-50 characters) |
specin.duedate | O | ascii | Due date in YYYY-MM-DD format. Defaults to NOW + 3 days |
specin.email | M | utf-8 | RFC compliant email address of the account holder |
specin.nationalid | M | ascii | Consumer’s CPF or CNPJ tax id |
specin.rendertype | O | ascii | How the Boleto will be rendered: as PDF or HTML. Default: PDF |
transientin.merchantlogourl | O | ascii | Bradesco-only The URL of the logo to be displayed on the payment page. Max logo size: W=1200, H=627. Max URL characters is 255. |
This payment method supports the dynamic descriptor field (see The dynamic descriptor).
For standard input parameters, check Input parameters for the TRANSACTION call.
Important
Boleto Bancário Domestic BRL Processing (Brazil) requires a Brazilian entity for settlement. Contact your account manager for more information.
Important
This payment method requires the real account holder value for the
accountholdernameparameter.
Specific output parameters for the TRANSACTION call
| Field Name | Type | Description |
|---|---|---|
SPECOUT.DUEDATE | numeric | If the Payment Service Provider enters the SPECIN.DUEDATE, they receive the SPECOUT.DUEDATE with the same values. If no SPECIN.DUEDATE is set, the PSP receives the default timeout as defined in the Clearing Contract (maximum time = 13 days). |
TRANSIENTOUT.DOCUMENT | ascii | For successful requests: the URL of the Boleto document. |
SPECOUT.DOCUMENTCODE | numeric | Bradesco-only: The numeric identifier of the Boleto. For example, the consumers can use this identifier to pay the Boleto with a banking app. |
For standard output parameters, check Output parameters for the TRANSACTION call.
Specific input parameters for the REFUND call
| Field Name | M/O | Type | Description |
|---|---|---|---|
specin.accountnumber | M | numeric | The consumer’s bank account number |
specin.bankagency | M | numeric | The consumer’s bank agency number |
specin.bankname | M | numeric | The consumer’s bank name (minimum length of two characters) |
TRANSACTION call input
tag=boletoitau
&txtype=TRANSACTION
&countrycode=BR
¤cy=BRL
&amount=10000
&merchanttxid=VkHvWj5bAf6U
&login=johndoe
&password=wXBrpVporFVjGO4R
&contractid=JOHNDOECONTRACT
&channel=testchannel
&merchantredirecturl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Flanding.php
¬ificationurl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Fnotification.php
&specin.dynamicdescriptor=DynDescriptor
&accountholdername=John%20Doe
&specin.beneficiary=Bob%20Bacon
&specin.billingcity=Sao%20Paolo
&specin.billingpostcode=01234567
&specin.billingstate=SP
&specin.billingstreet=123%20Street%20Street
&specin.duedate=
&specin.email=test%40gmx.de
&specin.nationalid=93248261668
&returnmode=urlencodeext
tag=boletobradesco
&txtype=TRANSACTION
&countrycode=BR
¤cy=BRL
&amount=10000
&merchanttxid=rwFxEsubP5YE
&login=johndoe
&password=wXBrpVporFVjGO4R
&contractid=JOHNDOECONTRACT
&channel=testchannel
&merchantredirecturl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Flanding.php
¬ificationurl=https%3A%2F%2Fmerchant.com%2Fwork%2Fppro2%2Fnotification.php
&specin.dynamicdescriptor=DynDescriptor
&accountholdername=John%20Doe
&specin.beneficiary=Bob%20Ross
&specin.billingcity=Sao%20Paolo
&specin.billingpostcode=01234567
&specin.billingstate=SP
&specin.billingstreet=123%20Street%20Street
&specin.duedate=
&specin.email=test%40gmx.de
&specin.nationalid=93248261668
&returnmode=urlencodeext
TRANSACTION call output
REQUESTSTATUS=SUCCEEDED
&STATUS=SUCCEEDED
&TXID=816139903
&ERRMSG=
&CHANNEL=testchannel
&TAG=boletoitau
&PAYMENTGUARANTEE=NONE
&REDIRECTSECRET=Ag988okoc3sFYXZzUHs2C9Zr6kmpFjph
&SPECOUT_DOCUMENTCODE=23790001246004987209031123456704579990000010000
&SPECOUT_REDIRECTOPTIONAL=1
REQUESTSTATUS=SUCCEEDED
&STATUS=SUCCEEDED
&TXID=785862375
&ERRMSG=
&CHANNEL=testchannel
&TAG=boletobradesco
&PAYMENTGUARANTEE=NONE
&REDIRECTSECRET=1Glm00HEDTDuJMaK9pJnvmr5yaw8vdo7
&SPECOUT_DOCUMENTCODE=23790001246004987209031123456704579990000010000
&SPECOUT_REDIRECTOPTIONAL=1
Additional Information
Payment Description character limit
The payment description in the specin.dynamicdescriptor must be:
Itaú: Maximum 3 lines of text up to 60 characters each
Bradesco: Maximum 10 lines of text up to 60 characters each
Lines can be split by using a carriage return (enter key).
A word-wrap algorithm splits the text when you exceed the maximum number of lines or don't split the lines.
About the account holder name
The account holder name passed in the request must follow the format . The minimum length is 2 character per name. Multiple first names are accepted.
Example:
John Dorian
William Charles Dickinson (Where "William Charles" is the first name)
The system does not accept the request if these conditions are not met.
Scenarios for using the specin.duedate parameter
Setting a value for specin.duedate does not affect the default timeout of 3 days for the payment. The following use cases apply:
specin.duedate value is lower than the timeout value
In this use case, you define a more aggressive due date. If the value of specin.duedate is lower than the timeout value, a consumer not paying by the due date will not affect when PPRO sends a timeout. PPRO still sends the timeout at 3 days, as defined above.
We recommend you track the due date expiring based on the local timezone on the desired day at 23:59:59. Ignore the PPRO timeout.
specin.duedate value is greater than the timeout value
In this use case, you define a less aggressive due date. If the value of specin.duedate is greater than the timeout value, PPRO will still send the timeout message at 3 days, as defined above. This means that a consumer may successfully pay after the PPRO timeout is sent. This causes a scenario where PPRO sends a second notification to the notification URL indicating a payment's success. This is the "succeeded after failed" scenario.
We recommend you track the due date expiring based on the local timezone on the desired day at 23:59:59. Ignore the PPRO timeout.
Updated about 1 year ago