Create Pre-Authorization

Brazil

WARNING: This page is a document under construction, subject to change without notice, and still uncoupled from our full documentation. If you wish to access all our documentation, check here.

Pre-authorization interface that allows the merchant to perform pre-authorization requests in a single call. Click here for more information on pre-authorization capture.

Request details

Resource: /v2/preauthorizations/
HTTP Method: POST
Request format: JSON
Response format: JSON
Header parameters:

Parameter	Description	Format	Mandatory
`Content-Type`	Fixed value `application/json`	= 15 AN	YES
`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

Examples:

Request:

To use this example, don't forget to define the variable {{url}} to the value

curl
--request POST "https://{{url}}/e-sitef/api/v2/preauthorizations/"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "order_id":"123255",
    "merchant_usn":"20190101",
    "amount":"100",
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "card":{
        "number":"xxxxxxxxxxxxxxxx",
        "expiry_date":"1225",
        "security_code":"123"
    }
}
--verbose

Response:

{
    "code":"0",
    "message":"OK. Transaction successful.",
    "pre_authorization":{
        "authorizer_code":"000",
        "authorizer_message":"Transacao OK.",
        "status":"CON",
        "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
        "customer_receipt":"=== CUSTOMER RECEIPT ===",
        "merchant_receipt":"=== MERCHANT RECEIPT ===",                
        "authorizer_id":"2",
        "authorizer_date":"09/11/2018T19:40",
        "acquirer_id":"229",
        "acquirer_name":"Bin",
        "authorization_number":"013245",
        "merchant_usn":"20190101",
        "esitef_usn":"181109017689784",
        "order_id":"123255",
        "sitef_usn":"212194",
        "host_usn":"999212194",
        "amount":"100",
        "issuer":"2",
        "payment_type":"C",
        "authorizer_merchant_id":"000000000000000",
        "standin_details": "000001",
        "cvv_result_code": "M"
    }
}

Pre-Authorization with CARD PAR Token

An object {{card}} was created that receives the field {{par}}: The Payment Account Reference, it is a value linked to the PAN: Primary Account Number of a Mastercard card.

Request:

It is worth emphasizing that it will only work if the variable {{cryptogram}} is defined in the request.

curl
--request POST "https://{{url}}/e-sitef/api/v2/preauthorizations/"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "merchant_usn":"1709151775",
   "order_id":"0001709151774770",
   "installments":"1",
   "installment_type":"4",
   "authorizer_id":"2",
   "amount":"100",
   "soft_descriptor": "Empresa Aluguel de carros XYZ",
    "card":{
      "number":"555555555555555",
      "expiry_date":"1227",
      "security_code":"157",
      "cryptogram": "ALRzlt6NKQtPAAZAkOuIAAADFA==",
      "wallet_type": "network_token"
   }
}'

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "card": {
        "par": "A80pcFJxz0FgEK6qDggFpM5KUl2Jf"
    },
    "pre_authorization": {
        "authorizer_code": "000",
        "authorizer_message": "TRANSACAO APROVADA",
        "status": "CON",
        "nit": "74e3fa7509d683c73240e4868ec7b75b14170547567b809f6f2698f234ab8f4f",
        "order_id": "0001709151682784",
        "customer_receipt": "====CUPOM COMPRADOR====",
        "merchant_receipt": "====CUPOM ESTABELECIMENTO====",
        "authorizer_id": "2",
        "acquirer_id": "2651",
        "acquirer_name": "Bin (Via Servicos TEF)",
        "authorizer_date": "28/02/2024T17:21",
        "authorization_number": "242440",
        "merchant_usn": "1709151683",
        "esitef_usn": "240228062687254",
        "sitef_usn": "304331",
        "host_usn": "43734572891",
        "amount": "100",
        "payment_type": "C",
        "terminal_id": "ES000001",
        "card_par": "A80pcFJxz0FgEK6qDggFpM5KUl2Jf",
        "recurrency_tid": "969452034274685",
        "standin_details": "000001",
        "cvv_result_code": "M"
    }
}

Pre-Authorization - Network Token

Some card brands have a tokenization solution that offers card storage encrypted in safes at the brand itself. This brand tokenization is intended to improve the security and quality of the transmitted card information, which may increase checkout conversion rates.

Request:

To use this example, don't forget to define the variable {{url}} to the value

curl
--request POST "https://{{url}}/e-sitef/api/v2/preauthorizations/"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "order_id":"1670945065929",
    "merchant_usn":"16114726760",
    "amount":"25255",
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "card": {
        "expiry_date": "1023",
        "number": "xxxxxxxxxxxxxxxx",
        "security_code": "123",
        "cryptogram":"ALRzlt6NKQtPAAZAkOuIAAADFA=="
    }
}'

Response:

{
    "code": "0",
    "message": "OK. Transaction successful.",
    "pre_authorization": {
        "authorizer_code": "000",
        "authorizer_message": "Transacao Aprov.",
        "status": "CON",
        "nit": "8621c93b58e507d3fe0bda407f5cb0b1fe3971df591fd2652cc9f737134502d3",
        "order_id": "1670945065929",
        "customer_receipt":"=== CUSTOMER RECEIPT ===",
        "merchant_receipt":"=== MERCHANT RECEIPT ===",  
        "authorizer_id": "2",
        "acquirer_id": "229",
        "acquirer_name": "Bin",
        "authorizer_date": "13/12/2022T12:24",
        "authorization_number": "136231",
        "merchant_usn": "16114726760",
        "esitef_usn": "221213115168264",
        "sitef_usn": "136231",
        "host_usn": "999136231   ",
        "amount": "25255",
        "payment_type": "C",
        "issuer": "1",
        "authorizer_merchant_id": "000000000000005",
        "terminal_id": "ES000038",
        "standin_details": "000001",
        "cvv_result_code": "M"
    }
}

Request Parameters

WARNING:

In addition to the return parameters of the services described in this specification, Carat may return other parameters without prior notice.

It is important that the application is prepared to receive unknown parameters in addition to the parameters already specified and simply ignore them.

The terminal e company_code parameters 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 the sending of Company and SiTef Terminal through REST.

Response Parameters

The table below contains the response parameters of the pre-authorization effectuation service. The app should merchant the parameters that finds necessary. We suggest storing the parameters:order_id, authorization_number, merchant_usn, esitef_usn, sitef_usn, host_usn, status, code, amount, message (the message parameter can be displayed to the customer).

Updated 6 days ago

Did this page help you?