Pre-Authorization Editing External Origin Service

For GetnetLac route you can change the value of a non-captured preauthorization, even if it isn't present in e-SiTef's databases. Consult our support to avail which other routes have this functionality too. To use this functionality, simply call the doPreAuthorization operation with data from a pre-authorization transaction with status CON (confirmed) in addition to the amount field. Below are the details for this call.

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

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

Pre-authorization editing external origin creation

Call details

Resource: /v1/transactions
HTTP Method: POST
Request format: JSON
Response format: JSON
Header parameters:

Parameter	Description	Format	Mandatory
`Content-Type`	Fixed value "application/json"	= 15 A	Yes
`merchant_id`	e-SiTef store's ID. Production and certification IDs are different.	≤ 15 A	Yes
`merchant_key`	Store authentication key in e-SiTef. Production and certification keys are different.	< 80 A	Yes

Examples

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

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/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":"preauthorization",
    "is_transaction_origin_external": "true"
}
--verbose

Response:

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

Request Parameter

Parameter	Description	Format	Mandatory
`amount`	Total purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas	< 12N	Yes
`encrypted_card`	This 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 AN	No
`merchant_usn`	Unique 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 e-SiTef, it is strongly recommended that the field be formatted and sent by the store application.	< 12 N	No
`order_id`	Order 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 e-SiTef, in SiTef it will only be 123456789012).	< 40 AN	No
`transaction_type`	Fixed value "preauthorization"	= 15 A	Yes
`soft_descriptor`	Additional text that will be presented alongside the name of the establishment in the credit card invoice. Learn more	< 22 AN	NO
`is_transaction_origin_external`	Fixed value "true"	= 5 AN	Yes

Format field caption:

A = alphanumeric

N = numeric

N A = not applied

Response Parameters

Parameter	Description	Format
`code`	e-SiTef response code. Any code other than ‘0’ means failure. For more information, see Responde Codes.	< 4 N
`message`	e-SiTef's response message.	< 500 A
`amount`	Transaction's amount defined by the store (in cents) at transaction creation.	< 12 N
`merchant_usn`	Unique sequential number sent by store transaction creation.	< 12 N
`nit`	Pre-authorization transaction ID in e-SiTef.	= 64 A
`order_id`	Order code sent by store at transaction creation.	< 40 AN
`status`	Pre-authorization transaction status in e-SiTef.	= 3 A

Pre-Authorization Editing External Origin Service

The execution follows the same flow as a pre-authorization editing transaction originated in e-SiTef, but it is necessary to send some additional parameters in the request.

Request Parameter

Parameter	Description	Format	Mandatory
acquirer	This element’s fields must be sent in cases of external origin transactions.
`authorizer_id`	Code of the authorizer on e-SiTef. It must be the same value sent on the pre autorization.	< 3 N	Yes
`host_usn`	Host/authorizer USN of the transaction to be captured.	= 9 N	Yes
`authorization_number`	Authorization number of the transaction to be captured.	< 6 N	Yes
`authorizer_date`	Pre-authorization date returned by the authorizer in `DD/MM/YYYY` format.	= 10 D	Yes
`order_id`	Order code used in the pre-authorization initiated outside e-SiTef.	< 40 AN	No
`identification_number`	CPF or CNPJ used in the pre-authorization initiated outside e-SiTef.	< 20 AN	Yes
`terminal`	SiTef terminal code. In absence e-SiTef will generate a random terminal code.	= 14 N	Yes
`company_code`	SiTef company code. In absence e-SiTef will use company code from merchant configuration.	= 8 N	Yes

Note:

1 - When the terminal andcompany_code information are sent, the behavior of cardquery changes slightly. At this point, when running cardquery, e-SiTef 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 e-SiTef. 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 e-SiTef 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 e-SiTef Support Team for the permission Permite envio de Empresa e Terminal SiTef via REST.

Example

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
{
    "amount": "3000",
    "installments": "1",
    "installment_type": "4",
    "card": {
        "number": "5555555555555555",
        "expiry_date": "1222",
        "security_code": "123"
    },
    "acquirer": {
        "authorizer_id": "1",
        "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.",
   "pre_authorization":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK SDO DISPONIVEL 244,00",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"orderID",
      "customer_receipt":"=== CUSTOMER RECEIPT ===",
      "merchant_receipt":"=== MERCHANT RECEIPT ===",
      "authorizer_id":"1",
      "acquirer_id":"1181",
      "acquirer_name":"GetNet Lac",
      "authorizer_date":"30/03/2021T10:03",
      "authorization_number":"300016",
      "merchant_usn":"30120944339",
      "esitef_usn":"210330069186034",
      "sitef_usn":"300016",
      "host_usn":"003300016 ",
      "amount":"3000",
      "payment_type":"C",
      "authorizer_merchant_id":"000000000000000"
   }
}