Pre-Authorization effectuation service

Call details

The nit obtained from the return of the pre-authorization creation service should be sent on the pre-authorization effectuation operation along with the parameters described in the table below (as necessary by each application):

Resource: /v1/preauthorizations/{nit}
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 e-SiTef. The production and certification codes will be different.	< 15 AN	YES
`merchant_key`	Merchant authentication key on e-SiTef. The production and certification keys will be different.	< 80 AN	YES

Examples:

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/preauthorizations/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
    "authorizer_id":"2",
    "installments":"2",
    "installment_type":"4",
    "card":{
        "number":"xxxxxxxxxxxxxxxx",
        "expiry_date":"1222",
        "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":"1005",
        "acquirer_name":"Redecard",
        "authorization_number":"013245",
        "merchant_usn":"20190101",
        "esitef_usn":"181109017689784",
        "order_id":"orderID",
        "sitef_usn":"212194",
        "host_usn":"999212194",
        "amount":"100",
        "issuer":"2",
        "payment_type":"C",
        "authorizer_merchant_id":"000000000000000"
    }
}

Request Parameters

Parameter	Description	Format	Mandatory
`authorizer_id`	e-SiTef authorizers ID. Learn more.	< 3 N	YES
`customer_id`	Buyers' ID. Only alphanumerics are allowed (no dots, dashes or other special characters).	< 20 AN	NO
`discount`	Discount amount in cents. In case of pre-authorizations with promotional values when using Visa Checkout, VISA suggests that this field should be submitted additionally.	< 12 N	NO
`installments` (*)	Installments number, `1` for sale spot	< 2 N	YES
`installment_type`	Along with the installments field, indicates installment. Possible values for `installment_type` are: `3`: Installments with interest `4`: Installments without interest (adopt this as default on spot sales)	= 1 N	YES
`mcc`	Merchant Category Code - Indicates the store category's ID.	< 4 N	Required only when using sub-acquirer Stone WS and it is optional to send it to acquirers with sub-merchant funding via SiTef.
`merchant_email`	Store e-mail. When this parameter is sent, it overwrites the store registered e-mail.	< 40 AN	NO
`nit`	Transaction ID in e-SiTef (encrypted). Obtained from beginTransaction's return.	= 64 AN	YES
`promo_code`	Visa Checkout promotion code used in pre-authorization. In case of pre-authorizations with promotional values when using Visa Checkout, VISA suggests that this field should be submitted additionally.	AN	NO
`soft_descriptor`	Additional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more	< 22 AN	NO
`subtotal`	Subtotal amount, in cents. In case of pre-authorizations with promotional amounts by using Visa Checkout, VISA suggests that this field be submitted additionally.	< 12 N	NO
`subacquirer_merchant_id`	It is the merchant identification for the subacquirer.	< 22 N	NO
`card`	Sending card data is mandatory. Only one of these fields must be used: `number`, `token` or `wallet_transaction_id`
`holder`	Cardholder's name. Required only for e-Rede, GetNet WS e VR (SmartNet) routings.	< 30 AN	COND.
`number`	Customer's card number (PAN).	< 19 N	COND.
`token`	Used for recurring pre-authorizations, when the card is already stored at e-SiTef database.	= 88 AN	COND.
`wallet_transaction_id`	Wallet Visa Checkout transaction ID.	< 25 AN	COND.
`initial_wallet_transaction_id`	Informs if the Wallet ID (`wallet_transaction_id`) is being used for the first time. If it's the first time, send `true`, otherwise, send `false`. Required only for Visa Checkout. Default value: `true`	< 5 AN	COND.
`expiry_date`	Card expiry date in `MMYY` format.	= 4 N	COND.
`security_code`	Card security code.	< 5 N	COND.
`external_authentication`	This element receives MPI authentication fields.
`eci`	Eletronic Commerce Indicator – Card holder authentication security level indicator.	< 3 N	NO
`xid`	External card holder authentication transaction id.	< 40 N	NO
`cavv`	Cardholder Authentication Verification Value - Codes that refers to card holder authentication result data.	< 40 N	NO
`acquirer`	Data required only to specific acquirers / routings.
`terminal`	Sitef terminal code. In absence e-SiTef will generate a random terminal code.	= 14 N	NO
`company_code`	Sitef company code. In absence e-SiTef will use company code from merchant configuration.	= 8 N	NO

(*) Installments funding routed by GetNetLac via SiTef : In this case, the merchant will be responsible for the installment control, so the installment rules set up for the e-SiTef HTML payment interface won't take effect, only the authorizing installment rules will be verified and applied. For these mentioned networks, if pre-authorization is made at spot, the capture cannot be split. Also, pre-authorizations routed by GetNetLac via SiTef, when splitted, are only accepted without interest, that is, with the parameter installment_type = 4. Interest-free installments are not accepted on this routing.

WARNING: 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 e-SiTef Support Team for the permission Permite envio de Empresa e Terminal Sitef via REST.

Response Parameters

The table below contains the response parameters of the pre-authorization effectuation service. The app should store 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).

Parameter	Description	Format
`code`	e-SiTef response code. Anything besides `0` means failure. Learn more.	< 4 N
`message`	e-SiTef response message.	< 500 AN
`pre_authorization`
`acquirer_id`	Acquirer/routing ID used in transaction.	< 4 N
`acquirer_name`	Acquirer/routing name used in transaction.	< 100 AN
`amount`	Purchase amount specified by store (in cents) on transaction creation.	< 12 AN
`authorization_number`	Authorization number	< 6 AN
`authorizer_code`	Authorizer responde code.	< 10 AN
`authorizer_date`	Authorizer pre-auth effectuation date, returned by the authorizer on the format `DD/MM/AAAA’T’HH:mm`. Example: `13/07/2017T16:03`	= 16 AN
`authorizer_id`	Authorizer ID use in transaction.	< 4 N
`authorizer_merchant_id`	Merchant ID from authorizer.	< 100 AN
`authorizer_message`	Reponse message from authorizer.	< 500 AN
`customer_receipt`	Customer receipt.	< 4000 AN
`eci`	Eletronic Commerce Indicator (pre-authorization security level indicator on transactions via Cielo e-Commerce).	< 3 AN
`esitef_usn`	e-SiTef pre-authorization's unique sequential number.	= 6 N
`host_usn`	Authorizer NSU.	< 15 AN
`issuer`	Issuer code returned by the authorizer.	< 5 AN
`merchant_receipt`	Merchant receipt.	< 4000 AN
`merchant_usn`	Unique sequential number sent by store at the transaction creation.	< 12 AN
`nit`	e-SiTef pre-authorization transaction ID.	= 64 AN
`order_id`	Order ID sent by the store 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 payment methods, `W` = Boleto NR via Web Service	= 1 AN
`sitef_usn`	SiTef pre-authorization's unique sequential number.	= 6 N
`status`	e-SiTef pre-authorization transaction status.	= 3 AN
`tid`	Acquirer/routing 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