Transaction status query

These services can be called to obtain data from the payment, cancel or schedule transactions. It's essential to use this operation for handling communication errors to verify the current status of the transaction, which may have been processed or not received by e-SiTef.

e-SiTef provides a service for querying by NIT (payment/cancel) and a service for querying by SID (schedule). In the case of payment with schedule, the queries will return the data from both transactions.

Note:

The e-SiTef transaction query service DO NOT makes a transaction status check in acquirer / authorizer. This service only returns the transaction status in e-SiTef database.

Example: If a payment transaction is confirmed in e-SiTef, but is reversed via telephone directly to the acquirer / authorizer, this reversal will not necessarily be reflected in the e-SiTef transaction query service.

Call details

Query by NIT

Resource: /v1/transactions/{nit}
HTTP Method: GET
Request format: there are no request parameters
Response format: JSON
Header parameters:

Parameter	Description	Format	Mandatory
`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

Query by SID

Resource: /v1/schedules/{sid}
HTTP Method: GET
Request format: there are no request parameters
Response format: JSON
Header parameters:

Parameter	Description	Format	Mandatory
`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

Below are some examples of the query services calls using the cURL tool.

Payment query

Request:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13064421440",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T18:44",
      "authorization_number":"132048",
      "merchant_usn":"13064421441",
      "esitef_usn":"170713097341620",
      "sitef_usn":"132048",
      "host_usn":"999132048   ",
      "payment_date":"13/07/2017T18:44",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   }
}

Schedule query

Request:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000050",
      "authorizerId":"2",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/08/2017",
      "number_of_times":"3",
      "current_times":"0",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false"
   }
}

Query by payment with schedule NIT

Request:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13065054564",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T18:51",
      "authorization_number":"132050",
      "merchant_usn":"13065054565",
      "esitef_usn":"170713097341630",
      "sitef_usn":"132050",
      "host_usn":"999132050   ",
      "payment_date":"13/07/2017T18:51",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   },
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000060",
      "authorizerId":"2",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/10/2017",
      "number_of_times":"3",
      "current_times":"2",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false",
      "nits":[
         "123412341234111",
         "123412341234222"
      ]
   }
}

Query by schedule with payment SID

Request:

curl
--request GET "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/schedules/qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01"
--header "merchant_id: xxxxxxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13065054564",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T18:51",
      "authorization_number":"132050",
      "merchant_usn":"13065054565",
      "esitef_usn":"170713097341630",
      "sitef_usn":"132050",
      "host_usn":"999132050   ",
      "payment_date":"13/07/2017T18:51",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   },
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000060",
      "authorizerId":"2",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/10/2017",
      "number_of_times":"3",
      "current_times":"2",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Assinatura",
      "show_times_invoice":"false",
      "nits":[
         "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqs",
         "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqt"
      ]
   }
}

Response parameters

If successful, the HTTP response code will be 200. Any other code must be interpreted as an error. The table below describes the response parameters of the transaction query service:

Parameter	Description	Format
`code`	e-SiTef response code. Any code different from `0` means failure. Learn more.	< 4 N
`message`	e-SiTef response message.	< 500 AN
	payment
`authorizer_code`	Authorizer response code.	< 10 AN
`authorizer_message`	Authorizer response message.	< 500 AN
`status`	Status of the payment transaction on e-SiTef. Learn more.	= 3 AN
`nit`	Identifier of the payment transaction on e-SiTef.	= 64 AN
`order_id`	Order code sent by the merchant on the creation of the transaction.	< 40 AN
`merchant_usn`	Unique sequential number sent by the merchant on the creation of the transaction.	< 12 N
`amount`	Total price of the purchase specified by the merchant (in cents) on the creation of the transaction.	< 12 N
`sitef_usn`	Unique sequential number of the payment transaction on SiTef.	= 6 N
`esitef_usn`	Unique sequential number of the payment transaction on e-SiTef.	= 15 N
`customer_receipt`	Customer's receipt.	< 4000 AN
`merchant_receipt`	Merchant's receipt.	< 4000 AN
`authorizer_id`	Code of the authorizer used on the transaction.	< 4 N
`acquirer_id`	Code of the acquirer used on the transaction.	< 4 N
`acquirer_name`	Name of the acquirer used on the transaction.	< 100 AN
`authorizer_date`	Payment authorization date returned by the authorizer in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`authorization_number`	Authorization number.	< 6 AN
`host_usn`	Host USN.	< 15 AN
`tid`	ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef.	< 40 AN
`eci`	Eletronic Commerce Indicator (security level indicator of the payment transaction via Cielo e-Commerce).	< 3 AN
`payment_date`	Payment authorization date on e-SiTef in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`issuer`	Issuer code returned by the authorizer.	< 5 AN
`authorizer_merchant_id`	Affiliation code of the merchant on the authorizer.	< 100 AN
`xid`	XID field returned on 3DS authentications or certain acquirers.	< 40 AN
`balance`	Current balance after payments with Gift cards.	< 12 N
	payment.analysis
`code`	Response code of the fraud analysis operation.	< 4 N
`message`	Response message of the fraud analysis operation.	< 200 AN
`status`	Status of the fraud analysis transaction on e-SiTef. This field can assume the following value: `NOV` – New. `EXP` – Expired. `ACC` – Accepted `REJ` – Rejected `REV` – In review `INV` – Invalid	= 3 AN
	schedule
`status`	Status of the schedule on e-SiTef. Learn more.	= 3 AN
`sid`	Schedule transaction identifier on e-SiTef.	= 64 AN
`schedule_usn`	Unique sequential number of the schedule on e-SiTef.	= 15 N
`authorizer_id`	Code of the authorizer to be used on the scheduled payments.	= 4 N
`amount`	Amount of the scheduled payments specified by the merchant (in cents) on the creation of the transaction.	< 12 N
`order_id`	Order code sent by the merchant on the creation of the transaction.	< 40 AN
`merchant_usn`	Unique sequential number sent by the merchant on the creation of the transaction.	< 12 N
`initial_date`	Execution date of the first scheduled payment in `DD/MM/YYYY` format.	= 10 D
`next_date`	Execution date of the next scheduled payment in `DD/MM/YYYY` format.	= 10 D
`number_of_times`	Total quantity of scheduled payments.	< 3 N
`current_times`	Quantity of scheduled payments already executed.	< 3 N
`installments`	Number of installments to be used on the scheduled payments.	< 2 N
`installment_type`	Financing type to be used on the scheduled payments.	< 2 N
`soft_descriptor`	Additional text that will be presented alongside the name of the establishment in the credit card invoice. This functionality is available to the acquirers Cielo e-Commerce, PayPal, e-Rede, ElavonWS and Stone.	< 30 AN
`show_times_invoice`	For finite time schedules, send this field with value `true` if you want to add at the end of the `soft_descriptor` field the current times/number of times (e.g. Subscription 3/12).	< 5 T/F
`nits`	NITs of the last six scheduled payments already executed.	= 64 AN[]
	cancellation
`authorizer_code`	Authorizer response code.	< 10 AN
`authorizer_message`	Authorizer response message.	< 500 AN
`status`	Status of the payment transaction on e-SiTef. Learn more.	= 3 AN
`nit`	Identifier of the cancel transaction on e-SiTef.	= 64 AN
`order_id`	Order code of the transaction sent by the merchant.	< 40 AN
`merchant_usn`	Unique sequential number of the transaction sent by the merchant.	< 12 N
`amount`	Amount of the cancel transaction as specified by the merchant (in cents).	< 12 N
`sitef_usn`	Unique sequential number of the cancel transaction on SiTef.	= 6 N
`esitef_usn`	Unique sequential number of the cancel transaction on e-SiTef.	= 15 N
`customer_receipt`	Customer's receipt.	< 4000 AN
`merchant_receipt`	Merchant's receipt.	< 4000 AN
`authorizer_id`	Code of the authorizer used on the transaction.	< 4 N
`acquirer_id`	Code of the acquirer used on the transaction.	< 4 N
`acquirer_name`	Name of the acquirer used on the transaction.	< 100 AN
`authorizer_date`	Cancel authorization date returned by the authorizer in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`authorization_number`	Authorization number.	< 6 AN
`host_usn`	Host USN.	< 15 AN
`tid`	ID of the transaction on the acquirer. This field is only returned on transactions with acquirers that are external to SiTef.	< 40 AN
`esitef_date`	Cancel authorization date on e-SiTef in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D
`issuer`	Issuer code returned by the authorizer.	< 5 AN
`authorizer_merchant_id`	Affiliation code of the merchant on the authorizer.	< 100 AN
`is_host_cancel`	This field will return the value `true` in case of cancel via host.	< 5 T/F
`terminal_id`	Terminal code used in the transaction	< 8 AN

Querying transactions from a group of merchants

e-SiTef requires that the credentials (merchant_id and merchant_key) are the same used on the transacF