Boleto Citibank
Carat allows payment of boletos through Citibank.
In this page, the nomenclature "Citibank" will be used to reference the acquirer on Carat Portal.
Carat Portal Interfaces Supported for Integration#
The following interfaces for integration with Boleto Citibank are available:
- REST payment
- HTML Payment
- Reprint of boletos
Required credentials#
The merchant must obtain with Citibank the credentials listed below, and pass them to Software Express.
| Field | Description | Format | Required |
|---|---|---|---|
codigoBeneficiario | Merchant agreement code at Citibank. | = 20 N | Yes |
codigoAgenciaBeneficiario | Merchant bank agency at Citibank | ≤ 5 N | Yes |
mensagemBeneficiario | Assignor's message. Do not use special character other than “/”, “-“ , “;” or "@". | ≤ 40 N | Yes |
The store may also request the configuration of some parameters of default values with Software Express.
| Field | Description | Format | Required |
|---|---|---|---|
quantidadeDiasCalculoVencimento | Number of days to calculate the standard expiration date. | ≤ 2 N | No |
mensagemReciboPagador | Default message displayed in boleto payment receipt. Note: up to two lines with a maximum of 40 characters. | ≤ 40 AN | No |
mensagemFichaCompensacao | Default message displayed in the boleto instructions. Note: up to two lines with a maximum of 40 characters. | ≤ 40 AN | No |
Citibank payemnt flow#
- Successfully generated the boleto.
- The Payment Transaction will remain in 'Processed' status.
- The merchant will receive from Citibank a file with the data of the slips and situation, informing if they were paid.
Payment REST#
Boleto payment follows the normal payment flow
Transaction creation#
More details in topic Transaction creation
Ex:
Payment Effectuation#
More details in topic Payment effectuation
The effectuation payment response delivers some unique data from the boleto payment
| Field | Description |
|---|---|
| payment.boleto | Boleto's payment exclusive fields |
digitable_line | Digitable line |
url | Boleto's url |
Ex request:
Ex response:
Web Checkout#
Transaction creation#
More details in topic Transaction creation
Ex:
Optional data in Web Checkout#
If the buyer's Name, Document and Address data are not sent, a form will be displayed for the buyer to fill out.
Mandatory fields#
So that the customer can make a boleto bancário payment, it's necessary that the store submits to Carat Portal the following information:
| Field | Description | Format | Mandatory |
|---|---|---|---|
| additional_data.payer | |||
name | Payer's name. Obs.: concatenation of first name with last name cannot exceed 255 characters. | < 200 AN | Yes |
surname | Payer's surname. Obs.: concatenation of first name with last name cannot exceed 255 characters. | < 200 AN | Yes |
| additional_data.payer.address | |||
street_name | Payer's adress. | < 150 AN | Yes |
street_number | Payer's adress number. | < 20 AN | Yes |
complement | Payer's adress complement. | < 100 AN | No |
zip_code | Payer's zip code. | < 8 N | Yes |
city | Payer's city. | < 50 AN | Não |
state | Payer's state. | = 2 AN | Não |
country | Payer's country AN 3166-1 format. Ex.: BRA | = 3 AN | No |
| additional_data.boleto | |||
assignor_code | Bank relationship number | = 20 N | No |
bank_issuer_code | Bank branch relationship number | < 7 AN | No |
boleto_number | Boleto's identification number. In absent it will be generated | < 14 N | No |
your_number | Number used and controlled by the merchant, to identify the boleto. | < 11 AN | No |
expiration_date | Boleto expiration date in the format dd/mm/aaaa. Note: If not sent, it will be generated based on the authorizer's default configuration | < 10 AN | No |
issue_date | Date of issue of the ticket in the format dd/mm/aaaa. Note: If not sent, it will be generated based on the current date | < 10 AN | No |
specie_type | Code adopted to identify the type of billing document: 01 - Cheque 02 - Trade Duplicate 03 - Trade Duplicate for Indication | = 02 N | Yes |
fine_date | Fine date | = 10 AN | No |
fine_amount | Amount in cents of the penalty for late payment. | < 12 AN | No |
fine_percentage | Percentage of fine to be applied on the value of the boleto, for late payment. | < 12 N | No |
company_identification | Field intended for use by the Beneficiary Company to identify the boleto. | < 25 AN | No |
iof_amount | IOF amount. | < 12 N | No |
assignor | Assignor's Name | < 40 AN | No |
| additional_data.payer.assignor_document | Assignor's document id. Note: If not sent, the merchant configured document will be used | ||
type | Assignor's document type | CPF or CPNJ | No |
number | Assignor's document id | < 14 N | No |
| additional_data.payer.assignor_address | Assignor's address. Note: If not sent, the merchant configured address will be used | ||
street_name | Assignor's address. | < 150 AN | Yes |
street_number | Assignor's address number. | < 20 AN | Yes |
complement | Assignor's address complement. | < 100 AN | No |
zip_code | Assignor's zip code | < 8 N | Yes |
city | Assignor's city | < 50 AN | No |
state | Assignor's state | = 2 AN | No |
| additional_data.boleto.instructions[] | |||
message | Text of observations intended for sending free messages, to be printed in the instructions field of the compensation form Note: If not sent, the default merchant configuration will be used | < 40 N | No |
| additional_data.boleto.receipt_messages[] | |||
message | Text of remarks intended for sending free messages, to be printed on the receipt of the payer's part of the ticket Note: If not sent, the default merchant configuration will be used | < 40 N | No |
| additional_data.boleto.payment | |||
allowed_quantity | Allowed payment quantity | < 2 N | No |
type | Payment type | < 35 AN | Yes |
minimum_amount | Minimum admissible payment amount. | < 12 N | No |
maximum_amount | Maximum admissible amount for payment. | < 12 N | No |
minimum_percentage | Value of the minimum percentage admissible for payment. | < 12 N | No |
maximum_percentage | Value of the maximum percentage admissible for payment. | < 12 N | No |
Reprint of boletos#
It is possible to make available to customers the reprint of Citibank boletos.
That functionality is available through the URL:
| Production environment |
|---|
| https://esitef.softwareexpress.com.br/e-sitef/reissue.se?nit=XXX |
| UAT environment |
| https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/reissue.se?nit=XXX |
The nit used in the original payment transaction, made via Citibank Boleto, must be informed as a GET parameter. Accessing this URL allows viewing the boleto.
If the payment transaction is not in the expected state, it is present an error message.
Attention
The IP address must never be used instead of the domain esitef.softwareexpress.com.br (or esitef-homologacao.softwareexpress.com.br for Certification and Test environment). The IP address can change at any moment without notice, so it is important to always use the domain to access Carat Portal.