Pre-Authorization Increment Service

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

ParameterDescriptionFormatMandatory
nitTransaction ID in e-SiTef (encrypted). Obtained from beginTransaction's return.= 64 AYes
authorizer_ide-SiTef authorizers ID. See Authorizers.≤ 3 NYes
additional_amountAdditional amount specified by store (in cents).< 12 AN
number(*)Buyer card number (PAN).≤ 19 NSim
token(*)Used for recurring pre-authorizations, when the card is already stored at e-SiTef database.= 88 AConditional
wallet_transaction_id(*)Visa Checkout wallet transaction ID.< 25 AConditional
expiry_dateCard expiration date in format MMYY.= 4 NYes
security_codeSecurity code.≤ 5 NYes

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

Response Parameters

ParameterDescriptionFormat
codee-SiTef response code. Anything besides "0" means failure. See more information at the Response Code document< 4 N
messagee-SiTef response message.< 500 AN
acquirer_idAcquirer/routing ID used in transaction.< 4 N
acquirer_nameAcquirer/routing name used in transaction.< 100 AN
amountTotal purchase amount (in cents), i.e, initially pre-authorized amount plus incremented amount(s)< 12 AN
authorization_numberIncrement's authorization number< 6 AN
authorizer_codeIncrement's authorizer responde code.< 10 AN
authorizer_dateIncrement'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_idAuthorizer ID used in increment.< 4 N
authorizer_merchant_idMerchant ID from authorizer.< 100 AN
authorizer_messageIncrement's reponse message from authorizer.< 500 AN
customer_receiptIncrement's customer receipt.< 4000 AN
eciEletronic Commerce Indicator (pre-authorization security level indicator on transactions via Cielo e-Commerce).< 3 AN
esitef_usne-SiTef pre-authorization's unique sequential number.= 6 N
host_usnIncrement's authorizer NSU.< 15 AN
issuerIncrement's issuer code returned by the authorizer.< 5 AN
merchant_receiptIncrement's merchant receipt.< 4000 AN
merchant_usnUnique sequential number sent by merchant at the transaction creation.< 12 AN
nite-SiTef pre-authorization transaction ID.= 64 AN
order_idOrder ID sent by the merchant at transaction creation.< 40 AN
payment_typePayment 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_usnSiTef pre-authorization increment's unique sequential number.= 6 N
statuse-SiTef pre-authorization increment status.= 3 AN
tidAcquirer/routing increment transaction ID. This field is only returned in transactions with external acquirer's.< 40 AN
xidXID field returned on 3DS authentications or certain acquirers/routings.< 40 AN

In case of success, the responseCode returned will be '0'. Transaction status in e-SiTef 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"
   }
}
← Pre-Authorization Editing External Origin ServiceCard Query Service →