External origin payment confirmation service
Introduction#
The external origin payment confirmation functionality allows that a payment transaction created outside of Carat Portal can be confirmed inside of Carat Portal.
Currently this functionality allows payment transaction confirmation done in SiTef.
This operation is divided in two steps:
- The creation of a transaction of “Confirmation” type that represents the payment transaction externally created.
- The confirmation of the payment of this transaction.
Case of success
The flow below shows the happy path where a transaction is started and then the confirmation is sent.
External origin payment confirmation transaction creation#
Call details#
- Resource:
/v1/transactions - HTTP Method:
POST - Request format:
JSON - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Carat Portal store's ID. Production and certification IDs are different. | ≤ 15 A | YES |
merchant_key | Store authentication key in Carat Portal. Production and certification keys are different. | < 80 A | YES |
Content-Type | Fixed value "application/json" | = 15 A | YES |
Example#
Request
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response
Request parameters#
The table below shows fields for the creation of external origin payment confirmation transaction.
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
amount | Total purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas | < 12N | YES |
merchant_usn | Unique sequential id for each order created by the store. NSU will be used in all communication with the store to identify the order. As this is a store-side access key, although it is optional for Carat Portal, 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 merchant. It should be different at each request to facilitate traceability. If the store's integration with the acquirer/routing networks (Cielo, Redecard, etc) is via SiTef (TEF), the field orderId, which has a maximum length of 40 characters, will be shortened to 12 characters due to a SiTef restriction. This reduction will be performed by keeping the characters from left to right (eg if an order code entered is 12345678901234567890 in Carat Portal, in SiTef it will only be 123456789012). | < 40 AN | NO |
transaction_type | Fixed value confirmation | = 15 A | YES |
is_transaction_origin_external | Fixed value true | = 5 AN | YES |
Response parameters#
In case of success, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes de response parameters of the transaction creation 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 | ||
status | Status of the payment transaction on Carat Portal. Learn more. | = 3 AN |
nit | Payment transaction identifier 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 |
External origin payment confirmation transaction effectuation#
Call details#
- Resource:
/v1/payments/{nit} - HTTP Method:
PUT - Request format:
JSONandquery string - Response format:
JSON - Header parameters:
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
merchant_id | Carat Portal store's ID. Production and certification IDs are different. | ≤ 15 A | YES |
merchant_key | Store authentication key in Carat Portal. Production and certification keys are different. | < 80 A | YES |
Content-Type | Fixed value "application/json" | = 15 A | YES |
Example#
Request
To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br
Response
Request parameters - query string#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
confirm | This field must be sent with the value true if you want to confirm the payment, or false if you want to undo the payment. | < 5 T/F | YES |
Request parameters - JSON#
| Parameter | Description | Format | Mandatory |
|---|---|---|---|
amount | Total purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas. If not informed, the value informed in the transaction creation is used. | < 12N | NO |
authorizer_id | Code of the authorizer on Carat Portal. It must be the same value sent on the pre autorization. | < 3 N | YES |
installments | Number of installments. Send 1 for spot sales. | < 2 N | NO(*) |
installment_type | Installment financing type: Value 3 = installments with interest. Value 4 = installments without interest (use this value also on spot sales). Value 6 = installments with interest (IATA). Value 7 = installments without interest (IATA). The IATA financing types are only used by companies that work with air transportation. | < 2 N | NO(*) |
confirmation_data | Payment information returned by SiTef after effectuating a payment. This parameter is fundamental for the success of the confirmation. It is used by SiTef to identify the payment. | < 128 AN | NO |
| acquirer | |||
routing_id | Routing information used by the payment done outside of Carat Portal. This parameter is fundamental for the success of the confirmation. It is used to identify the routing inside of SiTef. | < 5 N | YES |
host_usn | Host/authorizer USN of the transaction to be confirmed. | = 9 N | NO(*) |
authorization_number | Authorization number of the transaction to be confirmed. | < 6 N | NO(*) |
authorizer_date | Pre-authorization date returned by the authorizer in DD/MM/YYYY format. | = 10 D | NO(*) |
order_id | Order code used in the pre-authorization initiated outside Carat Portal. | < 40 AN | NO(*) |
identification_number | CPF or CNPJ used in the pre-authorization initiated outside Carat Portal. | < 20 AN | NO(*) |
terminal | SiTef terminal code. In absence Carat Portal will generate a random terminal code. | = 8 AN | NO(*) |
company_code | SiTef company code. In absence Carat Portal will use company code from merchant configuration. | = 8 N | NO(*) |
Note: All fields marked with
NO(*)are optional and, if informed, Carat Portal will not be able to consist any one of them because they are not sent to SiTef in the confirmation operation.
Response parameters#
If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes the response parameters of the payment confirmation 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 | ||
status | Status of the payment transaction on Carat Portal. Learn more. | = 3 AN |
host_usn | Host USN. | < 15 AN |
payment_date | Payment authorization date on Carat Portal in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03 | = 16 D |