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:

The creation of a transaction of “Confirmation” type that represents the payment transaction externally created.
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:

Parameter	Description	Format	Mandatory
`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
`Content-Type`	Fixed value "application/json"	= 15 A	YES

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.

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
`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 `confirmation`	= 15 A	YES
`is_transaction_origin_external`	Fixed value `true`	= 5 AN	YES

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:

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
`status`	Status of the payment transaction on e-SiTef. Learn more.	= 3 AN
`nit`	Payment transaction identifier 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

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:

Parameter	Description	Format	Mandatory
`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
`Content-Type`	Fixed value "application/json"	= 15 A	YES

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

Parameter	Description	Format	Mandatory
`confirm`	This 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/F	YES

Request parameters - JSON

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. If not informed, the value informed in the transaction creation is used.	< 12N	NO
`authorizer_id`	Code of the authorizer on e-SiTef. It must be the same value sent on the pre autorization.	< 3 N	YES
`installments`	Number of installments. Send `1` for spot sales.	< 2 N	NO(*)
`installment_type`	Installment 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 N	NO(*)
`confirmation_data`	Payment 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 AN	NO
	acquirer
`route_id`	Routing 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 N	YES
`host_usn`	Host/authorizer USN of the transaction to be confirmed.	= 9 N	NO(*)
`authorization_number`	Authorization number of the transaction to be confirmed.	< 6 N	NO(*)
`authorizer_date`	Pre-authorization date returned by the authorizer in `DD/MM/YYYY` format.	= 10 D	NO(*)
`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	NO(*)
`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(*)

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:

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
`status`	Status of the payment transaction on e-SiTef. Learn more.	= 3 AN
`host_usn`	Host USN.	< 15 AN
`payment_date`	Payment authorization date on e-SiTef in `DD/MM/YYYY'T'HH:mm` format. Example: 13/07/2017T16:03	= 16 D