External Origin Pre-Authorization Capture Service

This functionality consists in capture a transaction even if it isn't present in Carat Portal's databases.

Currently, this functionality only alows capture of pre-authorizations originated via SiTef.

This operation has one more step, in relation to a normal capture. The capture external origin transaction flow is started by consuming the beginTransaction operation, which will generate an Carat Portal record of a transaction with status = NOV, and return the nit parameter to the application, which will identify this transaction.

A nit has a usage time set in Carat Portal. If this timeout exceeds the transaction, it will go beyond status NOV to the status EXP. In this case it will no longer be allowed to use the same nit, being necessary to consume the beginTransaction operation again to generate another valid nit.

Capture external origin creation#

Call details#

  • Resource: /v1/transactions
  • HTTP Method: POST
  • Request format: JSON
  • Response format: JSON
  • Header parameters:
ParameterDescriptionFormatMandatory
Content-TypeFixed value "application/json"= 15 AYes
merchant_idCarat Portal store's ID. Production and certification IDs are different.≤ 15 AYes
merchant_keyStore authentication key in Carat Portal. Production and certification keys are different.< 80 AYes

Examples#

Below there are some examples of calling the pre-authorization creation service using the cURL tool.

Request:

To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://{{url}}/e-sitef/api/v1/transactions"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"order_id":"orderID",
"merchant_usn":"20190101",
"amount":"100",
"transaction_type":"capture",
"is_transaction_origin_external": "true"
}
--verbose

Response:

{
"code": "0",
"message": "OK. Transaction successful.",
"capture": {
"status": "NOV",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "orderID",
"merchant_usn": "20190101",
"amount": "100"
}
}

Request Parameter#

ParameterDescriptionFormatMandatory
amountTotal purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas< 12NYes
encrypted_cardThis field must be sent with a value of "true" if the card number to be sent in the next step of the flow uses SiTef encryption.
The option to send the encrypted card will only be available through routing via SiTef and prior SiTef setup is required.
Options:
1. "true"
2. "false" (default)
< 5 ANNo
merchant_usnUnique 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 NNo
order_idOrder 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 ANNo
transaction_typeFixed value "preauthorization"= 15 AYes
is_transaction_origin_externalFixed value "true"= 5 AYes
soft_descriptorAdditional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more< 22 ANNO

Format field caption:

A = alphanumeric

N = numeric

N A = not applied

Response Parameters#

ParameterDescriptionFormat
codeCarat Portal response code. Any code other than ‘0’ means failure. For more information, see Responde Codes.< 4 N
messageCarat Portal's response message.< 500 A
amountTransaction's amount defined by the store (in cents) at transaction creation.< 12 N
merchant_usnUnique sequential number sent by store transaction creation.< 12 N
nitPre-authorization transaction ID in Carat Portal.= 64 A
order_idOrder code sent by store at transaction creation.< 40 AN
statusPre-authorization transaction status in Carat Portal.= 3 A

Pre-Authorization Capture External Origin Service#

The execution follows the same flow as a transaction capture originated in Carat Portal, but it is necessary to send some additional parameters in the request.

Request Parameter#

ParameterDescriptionFormatMandatory
acquirerThis element’s fields must be sent in cases of capture external origin.
routing_idRouting information used by the payment done outside of Carat Portal. It is used to identify the routing inside of SiTef. This information only make sense in external origin transaction.< 5 NNo
authorizer_idCode of the authorizer on Carat Portal. It must be the same value sent on the pre autorization.< 3 NYes
host_usnHost/authorizer USN of the transaction to be captured.= 9 NYes
authorization_numberAuthorization number of the transaction to be captured.< 6 NYes
authorizer_datePre-authorization date returned by the authorizer in DD/MM/YYYY format.= 10 DYes
order_idOrder code used in the pre-authorization initiated outside Carat Portal.< 40 ANNo
identification_numberCPF or CNPJ used in the pre-authorization initiated outside Carat Portal.< 20 ANYes
terminalSitef terminal code. In absence Carat Portal will generate a random terminal code.= 8 ANNo
company_codeSitef company code. In absence Carat Portal will use company code from merchant configuration.= 8 NNo

"Format" field type legent:

A - Alphanumeric

N - Numeric

N A - Not used

Note:#

1 - When the terminal and company_code information are sent, the behavior of cardquery changes slightly. At this point, when running cardquery, Carat Portal will identify the network returned by SiTef. Once identified, it will be used instead of the one registered in the store.

2 - In operations of external origin, we are unable to validate the network that was used in the external part of the operation, which was carried out outside Carat Portal. In these cases, we are going to use the network configured on SiTef. Because of that, configuration changes, if done during operation, can cause invalid or denied requests. For example, if a pre-authorization was made on the physical medium on the 181 network and, before the capture is completed, the SiTef configuration is changed to the 125 network, the operations that are done via Carat Portal will take over the 125 network.

WARNING: The terminal e company_code parameters must be sent simultaneously.
It is also necessary send a request to the Carat Portal Support Team for the permission Allows the sending of Company and SiTef Terminal through REST.

Example#

Request:

To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br

curl
--request POST "https://{{url}}/e-sitef/api/v1/preauthorizations/capture/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
"amount": "300",
"installments": "1",
"installment_type": "4",
"card": {
"number": "5555555555555555",
"expiry_date": "1222",
"security_code": "123"
},
"acquirer": {
"authorizer_id": "2",
"authorization_number": 212820,
"identification_number": "11111111555",
"order_id": 1611256811271,
"authorizer_date": "21/01/2021",
"host_usn": 999212820
}
}
--verbose

Response:

{
"code": "0",
"message": "OK. Transaction successful.",
"capture": {
"status": "CON",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "orderID",
"customer_receipt": "=== CUSTOMER RECEIPT ===",
"merchant_receipt": "=== MERCHANT RECEIPT ===",
"authorizer_id": "2",
"acquirer_id": "229",
"acquirer_name": "Bin",
"authorizer_code": "000",
"authorizer_message": "Transacao OK.",
"authorizer_date": "21/01/2021T19:40",
"authorizer_merchant_id": "000000000000000",
"authorization_number": "212195",
"esitef_usn": "180921015287704",
"merchant_usn": "20190101",
"sitef_usn": "212195",
"host_usn": "999212195",
"amount": "100",
"payment_type": "C",
"issuer": "2"
}
}