Pre-Authorization Increment

Brazil

For certains routings you can increment the value of a non-captured preauthorization. Consult our support to avail which routes have this functionality.

To use this functionality, simply call the doPreAuthorization operation with data from a pre-authorization transaction with status CON (confirmed) in addition to the additional_amount field. Below are the details for this call.

Request Parameters

Parameter	Description	Format	Mandatory
`nit`	Transaction ID in Carat Portal (encrypted). Obtained from beginTransaction's return.	= 64 A	Yes
`authorizer_id`	Carat Portal authorizers ID. See Authorizers.	≤ 3 N	Yes
`additional_amount`	Additional amount specified by store (in cents).	< 12 AN
`number`(*)	Buyer card number (PAN).	≤ 19 N	Sim
`token`(*)	Used for recurring pre-authorizations, when the card is already stored at Carat Portal database.	= 88 A	Conditional
`wallet_transaction_id`(*)	Visa Checkout wallet transaction ID.	< 25 A	Conditional
`expiry_date`	Card expiration date in format MMYY.	= 4 N	Yes
`security_code`	Security code.	≤ 5 N	Yes

(*) Mandatory using only one of the fields: number, token or wallet_transaction_id

Response Parameters

Parameter	Description	Format
`code`	Carat Portal response code. Anything besides "0" means failure. See more information at the Response Code document	< 4 N
`message`	Carat Portal response message.	< 500 AN
`acquirer_id`	Acquirer/routing ID used in transaction.	< 4 N
`acquirer_name`	Acquirer/routing name used in transaction.	< 100 AN
`amount`	Total purchase amount (in cents), i.e, initially pre-authorized amount plus incremented amount(s)	< 12 AN
`authorization_number`	Increment's authorization number	< 6 AN
`authorizer_code`	Increment's authorizer responde code.	< 10 AN
`authorizer_date`	Increment's authorizer pre-auth effectuation date, returned by the authorizer on the format DD/MM/YYYY’T’HH:mm. Example: 13/07/2017T16:03	= 16 D
`authorizer_id`	Authorizer ID used in increment.	< 4 N
`authorizer_merchant_id`	Merchant ID from authorizer.	< 100 AN
`authorizer_message`	Increment's reponse message from authorizer.	< 500 AN
`customer_receipt`	Increment's customer receipt.	< 4000 AN
`eci`	Eletronic Commerce Indicator (pre-authorization security level indicator on transactions via Cielo e-Commerce).	< 3 AN
`esitef_usn`	Carat Portal pre-authorization's unique sequential number.	= 15 N
`host_usn`	Increment's authorizer NSU.	< 15 AN
`issuer`	Increment's issuer code returned by the authorizer.	< 5 AN
`merchant_receipt`	Increment's merchant receipt.	< 4000 AN
`merchant_usn`	Unique sequential number sent by merchant at the transaction creation.	< 12 AN
`nit`	Carat Portal pre-authorization transaction ID.	= 64 AN
`order_id`	Order ID sent by the merchant at transaction creation.	< 40 AN
`payment_type`	Payment type from the selected authorizer: B = boleto, C = credit, D = debit, P = Private Label credit card, T = bank transfer, G = gift card, O = other ways of payments	= 1 A
`sitef_usn`	SiTef pre-authorization increment's unique sequential number.	= 6 N
`status`	Carat Portal pre-authorization increment status.	= 3 AN
`tid`	Acquirer/routing increment transaction ID. This field is only returned in transactions with external acquirer's.	< 40 AN
`xid`	XID field returned on 3DS authentications or certain acquirers/routings.	< 40 AN

In case of success, the responseCode returned will be '0'. Transaction status in Carat Portal database will not be changed under any circumstances (success or failure).

The fields sitef_usn, host_usn, authorization_number, sitef_date, customer_receipt e merchant_receipt refers to increment, but the respective transaction data is not updated in database. Only total amount is updated in transaction.

Exemplo:

1. R$20,00 pre-authorization creation and effectuation:

a. creation - request

{
  "order_id": "orderID",
  "merchant_usn": "20190101",
  "amount": "2000",
  "transaction_type": "preauthorization"
}

it's assumed here that creation was successful...

b. effectuation - request

{
  "authorizer_id": "2",
  "installments": "2",
  "installment_type": "4",
  "card": {
    "number": "xxxxxxxxxxxxxxxx",
    "expiry_date": "1222",
    "security_code": "yyy"
  }
}

c. 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": "1296",
    "acquirer_name": "Safra",
    "authorization_number": "013245",
    "merchant_usn": "20190101",
    "esitef_usn": "181109017689784",
    "order_id": "orderID",
    "sitef_usn": "212194",
    "host_usn": "999212194",
    "amount": "2000",
    "issuer": "2",
    "payment_type": "C",
    "authorizer_merchant_id": "000000000000000"
  }
}

2. R$2,00 pre-authorization increment

a. increment - request

{
  "authorizer_id": "2",
  "installments": "2",
  "installment_type": "4",
  "additional_amount": "200",
  "card": {
    "number": "xxxxxxxxxxxxxxxx",
    "expiry_date": "1222",
    "security_code": "yyy"
  }
}

b. increment - response

{
  "code": "0",
  "message": "OK. Transaction successful.",
  "pre_authorization": {
    "authorizer_code": "000",
    "authorizer_message": "Transacao OK.",
    "status": "CON",
    "nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
    "customer_receipt": "=== CUSTOMER RECEIPT INCREMENT ===",
    "merchant_receipt": "=== MERCHANT RECEIPT INCREMENT ===",
    "authorizer_id": "2",
    "authorizer_date": "09/11/2018T19:42",
    "acquirer_id": "1296",
    "acquirer_name": "Safra",
    "authorization_number": "013246",
    "merchant_usn": "20190101",
    "esitef_usn": "181109017689785",
    "order_id": "orderID",
    "sitef_usn": "212195",
    "host_usn": "999212195",
    "amount": "2200",
    "issuer": "2",
    "payment_type": "C",
    "authorizer_merchant_id": "000000000000000"
  }
}

Note that amount field contains the pre-authorized total value.

3. Resulting pre-authorization transaction status inquiry

a. transaction status inquiry - 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": "1296",
    "acquirer_name": "Safra",
    "authorization_number": "013245",
    "merchant_usn": "20190101",
    "esitef_usn": "181109017689784",
    "order_id": "orderID",
    "sitef_usn": "212194",
    "host_usn": "999212194",
    "amount": "2200",
    "issuer": "2",
    "payment_type": "C",
    "authorizer_merchant_id": "000000000000000"
  }
}

Updated 14 days ago