# 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 1. Successfully generated the _boleto_. 2. The Payment Transaction will remain in 'Processed' status. 3. 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](pagamento-rest-begin.md) Ex: ```json { "merchant_usn": "7112400307", "order_id": "07112400307", "amount": "2400", "installments": "1", "installment_type": "4", "authorizer_id": "2601", "additional_data": { "payer": { "name": "Steve", "surname": "Harris", "address": { "zip_code": "01307001", "street_number": "35", "street_name": "Avenida Paulista", "complement": "Ap 10", "district": "bela vista", "city": "São Paulo", "state": "SP", "country": "BR" }, "documents": [ { "type": "CPF", "number": "60861648005" } ] }, "boleto": { "assignor_code": "99999999999999999999", "your_number": "1646940087", "expiration_date": "20/03/2022", "issue_date": "10/03/2022", "specie_type": "01", "company_identification": "identificacao_empresa", "assignor": "XPTO COMPUTADORES DO BRASIL LTDA", "assignor_document": { "type": "CNPJ", "number": "72381189000110" }, "assignor_address": { "zip_code": "01307001", "street_number": "999", "street_name": "Avenida YYZ", "complement": "Ap 3000", "district": "bela vista", "city": "São Paulo", "state": "SP", "country": "BR" }, "instructions": [ { "message": "ficha_compensacao msg1" }, { "message": "ficha_compensacao msg2" } ], "receipt_messages": [ { "message": "recibo msg1" }, { "message": "recibo msg2" } ] } } } ``` ### Payment Effectuation ### More details in topic [Payment effectuation](pagamento-rest-dopayment.md) 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: ```json { "authorizer_id": "2601" } ``` Ex response: ```json { "code": "0", "message": "OK. Transaction successful.", "payment": { "authorizer_message": "OK", "status": "PRO", "nit": "9901701cc1631cf6fc71a38b0a6e8dba8b8130f2ad1c3109643753223dba312b", "order_id": "07112400307", "authorizer_id": "2601", "acquirer_id": "2601", "acquirer_name": "Boleto Citibank", "merchant_usn": "7112400307", "esitef_usn": "220310093364750", "amount": "2400", "payment_type": "B", "payment_date": "10/03/2022T16:29", "boleto": { "digitable_line": "47720953885052730207262219741330432820197130661", "url": "https://esitef-homologacao.softwareexpress.com.br/e-sitef/reissue.se?nit=9901701cc1631cf6fc71a38b0a6e8dba8b8130f2ad1c3109643753223dba312b" } } } ``` ## Web Checkout ## ### Transaction creation ### More details in topic [Transaction creation](pagamento-html-begin.md) Ex: ```json { "merchant_id": "BOLETOCITI", "merchant_usn": "7112400307", "order_id": "07112400307", "amount": "2400", "installments": "1", "installment_type": "4", "authorizer_id": "2601", "additional_data": { "payer": { "name": "Steve", "surname": "Harris", "address": { "zip_code": "01307001", "street_number": "35", "street_name": "Avenida Paulista", "complement": "Ap 10", "district": "bela vista", "city": "São Paulo", "state": "SP", "country": "BR" }, "documents": [ { "type": "CPF", "number": "60861648005" } ] }, "boleto": { "assignor_code": "99999999999999999999", "your_number": "1646940087", "expiration_date": "17/08/2022", "issue_date": "10/03/2022", "specie_type": "01", "company_identification": "identificacao_empresa", "assignor": "XPTO COMPUTADORES DO BRASIL LTDA", "assignor_document": { "type": "CNPJ", "number": "72381189000110" }, "assignor_address": { "zip_code": "01307001", "street_number": "999", "street_name": "Avenida YYZ", "complement": "Ap 3000", "district": "bela vista", "city": "São Paulo", "state": "SP", "country": "BR" }, "instructions": [ { "message": "ficha_compensacao msg1" }, { "message": "ficha_compensacao msg2" } ], "receipt_messages": [ { "message": "recibo msg1" }, { "message": "recibo msg2" } ] } } } ``` ### 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:///e-sitef/reissue.se?nit=XXX | | **UAT environment** | | https:///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 (or 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.