External origin payment confirmation service

Introduction#

The external origin payment confirmation functionality allows that a payment transaction created outside of e-SiTef can be confirmed inside of e-SiTef.

Currently this functionality allows payment transaction confirmation done in SiTef.

This operation is divided in two steps:

  1. The creation of a transaction of “Confirmation” type that represents the payment transaction externally created.
  2. The confirmation of the payment of this transaction.

Case of success

The flow below shows the happy path where a transaction is started and then the confirmation is sent.

External origin payment confirmation transaction creation#

Call details#

  • Resource: /v1/transactions
  • HTTP Method: POST
  • Request format: JSON
  • Response format: JSON
  • Header parameters:
ParameterDescriptionFormatMandatory
merchant_ide-SiTef store's ID. Production and certification IDs are different.≤ 15 AYES
merchant_keyStore authentication key in e-SiTef. Production and certification keys are different.< 80 AYES
Content-TypeFixed value "application/json"= 15 AYES

Example#

Request

curl --location --request POST 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/transactions'
--header 'merchant_id: xxxxxxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxxxxxxx'
--header 'Content-Type: application/json'
--data-raw '{
"merchant_usn": "21042858195",
"order_id": "1621949459257",
"amount": "300",
"transaction_type": "confirmation",
"is_transaction_origin_external": "true"
}'
--verbose

Response

{
"code": "0",
"message": "OK. Transaction successful.",
"confirmation": {
"status": "PPC",
"nit": "1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"order_id": "1621949459257",
"merchant_usn": "21042858195",
"amount": "300"
}
}

Request parameters#

The table below shows fields for the creation of external origin payment confirmation transaction.

ParameterDescriptionFormatMandatory
amountTotal purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas< 12NYES
merchant_usnUnique 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 NNO
order_idOrder 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 ANNO
transaction_typeFixed value confirmation= 15 AYES
is_transaction_origin_externalFixed value true= 5 ANYES

Response parameters#

In case of success, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes de response parameters of the transaction creation service:

ParameterDescriptionFormat
codee-SiTef response code. Any code different from 0 means failure. Learn more.< 4 N
messagee-SiTef response message.< 500 AN
payment
statusStatus of the payment transaction on e-SiTef. Learn more.= 3 AN
nitPayment transaction identifier on e-SiTef.= 64 AN
order_idOrder code sent by the merchant on the creation of the transaction.< 40 AN
merchant_usnUnique sequential number sent by the merchant on the creation of the transaction.< 12 N
amountTotal price of the purchase specified by the merchant (in cents) on the creation of the transaction.< 12 N

External origin payment confirmation transaction effectuation#

Call details#

  • Resource: /v1/payments/{nit}
  • HTTP Method: PUT
  • Request format: JSON and query string
  • Response format: JSON
  • Header parameters:
ParameterDescriptionFormatMandatory
merchant_ide-SiTef store's ID. Production and certification IDs are different.≤ 15 AYES
merchant_keyStore authentication key in e-SiTef. Production and certification keys are different.< 80 AYES
Content-TypeFixed value "application/json"= 15 AYES

Example#

Request

curl --location --request PUT 'https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/bacd62eb62c27f4bf2eae9cef74c93a02e831985eccb6de371628fd272ee5474?confirm=true'
--header 'merchant_id: xxxxxxxxxxxxxx'
--header 'merchant_key: xxxxxxxxxxxxx'
--header 'Content-Type: application/json'
--data-raw '{
"authorizer_id": "1",
"installments": "1",
"installment_type": "4",
"confirmation_data": "123456789012",
"acquirer": {
"route_id": "5",
"authorization_number": "212991",
"identification_number": "11111111111",
"order_id": "1621949459257",
"authorizer_date": "21/05/2021",
"host_usn": "000212991 ",
"terminal": "HA000006",
"company_code": "00000000"
}
}'
--verbose

Response

{
"code": "0",
"message": "OK. Transaction successful.",
"payment": {
"authorizer_code": "130",
"status": "CON",
"acquirer_id": "5",
"host_usn": "000212991 "
}
}

Request parameters - query string#

ParameterDescriptionFormatMandatory
confirmThis field must be sent with the value true if you want to confirm the payment, or false if you want to undo the payment.< 5 T/FYES

Request parameters - JSON#

ParameterDescriptionFormatMandatory
amountTotal purchase amount (in cents). Example: 1.00 = 100 or 1,100.00 = 110000 – send amount without dots or commas. If not informed, the value informed in the transaction creation is used.< 12NNO
authorizer_idCode of the authorizer on e-SiTef. It must be the same value sent on the pre autorization.< 3 NYES
installmentsNumber of installments. Send 1 for spot sales.< 2 NNO(*)
installment_typeInstallment financing type:
Value 3 = installments with interest.
Value 4 = installments without interest (use this value also on spot sales).
Value 6 = installments with interest (IATA).
Value 7 = installments without interest (IATA).
The IATA financing types are only used by companies that work with air transportation.
< 2 NNO(*)
confirmation_dataPayment information returned by SiTef after effectuating a payment. This parameter is fundamental for the success of the confirmation. It is used by SiTef to identify the payment.< 128 ANNO
acquirer
routing_idRouting information used by the payment done outside of e-SiTef. This parameter is fundamental for the success of the confirmation. It is used to identify the routing inside of SiTef.< 5 NYES
host_usnHost/authorizer USN of the transaction to be confirmed.= 9 NNO(*)
authorization_numberAuthorization number of the transaction to be confirmed.< 6 NNO(*)
authorizer_datePre-authorization date returned by the authorizer in DD/MM/YYYY format.= 10 DNO(*)
order_idOrder code used in the pre-authorization initiated outside e-SiTef.< 40 ANNO(*)
identification_numberCPF or CNPJ used in the pre-authorization initiated outside e-SiTef.< 20 ANNO(*)
terminalSiTef terminal code. In absence e-SiTef will generate a random terminal code.= 8 ANNO(*)
company_codeSiTef company code. In absence e-SiTef will use company code from merchant configuration.= 8 NNO(*)

Note: All fields marked with NO(*) are optional and, if informed, e-SiTef will not be able to consist any one of them because they are not sent to SiTef in the confirmation operation.

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 payment confirmation service:

ParameterDescriptionFormat
codee-SiTef response code. Any code different from 0 means failure. Learn more.< 4 N
messagee-SiTef response message.< 500 AN
payment
statusStatus of the payment transaction on e-SiTef. Learn more.= 3 AN
host_usnHost USN.< 15 AN
payment_datePayment authorization date on e-SiTef in DD/MM/YYYY'T'HH:mm format. Example: 13/07/2017T16:03= 16 D