Payment effectuation service
After consuming the transaction creation service and obtaining a NIT, it's possible to proceed to the next step of the flow: calling the payment effectuation service. This operation must also be consumed on payment with schedule flows. In this case, Carat Portal assures that the schedule will only be activated if the payment is confirmed.
Call details#
- Resource:
/v1/payments/{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 |
Examples#
Below are some examples of the payment effectuation service call using the cURL tool.
Payment with automatic confirmation#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Payment with late confirmation#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Payment with schedule#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Payment with stored card#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Payment with Via Certa Financiadora with financing plans#
Attention: It is important that in the creation of the transaction the
installmentis greater than1for installment.Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Payment with prefixes#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Payment Retry#
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Payment - Network Token#
Some card brands have a tokenization solution that offers the storage of cards in safes at the brand itself, in an encrypted form. This brand tokenization is intended to improve the security and quality of the transmitted card information, which leads to possible increases in the conversion of approval by issuing banks.
Request:
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response:
Response codes
See reference on API codes - response codes
Request parameters#
The table below describes the request parameters of the payment effectuation service:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
authorizer_id | Code of the authorizer on Carat Portal. Learn more. If this field wasn't sent during the transaction creation phase, it will become mandatory when consuming the payment effectuation service. | < 3 N | COND. |
customer_postal_code | User's postal code (CEP in Brazil). It must be sent for iCards via SiTef routed transactions, if the is_customer_postal_code_required field in card query service is marked as true. | < 8 N | COND. |
mcc | The MCC (Merchant Category Code) is a code that classifies the business by the type of goods or services it provides. | < 4 N | NO |
subacquirer_merchant_id | It is the merchant identification for the subacquirer. | < 22 N | NO |
| card | Card data. | ||
number | Customer's card number (PAN). Brand generated token (DPAN) for network token payment. Learn more | < 19 N | YES |
cryptogram | Cryptogram generated by the brand | = 28 A | Yes for network token payments |
expiry_date | Card expiry date in MMYY format. Its requirement depends on the selected acquirer. In most cases, this field is mandatory. | = 4 N | COND. |
security_code | Card security code. This field may not be mandatory if the company has an agreement in the contract established with the acquirers, only for payments of certain areas. However, it is possible to configure the mandatory field in the merchant settings, consult Carat support for more information. Important: a payment with schedule implies on storing the customer's card data on Carat Portal's environment. However, for security reasons, the security code cannot be stored. Therefore, the scheduled payments will always be executed without the security code. | < 5 N | COND. |
holder | Card holder name. Only mandatory for payments with e-Rede, GetNet WS and VR (SmartNet). | < 30 AN | COND. |
token | HASH of a card stored on Carat Portal. It's not allowed to send an ‘open' card number (number field) and a stored card (token field) on the same request. | = 88 AN | NO |
wallet_transaction_id | Digital wallet transaction ID. Currently, this functionality is only available to the Visa Checkout and VEE (via CardSE via SiTef) authorizer. It isn't allowed to send an ‘open' card number ( number field), a stored card (token field) and a wallet_transaction_id on the same request. | < 25 AN | NO |
initial_wallet_transaction_id | Informs if the wallet id (wallet_transaction_id) is being used for the first time. If so, send the value true, otherwise send false. | < 5 T/F | NO |
wallet_type | Field that specifies whether the transaction is processed with PAN or DPAN. If “type” is empty, the default value is PAN (non-tokenized card number). If there is a tokenized transaction, you must send the value “network_token”. | AN | NO |
| external_authentication | This element receives MPI authentication result fields. | ||
version | 3DS version used in the authentication process (only version 2 is currently being accepted). | < 1 AN | NO |
eci | Eletronic Commerce Indicator – Card holder authentication security level indicator. | < 3 N | NO |
reference_id | Identifier of the cardholder's authentication transaction, performed in an external service to Carat (In our Web Checkout, the reference_id is referenced by ds.transId in the 3DS authentication response). | < 40 N | NO |
cavv | Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data. | < 40 N | NO |
| acquirer | Data required only to specific acquirers / routings. | ||
financing_plan | Financing Plan code used for Via Certa Financiadora routed payments, only in case of installments plan with interest. | < 4 N | NO |
special_code | Conductor/Renner SiTef routings general use code. | < 6 N | NO |
recurrency | Flag that defines whether or not the payment is recurring. Accepted all routings via SiTef, Cielo e-Commerce, Global Payments WS, Stone WS, e.Rede REST and GetnetWS routings. In the case of a Stone WS recurrency, it is mandatory to send only one of the fields below, is_first_recurring OR is_subsequent_recurring. | < 5 T/F | NO |
recurrency_tid | First transaction's TID. This field tells the first and the subsequent transactions apart. Use only if it is a recurrent payment.This field is used only for e.Rede REST routings using the brands Visa or Mastercard and for GetnetWS routing. | < 16 AN | NO |
is_first_recurring | Flag used only for StoneWS routing. Indicates that the transaction is the first in a series of recurring transactions. | < 5 T/F | COND. |
is_subsequent_recurring | Flag used only for StoneWS routing. It indicates that the transaction is the second or nth of a series of recurring transactions, where n > 2. | < 5 T/F | COND. |
recurrency_original_amount | Original value of the transaction that started the recurrency. This value must be informed in all subsequent recurrences. Used only for recurrence. Field used only in BIN routing, mandatory when recurrence | < 18 AN | NO |
product_code | Product code. It is mandatory in routing via Marisa. | < 6 N | COND. |
terminal | Sitef terminal code. In absence Carat Portal will generate a random terminal code. | = 14 N | No |
company_code | Sitef company code. In absence Carat Portal will use company code from merchant configuration. | = 8 N | No |
authorization_number | Authorization number. Mandatory for Bradescard Voucher authorizer. | < 6 AN | COND. |
| acquirer.vouchers_filter[] | Choice of vouchers that will not be accepted. Options of "Vouchers": 01 - Food, 02 - Meal, 03 - Culture, 04 - Fuel, 05 - Benefit. Example: You do not want to accept Vouchers: Culture, Fuel, Benefit. You must send: "vouchers_filter": ["03", "04", "05"] | ||
| acquirer.prefixes | Element for sending SiTef prefixes, like CICLOS, CPLANO and VLRADD. If the prefix that was sent is not supported by card, Carat Portal will invalidate the transaction, preventing that a false impression of the use of a functionality is given. Example: { "key" : "value" } -> { "CICLO" : "01" } | ||
key | Prefix name. | < 1024 AN | NO |
value | Prefix value. | < 1024 AN | NO |
| acquirer.submerchant_split[] | It consists of an array for split payments, unique to BIN and Sipag routing, both via SiTef. It allows the division of parts of the total amount of the payment among other merchants. The maximum number of items allowed in this array is 5 items. | ||
submerchant_code | BIN/Sipag merchant code | < 51 AN | NO |
submerchant_amount | Transaction amount related to the merchant | < 12 N | NO |
| acquirer.card_on_file | It is intended for sending specific information such as card storage authorization, confirming that the cardholder has authorized the storage of the card. Learn more. | ||
usage | Identifies the usage. For instance, in case of storage authorization: authorized | < 11 AN | NO |
reason | Itentifies the reason. For instance, in case of storage authorization: card | < 11 AN | NO |
WARNING: The
terminalecompany_codeparameters must be used only for SiTef routings and must be sent simultaneously.
It is also necessary send a request to the Carat Portal Support Team for the permission Allows sending Company and SiTef Terminal via REST.
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 payment effectuation service:
| Parameter | Description | Format |
|---|---|---|
code | Carat Portal response code. Any code different from 0 means failure. Learn more. | < 4 N |
message | Carat Portal response message. | < 500 AN |
| payment | ||
authorizer_code | Authorizer response code. | < 10 AN |
authorizer_message | Authorizer response message. | < 500 AN |
status | Status of the payment transaction on Carat Portal. Learn more. | = 3 AN |
nit | Identifier of the payment transaction on Carat Portal. | = 64 AN |
order_id | Order code sent by the merchant on the creation of the transaction. | < 40 AN |
merchant_usn | Unique sequential number sent by the merchant on the creation of the transaction. | < 12 N |
amount | Total price of the purchase specified by the merchant (in cents) on the creation of the transaction. | < 12 N |
sitef_usn | Unique sequential number of the payment transaction on SiTef. | = 6 N |
esitef_usn | Unique sequential number of the payment transaction on Carat Portal. | = 15 N |
customer_receipt | Customer's receipt. | < 4000 AN |
merchant_receipt | Merchant's receipt. | < 4000 AN |
authorizer_id | Code of the authorizer used on the transaction. | < 4 N |
acquirer_id | Code of the acquirer used on the transaction. | < 4 N |
acquirer_name | Name of the acquirer used on the transaction. | < 100 AN |
authorizer_date | Payment authorization date returned by the authorizer in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03 | = 16 D |
authorization_number | Authorization number. | < 6 AN |
host_usn | Host USN. Caveat for effecting PIX payments. Learn more. | < 15 AN |
tid | ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef. | < 40 AN |
eci | Eletronic Commerce Indicator (security level indicator of the payment transaction via Cielo e-Commerce). | <3 AN |
payment_date | Payment authorization date on Carat Portal in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03 | = 16 D |
issuer | Issuer code returned by the authorizer. | < 5 AN |
authorizer_merchant_id | Affiliation code of the merchant on the authorizer. | < 100 AN |
xid | XID field returned on 3DS authentications or certain acquirers. | < 40 AN |
authentication_url | Authentication URL returned on payment with authentication flows. Only available to Cielo e-Commerce. | < 56 AN |
balance | Current balance after payments with Gift cards. | < 12 N |
recurrency_tid | First transaction's id (TID) on the card brand. Returned only if it is a recurrent payment. This field is used only for e.Rede REST routings using the brands Visa or Mastercard. | < 16 AN |
retryable_code | Reversibility indicator of a transaction whose authorization was denied by the authorizer. This field will be returned in the response to the card payment request and must be taken into account in the online store's transaction retry mechanism. Valid codes:01 – Reversible Denied Transaction, Retain Later.02 – Irreversible Denied Transaction, Non-Retentive. | = 2 N |
| payment.analysis | ||
code | Response code of the fraud analysis operation. | < 4 N |
message | Response message of the fraud analysis operation. | < 200 AN |
status | Status of the fraud analysis transaction on Carat Portal. This field can assume the following value:NOV – New.EXP – Expired.ACC – AcceptedREJ – RejectedREV – In reviewINV – Invalid | = 3 AN |
| schedule | ||
status | Status of the schedule on Carat Portal. Learn more. | = 3 AN |
sid | Schedule transaction identifier on Carat Portal. | = 64 AN |
schedule_usn | Unique sequential number of the schedule on Carat Portal. | = 15 N |
authorizer_id | Code of the authorizer to be used on the scheduled payments. In operations with tokenized card, if the authorizer is not informed, the authorizer code used in the card storage will be used. | = 4 N |
amount | Amount of the scheduled payments specified by the merchant (in cents) on the creation of the transaction. | < 12 N |
order_id | Order code sent by the merchant on the creation of the transaction. | < 40 AN |
merchant_usn | Unique sequential number sent by the merchant on the creation of the transaction. | < 12 N |
initial_date | Execution date of the first scheduled payment in DD/MM/YYYY format. | = 10 D |
next_date | Execution date of the next scheduled payment in DD/MM/YYYY format. | = 10 D |
number_of_times | Total quantity of scheduled payments. | < 3 N |
installments | Number of installments to be used on the scheduled payments. | < 2 N |
installment_type | Financing type to be used on the scheduled payments. | < 2 N |
soft_descriptor | Additional text that will be presented alongside the name of the establishment in the credit card invoice. This functionality is available to the acquirers Cielo e-Commerce, PayPal, e-Rede, ElavonWS and Stone. | < 30 AN |
show_times_invoice | For finite time schedules, send this field with value true if you want to add at the end of the soft_descriptor field the current times/number of times (e.g. Subscription 3/12). | < 5 T/F |
terminal_id | Terminal code used in the transaction | < 8 AN |
recurrency_tid | First transaction's id (TID) on the card brand. Returned only if it is a recurrent payment. This field is used only for e.Rede REST routings using the brands Visa or Mastercard. | < 16 AN |