Payment Facilitator
Overview#
This item will present features for routing transactions in the Payment Facilitator via acquiring processed by Fiserv.
Attention: To operate as a Payment Facilitator, you will need to have a PFAC ID with the brands, sign a contract with the acquirer and request access to the specific environment for testing.
Establishments that operate as Payment Facilitators intermediate other establishments (submerchants) to accept electronic payments at the acquirer. To operate in this mode, it will be necessary to request configuration on the register and transmit specific information about the operations of your submerchants according to instructions.
Payment#
- Resource:
/e-sitef/api/v2/payments/ - HTTP Method:
POST - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | It must be sent with the value application/json. | = 15 AN | YES |
Example#
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Request:
Request parameters
The table below describes the transaction creation service request parameters:
| Parameter | Description | Format | Required |
|---|---|---|---|
merchant_usn | Unique sequential number for each order, created by the store. The NSU will be used in all communication with the store, in order to identify the order. As this is a possible key for store-side access, despite being optional for Carat, it is strongly recommended that the field be formatted and sent by the store application. | 12 N | NO |
order_id | Order code to be displayed to the buyer, defined by the retailer. It is advisable that it is different for each order to facilitate traceability. If the integration of the Store with acquiring networks (Cielo, Redecard, etc.) is with Carat and SiTef* *, the orderId field, which has a maximum length of 40 characters, will be reduced to 12 characters, due to a SiTef** restriction. This reduction will be carried out keeping the characters from left to right (e.g. if an order code entered is 12345678901234567890 in Carat, in SiTef it will only be 123456789012). | < 40 AN | NO |
installments | Number of installments. Send ‘1’ for cash transactions. | 2 N | YES |
installation_type | Type of installment financing: value 3 = interest-free installments from the card administrator. value 4 = interest-free installments made by the store (adopt this value as standard/default for cash transactions). br/>Value 6 = interest-free installments from the administrator (IATA). value 7 = interest-free installments made by the store (IATA). IATA installments are only used by air transport companies . | 2 N | YES |
authorizer_id | Authorizer code in Carat. Learn more. | 3 N | NO |
amount | Total purchase value (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send the value without the comma and period. | ||
soft_descriptor | Additional text that will be displayed next to the name of the establishment on the buyer's credit card statement. Learn more | < 25 AN | YES |
| card | Card details. | ||
expiry_date | Card expiration date in MMYY format. | < = 4 N | COND. |
security_code | Card security code | < < 5 N | COND. |
number | Buyer's card number (PAN). | < 5 T/F | NO |
holder | Buyer's name | < 40 AN | YES |
| additional_data | Elemento para envio de dados adicionais. | ||
mcc | Merchant Category Code | < = 4 N | YES |
| subacquirer_merchant | Sub-acquirer merchant data | ||
id | Establishment ID | = 15 N | YES |
address | Address of the subseller | < 120 AN | YES |
city | City | < 20 AN | YES |
state | UF | < 30 AN | YES |
country | Country according to ISO 3166 numeric code | < 3 N | YES |
zip_code | Zip code | < 8 N | YES |
identification_number | Subseller's Identification number | < 18 N | YES |
payment_facilitator_id | Facilitator's code. (If it does not reach 11 characters, add zeros to the left) | = 11 N | YES |
payment_facilitator_url | Facilitator's URL | < 76 AN | YES |
phone_number | Phone number | < 15 N | YES |
Response:
Response parameters
If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes the response parameters of the transaction creation service:
| Parameter | Description | Format |
|---|---|---|
code | Carat response code. Any code other than 0 means failure. Learn more. | 4 N |
message | Carat response message. | < 500 AN |
| payment | ||
authorizer_code | Authorizer response code. | < 10 AN |
authorizer_message | Authorizer response message. | < 500 AN |
status | Payment transaction status in Carat. Learn more. | = 3 AN |
nit | Identifier of the payment transaction in Carat. | = 64 AN |
order_id | Order code sent by the store when creating the transaction. | < 40 AN |
customer_receipt | Coupon (via customer). | < 4000 AN |
merchant_receipt | Coupon (via establishment). | < 4000 AN |
authorizer_id | Authorizer code used in the transaction. | 4 N |
acquirer_id | Acquirer code used in the transaction. | 4 N |
acquirer_name | Name of the acquirer used in the transaction. | < 100 AN |
authorizer_date | Payment effective date returned by the authorizer in the format DD/MM/YYYY'T'HH:mm. Example: 07/13/2017T16:03 | = 16D |
authorization_number | Authorization number. | < 6 AN |
merchant_usn | Unique sequential number sent by the store when creating the transaction. | 12 N |
esitef_usn | Unique sequential number of the payment transaction in Carat. | = 15 N |
sitef_usn | Unique sequential number of the payment transaction in SiTef. | = 6 N |
host_usn | NSU of the authorizer. Reservation for making PIX payments | < 15 AN |
amount | Purchase value specified by the store (in cents) when creating the transaction. | 12 N |
payment_type | Type of payment from the chosen authorizer: B = bank slip, C = credit, D = debit, P = pure Private Label credit card, T = bank transfer, G = gift card, O = other payment methods, W = Boleto NR via Web Service | = 1 AN |
terminal_id | Terminal code used in the transaction | 8 N |
payment_date | Payment date in Carat in the format DD/MM/YYYY'T'HH:mm. Example: 07/13/2017T16:03 | = 16D |
Pre-Authorization#
- Resource:
/e-sitef/api/v2/preauthorizations/ - HTTP Method:
POST - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | It must be sent with the value application/json. | = 15 AN | YES |
Example#
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Request:
Request parameters
| Parameter | Description | Format | Required |
|---|---|---|---|
merchant_usn | Unique sequential number for each order, created by the store. The NSU will be used in all communication with the store, in order to identify the order. As this is a possible key for store-side access, despite being optional for Carat, it is strongly recommended that the field be formatted and sent by the store application. | 12 N | NO |
order_id | Order code to be displayed to the buyer, defined by the retailer. It is advisable that it is different for each order to facilitate traceability. If the integration of the Store with acquiring networks (Cielo, Redecard, etc.) is with Carat and SiTef* *, the orderId field, which has a maximum length of 40 characters, will be reduced to 12 characters, due to a SiTef** restriction. This reduction will be carried out keeping the characters from left to right (e.g. if an order code entered is 12345678901234567890 in Carat, in SiTef it will only be 123456789012). | < 40 AN | NO |
installments | Number of installments. Send ‘1’ for cash transactions. | 2 N | YES |
installation_type | Type of installment financing: value 3 = interest-free installments from the card administrator. value 4 = interest-free installments made by the store (adopt this value as standard/default for cash transactions). br/>Value 6 = interest-free installments from the administrator (IATA). value 7 = interest-free installments made by the store (IATA). IATA installments are only used by air transport companies . | 2 N | YES |
authorizer_id | Authorizer code in Carat. Learn more. | 3 N | NO |
amount | Total purchase value (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send the value without the comma and period. | ||
soft_descriptor | Additional text that will be displayed next to the name of the establishment on the buyer's credit card statement. Learn more | < 25 AN | NÃO |
| card | Card details. | ||
expiry_date | Card expiration date in MMYY format. | < = 4 N | COND. |
security_code | Card security code . | < < 5 N | COND. |
number | Buyer's card number (PAN). | < 5 T/F | NO |
holder | Merchant Name | < 40 AN | YES |
| additional_data | Elemento para envio de dados adicionais. | ||
mcc | Merchant Category Code | < = 4 N | YES |
| subacquirer_merchant | Establishment ID | ||
id | Código de estabelecimento do subadquirente | = 15 N | YES |
address | Address of the establishment | < 120 AN | YES |
city | City | < 20 AN | YES |
state | State | < 30 AN | YES |
country | Country according to ISO 3166 numeric code | < 3 N | YES |
zip_code | Zip code | < 8 N | YES |
identification_number | Subseller's Identification number | < 18 N | YES |
payment_facilitator_id | Facilitator's code. (If it does not reach 11 characters, add zeros to the left) | = 11 N | YES |
payment_facilitator_url | Facilitator's URL | < 76 AN | YES |
phone_number | Phone number | < 15 N | YES |
Response:
Response parameters
| Parameter | Description | Format |
|---|---|---|
code | Carat response code. Any code other than 0 means failure. Learn more. | 4 N |
message | Carat response message. | < 500 AN |
| pre_authorization | ||
authorizer_code | Authorizer response code. | < 10 AN |
status | Payment transaction status in Carat. Learn more. | = 3 AN |
nit | Identifier of the payment transaction in Carat. | = 64 AN |
order_id | Order code sent by the store when creating the transaction. | < 40 AN |
customer_receipt | Coupon (via customer). | < 4000 AN |
merchant_receipt | Coupon (via establishment). | < 4000 AN |
authorizer_id | Unique sequential number sent by the store when creating the transaction. | 12 N |
acquirer_id | Acquirer code used in the transaction. | 4 N |
acquirer_name | Name of the acquirer used in the transaction. | < 100 AN |
authorizer_date | Payment effective date returned by the authorizer in the format DD/MM/YYYY'T'HH:mm. Example: 07/13/2017T16:03 | = 16D |
authorization_number | Authorization number. | < 6 AN |
merchant_usn | Unique sequential number sent by the store when creating the transaction. | 12 N |
esitef_usn | Unique sequential number of the payment transaction in Carat. | = 15 N |
sitef_usn | Unique sequential number of the payment transaction in SiTef. | = 6 N |
host_usn | NSU of the authorizer. Reservation for making PIX payments | < 15 AN |
amount | Purchase value specified by the store (in cents) when creating the transaction. | 12 N |
payment_type | Type of payment from the chosen authorizer: B = bank slip, C = credit, D = debit, P = pure Private Label credit card, T = bank transfer, G = gift card, O = other payment methods, W = Boleto NR via Web Service | = 1 AN |
terminal_id | Terminal code used in the transaction | 8 N |
payment_date | Payment date in Carat in the format DD/MM/YYYY'T'HH:mm. Example: 07/13/2017T16:03 | = 16D |
Capture#
- Resource:
/e-sitef/api/v1/preauthorizations/capture/{{nit}} - HTTP Method:
POST - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | It must be sent with the value application/json. | = 15 AN | YES |
Example#
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Request:
Request parameters
| Parameter | Description | Format | Required |
|---|---|---|---|
amount | Total purchase value (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send the value without the comma and period. | < 12 N | SIM |
installments | Number of installments. Send ‘1’ for cash transactions. | < 2 N | SIM |
installment_type | Type of installment financing: value 3 = interest-free installments from the card administrator. value 4 = interest-free installments made by the store (adopt this value as standard/default for cash transactions). br/>Value 6 = interest-free installments from the administrator (IATA). value 7 = interest-free installments made by the store (IATA). IATA installments are only used by air transport companies. | < 2 N | SIM |
soft_descriptor | Additional text that will be displayed next to the name of the establishment on the buyer's credit card statement. Learn more | < 25 AN | NÃO |
| subacquirer_merchant | Sub-acquirer merchant data | ||
id | subseller ID | = 15 N | Sim |
address | Address of the subseller | < 120 AN | Sim |
city | City | < 20 AN | Sim |
state | State | < 30 AN | Sim |
country | Country according to ISO 3166 numeric code | < 3 N | Sim |
zip_code | Zip code | < 8 N | Sim |
identification_number | Subseller's Identification number | < 18 N | Sim |
payment_facilitator_id | Facilitator's code. (If it does not reach 11 characters, add zeros to the left) | = 11 N | Sim |
payment_facilitator_url | Facilitator's URL | < 76 AN | Sim |
phone_number | Phone number | < 15 N | Sim |
mcc | Merchant Category Code | < = 4 N | Sim |
Response:
Response parameters
| Parameter | Description | Format |
|---|---|---|
code | Carat response code. Any code other than 0 means failure. Learn more. | 4 N |
message | Carat response message. | < 500 AN |
| capture | ||
authorizer_code | Authorizer response code. | < 10 AN |
authorizer_message | Authorizer response message. | < 500 AN |
status | Payment transaction status in Carat. Learn more. | = 3 AN |
nit | Identifier of the payment transaction in Carat. | = 64 AN |
order_id | Order code sent by the store when creating the transaction. | < 40 AN |
customer_receipt | Coupon (via customer). | < 4000 AN |
merchant_receipt | Coupon (via establishment). | < 4000 AN |
authorizer_id | Unique sequential number sent by the store when creating the transaction. | 12 N |
acquirer_id | Acquirer code used in the transaction. | 4 N |
acquirer_name | Name of the acquirer used in the transaction. | < 100 AN |
authorizer_date | Payment effective date returned by the authorizer in the format DD/MM/YYYY'T'HH:mm. Example: 07/13/2017T16:03 | = 16D |
authorization_number | Authorization number. | < 6 AN |
merchant_usn | Unique sequential number sent by the store when creating the transaction. | 12 N |
esitef_usn | Unique sequential number of the payment transaction in Carat. | = 15 N |
sitef_usn | Unique sequential number of the payment transaction in SiTef. | = 6 N |
host_usn | NSU of the authorizer. Reservation for making PIX payments | < 15 AN |
amount | Purchase value specified by the store (in cents) when creating the transaction. | 12 N |
payment_type | Type of payment from the chosen authorizer: B = bank slip, C = credit, D = debit, P = pure Private Label credit card, T = bank transfer, G = gift card, O = other payment methods, W = Boleto NR via Web Service | = 1 AN |
Cancellation#
The cancellation process requires authentication with signature by default, see details in Online Payment | Cancellation and follow the request below. Note: For transactions already captured it will also be possible to use Asynchronous Cancellation, see details in Online Payment | Asynchronous Cancellation
- Resource:
/e-sitef/api/v2/cancellations/{{nit}} - HTTP Method:
POST - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Merchant code on Carat Portal. The production and certification codes will be different. | < 15 AN | YES |
merchant_key | Merchant authentication key on Carat Portal. The production and certification keys will be different. | < 80 AN | YES |
Content-Type | It must be sent with the value application/json. | = 15 AN | YES |
Authorization | Merchant's signature in the Bearer {signature} format. Example: Bearer JHVGytfdgauygdauiw78264284527852897hagdg. This parameter is mandatory, unless the Merchant has enabled mutual authentication (mTLS) along with Carat. | < 2000 AN | COND. |
Example#
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Request:
Request parameters
| Parameter | Description | Format | Required |
|---|---|---|---|
amount | Total purchase value (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send the value without the comma and period. | 12 N | YES |
mcc | Merchant Category Code | = 4 N | Yes |
| subacquirer_merchant | Sub-acquirer merchant data | ||
id | Establishment ID | < 120 AN | Yes |
address | Address of the establishment | < 120 AN | Yes |
city | City | < 20 AN | Yes |
state | UF | < 30 AN | Yes |
country | Country according to ISO 3166 numeric code | ||
zip_code | Zip code | < 8 N | Sim |
identification_number | Subseller's Identification number | < 18 N | Sim |
payment_facilitator_id | Facilitator's code. (If it does not reach 11 characters, add zeros to the left) | = 11 N | Sim |
payment_facilitator_url | Facilitator's URL | < 76 AN | Sim |
phone_number | Phone number | < 15 N | Sim |
Response:
Response parameters
| Parameter | Description | Format |
|---|---|---|
code | Carat response code. Any code other than 0 means failure. Learn more. | 4 N |
message | Carat response message. | < 500 AN |
| cancellation | ||
authorizer_code | Authorizer response code. | < 10 AN |
authorizer_message | Authorizer response message. | < 500 AN |
status | Payment transaction status in Carat. Learn more. | = 3 AN |
nit | Identifier of the payment transaction in Carat. | = 64 AN |
order_id | Order code sent by the store when creating the transaction. | < 40 AN |
customer_receipt | Coupon (via customer). | < 4000 AN |
merchant_receipt | Coupon (via establishment). | < 4000 AN |
authorizer_id | Unique sequential number sent by the store when creating the transaction. | 12 N |
acquirer_id | Acquirer code used in the transaction. | 4 N |
acquirer_name | Name of the acquirer used in the transaction. | < 100 AN |
authorizer_date | Payment effective date returned by the authorizer in the format DD/MM/YYYY'T'HH:mm. Example: 07/13/2017T16:03 | = 16D |
authorization_number | Authorization number. | < 6 AN |
merchant_usn | Unique sequential number sent by the store when creating the transaction. | 12 N |
esitef_usn | Unique sequential number of the payment transaction in Carat. | = 15 N |
sitef_usn | Unique sequential number of the payment transaction in SiTef. | = 6 N |
host_usn | NSU of the authorizer. Reservation for making PIX payments | < 15 AN |
amount | Purchase value specified by the store (in cents) when creating the transaction. | 12 N |
payment_type | Type of payment from the chosen authorizer: B = bank slip, C = credit, D = debit, P = pure Private Label credit card, T = bank transfer, G = gift card, O = other payment methods, W = Boleto NR via Web Service | = 1 AN |
esitef_date | Effective date of cancellation in Carat in the format DD/MM/YYYY'T'HH:mm. Example: 07/13/2017T16:03 | = 16 D |
is_host_cancel | This field will return the value true in case of cancellation via the host. | 5 T/F |