Payment effectuation service

After consuming the transaction creation service and obtaining a NIT, it's possible to proceed to the next step of the flow: calling the payment effectuation service. This operation must also be consumed on payment with schedule flows. In this case, e-SiTef assures that the schedule will only be activated if the payment is confirmed.

Call details

• Resource: /v1/payments/{nit}
• HTTP Method: POST
• Request format: JSON
• 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
Content-Type	It must be sent with the value application/json.	= 15 AN	YES

Examples

Below are some examples of the payment effectuation service call using the cURL tool.

Payment with automatic confirmation

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   }
}
--verbose

Response:

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

Payment with late confirmation

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   }
}
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"PPC",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13035748930",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T15:58",
      "authorization_number":"132031",
      "merchant_usn":"13035748930",
      "esitef_usn":"170713097340340",
      "sitef_usn":"132031",
      "host_usn":"999132031   ",
      "payment_date":"13/07/2017T15:58",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   }
}

Payment with schedule

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   }
}
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"13040222890",
      "customer_receipt":"==== CUPOM COMPRADOR ====",
      "merchant_receipt":"==== CUPOM ESTABELECIMENTO ====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"13/07/2017T16:03",
      "authorization_number":"132032",
      "merchant_usn":"13040222890",
      "esitef_usn":"170713097340360",
      "sitef_usn":"132032",
      "host_usn":"999132032   ",
      "payment_date":"13/07/2017T16:03",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005"
   },
   "schedule":{
      "status":"ATV",
      "sid":"qwertyuiopasdfghjklzxcvbnm0123456789qwertyuiopasdfghjklzxcvbnm01",
      "schedule_usn":"170713000000020",
      "amount":"900",
      "initial_date":"03/08/2017",
      "next_date":"03/08/2017",
      "number_of_times":"3",
      "installments":"1",
      "installment_type":"4",
      "soft_descriptor":"Subscription",
      "show_times_invoice":"false"
   }
}

Payment with stored card

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "token":"g16hJtpdU6XEN3FP-ApQ9pKTGII5Fa9Y12tRX-qfyC-+BUCV5OaFn807zwwOR6rDtKoRnIJg0QbikaJqJqosyQ=="  
   }
}
--verbose

Response:

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

Payment with Via Certa Financiadora with financing plans

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "security_code":"123",
      "number":"5555555555555555"
   },
   "acquirer":{
      "financing_plan":"0302"
   }
}
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"21105507366",
      "customer_receipt":"====CUPOM COMPRADOR====",
      "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
      "authorizer_id":"313",
      "acquirer_id":"1313",
      "acquirer_name":"Via Certa Financiadora",
      "authorizer_date":"21/11/2017T10:55",
      "authorization_number":"211982",
      "merchant_usn":"21105507366",
      "esitef_usn":"171121108905101",
      "sitef_usn":"211982",
      "host_usn":"999211982   ",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"0000000000000313",
      "payment_date":"21/11/2017T10:55"
   }
}

Payment with prefixes

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "expiry_date":"1222",
      "security_code":"123",
      "number":"5555555555555555"
   },
   "acquirer":{
      "prefixes":{
         "TRAT":"1"
      }
   }
}
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code":"000",
      "authorizer_message":"Transacao OK",
      "status":"CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "order_id":"21105507366",
      "customer_receipt":"====CUPOM COMPRADOR====",
      "merchant_receipt":"====CUPOM ESTABELECIMENTO====",
      "authorizer_id":"2",
      "acquirer_id":"1005",
      "acquirer_name":"Redecard",
      "authorizer_date":"21/11/2017T10:55",
      "authorization_number":"211981",
      "merchant_usn":"21105507366",
      "esitef_usn":"171121108905100",
      "sitef_usn":"211981",
      "host_usn":"999211981   ",
      "amount":"1000",
      "payment_type":"C",
      "issuer":"2",
      "authorizer_merchant_id":"000000000000005",
      "payment_date":"21/11/2017T10:55"
   }
}

Split Payment for BIN and Sipag routings (SiTef)

Request:

curl
--request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/payments/1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr"
--header "Content-Type: application/json"
--header "merchant_id: xxxxxxxx"
--header "merchant_key: xxxxxxxxxxx"
--data-binary
{
   "card":{
      "number":"5555555555555555",
      "expiry_date":"1222",
      "security_code":"123"
   },
   "acquirer":{
      "submerchant_split":[
         {
            "submerchant_code":"empresa01",
            "submerchant_amount":"10"
         },
         {
            "submerchant_code":"empresa02",
            "submerchant_amount":"20"
         },
         {
            "submerchant_code":"empresa03",
            "submerchant_amount":"20"
         },
         {
            "submerchant_code":"empresa04",
            "submerchant_amount":"30"
         },
         {
            "submerchant_code":"empresa05",
            "submerchant_amount":"30"
         }
      ]
   }
}
--verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "payment":{
      "authorizer_code": "000",
      "authorizer_message": "APROVADA",
      "status": "CON",
      "nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
      "authorizer_id": "1",
      "acquirer_id": "229",
      "acquirer_name": "Bin",
      "authorizer_date": "29/03/2019T13:26",
      "authorization_number": "000058",
      "merchant_usn": "20180809",
      "esitef_usn": "190329026585100",
      "sitef_usn": "000058",
      "host_usn": "003000058   ",
      "amount": "13000",
      "payment_type": "C",
      "issuer": "1",
      "authorizer_merchant_id": "000000000000000",
      "payment_date": "29/03/2019T13:26"   
   }
}

Request parameters

The table below describes the request parameters of the payment effectuation service:

Parameter	Description	Format	Mandatory
authorizer_id	Code of the authorizer on e-SiTef. Learn more. If this field wasn't sent during the transaction creation phase, it will become mandatory when consuming the payment effectuation service.	< 3 N	COND.
customer_postal_code	User's postal code (CEP in Brazil). It must be sent for iCards via SiTef routed transactions, if the is_customer_postal_code_required field in card query service is marked as true.	< 8 N	COND.
mcc	The MCC (Merchant Category Code) is a code that classifies the business by the type of goods or services it provides.	< 4 N	NO
subacquirer_merchant_id	It is the merchant identification for the subacquirer.	< 22 N	NO
card	Card data.
number	Customer's card number (PAN).	< 19 N	YES
expiry_date	Card expiry date in MMYY format. Its requirement depends on the selected acquirer. In most cases, this field is mandatory.	= 4 N	COND.
security_code	Card security code. This field may not be mandatory if the company has an agreement in the contract established with the acquirers, only for payments of certain areas. Important: a payment with schedule implies on storing the customer's card data on e-SiTef's environment. However, for security reasons, the security code cannot be stored. Therefore, the scheduled payments will always be executed without the security code.	< 5 N	COND.
holder	Card holder name. Only mandatory for payments with e-Rede, GetNet WS and VR (SmartNet).	< 30 AN	COND.
token	HASH of a card stored on e-SiTef. It's not allowed to send an ‘open' card number (number field) and a stored card (token field) on the same request.	= 88 AN	NO
wallet_transaction_id	Digital wallet transaction ID. Currently, this functionality is only available to the Visa Checkout and VEE (via CardSE via SiTef) authorizer. It isn't allowed to send an ‘open' card number (number field), a stored card (token field) and a wallet_transaction_id on the same request.	< 25 AN	NO
initial_wallet_transaction_id	Informs if the wallet id (wallet_transaction_id) is being used for the first time. If so, send the value true, otherwise send false.	< 5 T/F	NO
external_authentication	This element receives MPI authentication result 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.
financing_plan	Financing Plan code used for Via Certa Financiadora routed payments, only in case of installments plan with interest.	< 4 N	NO
special_code	Conductor/Renner SiTef routings general use code.	< 6 N	NO
recurrency	Flag that defines whether or not the payment is recurring. Accepted all routings via SiTef, Cielo e-Commerce, Global Payments WS, Stone WS, e.Rede REST and GetnetWS routings. In the case of a Stone WS recurrency, it is mandatory to send only one of the fields below, is_first_recurring OR is_subsequent_recurring.	< 5 T/F	NO
recurrency_tid	First transaction's TID. This field tells the first and the subsequent transactions apart. Use only if it is a recurrent payment. This field is used only for e.Rede REST routings using the brands Visa or Mastercard and for GetnetWS routing.	< 16 AN	NO
is_first_recurring	Flag used only for StoneWS routing. Indicates that the transaction is the first in a series of recurring transactions.	< 5 T/F	COND.
is_subsequent_recurring	Flag used only for StoneWS routing. It indicates that the transaction is the second or nth of a series of recurring transactions, where n > 2.	< 5 T/F	COND.
product_code	Product code. It is mandatory in routing via Marisa.	< 6 N	COND.
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
acquirer.vouchers_filter[]	Choice of vouchers that will not be accepted. Options of "Vouchers": 01 - Food, 02 - Meal, 03 - Culture, 04 - Fuel, 05 - Benefit. Example: You do not want to accept Vouchers: Culture, Fuel, Benefit. You must send: "vouchers_filter": ["03", "04", "05"]
acquirer.prefixes	Element for sending SiTef prefixes, like CICLOS, CPLANO and VLRADD. If the prefix that was sent is not supported by card, e-SiTef will invalidate the transaction, preventing that a false impression of the use of a functionality is given. Example: { "key" : "value" } -> { "CICLO" : "01" }
key	Prefix name.	< 1024 AN	NO
value	Prefix value.	< 1024 AN	NO
acquirer.submerchant_split[]	It consists of an array for split payments, unique to BIN and Sipag routing, both via SiTef. It allows the division of parts of the total amount of the payment among other merchants. The maximum number of items allowed in this array is 5 items.
submerchant_code	BIN/Sipag merchant code	< 51 AN	NO
submerchant_amount	Transaction amount related to the merchant	< 12 N	NO

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

If successful, the HTTP response code will be 201. Any other code must be interpreted as an error. The table below describes the response parameters of the payment effectuation 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
authentication_url	Authentication URL returned on payment with authentication flows. Only available to Cielo e-Commerce.	< 56 AN
balance	Current balance after payments with Gift cards.	< 12 N
recurrency_tid	First transaction's id (TID) on the card brand. Returned only if it is a recurrent payment. This field is used only for e.Rede REST routings using the brands Visa or Mastercard.	< 16 AN
	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
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
terminal_id	Terminal code used in the transaction	< 8 AN