Recharge effectuation service

Call details

Resource: /v3/recharge/{nit}
HTTP Method: PUT
Request format: JSON
Response format: JSON
Header parameters:

Parameter	Description	Format	Mandatory
`Content-Type`	It must be sent with the value `application/json`.	= 15 AN	YES
`Authorization`	Authenticity signature in `Bearer {signature}` format. Learn more. Example: `Bearer hh39458f73hf45324765ft349h5f73t4h95f34`. This field is mandatory if the transaction was created with the signature process.	< 2000 AN	COND.

Examples

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

Recharge type `normal` with payment

Request:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "hashes":{
         "general":"0000000000000000"
      },
      "dealer":{
         "code":"1",
         "type_code":"03",
         "branch":{
            "code":"98006000000"
         }
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000",
      "amount_key":"3",
      "used_payment_methods":[
         "11",
         "12"
      ],
      "answers":[
         {
            "code":"1",
            "description":"resposta"
         },
         {
            "code":"2",
            "description":"resposta2"
         }
      ],
      "terminal_type":"03",
      "cpf":"8298374982374",
      "cnpj":"123121333000123",
      "zip_code":"01310100",
      "payment":{
         "amount":"12",
         "authorizer_id":"1",
         "customer_id":"12341234",
         "merchant_key":"OIAUSWHFN012375901J23047FNN00UYWHN0R871Y2ND87",
         "installment":{
            "number":"2",
            "type":"4"
         },
         "card":{
            "number":"1111111111111111",
            "token":"",
            "security_code":"123",
            "expiry_date":"1222"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ]
      }
   }
}
--verbose

Response:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      },
      "payment_methods":{
         "max":4,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      },
      "payment":{
         "status":"PPC",
         "amount":"12",
         "type":"C",
         "esitef":{
            "usn":"098765432109876",
            "date":"12/12/2012 12:12"
         },
         "customer":{
            "receipt":"nwiugrnboinb APROVADO via do cliente"
         },
         "merchant":{
            "receipt":"nwiugrnboinb APROVADO via do estabelecimento "
         },
         "authorizer_id":"1",
         "acquirer":"CIELO",
         "authorization":{
            "number":"163457212",
            "sitef_usn":"456456",
            "host_usn":"654654",
            "tid":"7334312a2",
            "eci":"fr3u214wf71",
            "sitef_date":"12122012"
         },
         "analysis":{
            "status":"PEN",
            "code":"0",
            "message":"aprovado"
         },
         "extra_param":[
            {
               "key":"CRIPTO",
               "value":"1"
            }
         ],
         "sitef":{
            "code":"000"
         }
      }
   }
}

Recharge type `normal` without payment

Request:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "dealer":{
         "code":"1"
      },
      "phone":{
         "ddd":"11",
         "number":"123456789"
      },
      "amount":"3000"
   }
}
--verbose

Response:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      },
      "payment_methods":{
         "max":4,
         "available":[
            {
               "name":"dinheiro"
            },
            {
               "name":"cheque"
            }
         ]
      }
   }
}

Recharge type `others`

Request:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "dealer":{
         "code":"901",
         "type_code":"03",
         "branch":{
            "code":"98006000000"
         }
      },
      "amount":"3000"
   }
}
--verbose

Response:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"12344231",
      "merchant_usn":"5123",
      "esitef":{
         "message":"OK",
         "code":"0",
         "usn":"123456789012345"
      },
      "sitef":{
         "message":"OK",
         "code":"0"
      },
      "host":{
         "message":"OK",
         "code":"0"
      },
      "acquirer":{
         "branch_code":"cod filial",
         "merchant_code":"codigoEstab"
      },
      "authorization":{
         "confirmation_data":"000033333",
         "authorizer_date":"20150514",
         "authorizer_time":"1100",
         "host_usn":"11122",
         "sitef_usn":"333",
         "number":"332234"
      },
      "customer":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do cliente"
      },
      "merchant":{
         "total_copies":3,
         "receipt":"COMPROVANTE DE RECARGA via do estabelecimento"
      }
   }
}

Recharge type `invoice`

Request:

curl
--request PUT "https://esitef-homologacao.softwareexpress.com.br/e-sitef/v3/recharge/asdfghjk12345678asdfghjk12345678asdfghjk12345678asdfghjk12345678"
--header "Content-Type: application/json"
--data-binary
{
   "do_recharge_request":{
      "hashes":{
         "general":"85E791AD85E791AD"
      },
      "dealer":{
         "code":"800",
         "branch":{
            "code":"80019000000"
         }
      },
      "amount":"6339",
      "terminal_type":"04",
      "cpf":"12312312312",
      "cnpj":"11110110000101",
      "zip_code":"12345678",
      "invoice":{
         "bar_code":"88888888888888888888888888888888888888888888",
         "description":"Boleto Parcial Credito Manual",
         "expiry_date":"21082007",
         "reference_data":"082007",
         "echo":"12340000000"
      }
   }
}
--verbose

Response:

{
   "do_recharge_response":{
      "status":"PPC",
      "order_id":"31045431771",
      "merchant_usn":"2047986911",
      "esitef":{
         "message":"OK. Transaction successful.",
         "code":"0",
         "usn":"200831056294572"
      },
      "sitef":{
         "message":"Transacao Aprovada",
         "code":"000"
      },
      "acquirer":{
         "merchant_code":"302800000000000"
      },
      "authorization":{
         "confirmation_data":"0831310011A6",
         "authorizer_date":"0831",
         "authorizer_time":"165459",
         "host_usn":"000310011",
         "sitef_usn":"310011",
         "number":"000000"
      },
      "customer":{
         "receipt":"----- RECEIPT -----"
      },
      "merchant":{
         "receipt":"----- RECEIPT -----"
      },
      "payment_methods":{
         "max":"4",
         "available":[
            {
               "name":"00"
            },
            {
               "name":"01"
            },
            {
               "name":"02:03-07-08-09-10-14"
            },
            {
               "name":"03:03-07-08-09-10-14"
            },
            {
               "name":"04:10"
            },
            {
               "name":"05:10"
            },
            {
               "name":"06:10"
            }
         ]
      },
      "hashes":{
         "general":"85E791AD85E791AD",
         "wallet":""
      },
      "send_payment_methods":"true"
   }
}

Request parameters

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

Parameter	Description	Format	Mandatory
`nit`	Identification of the recharge transaction on e-SiTef	= 64 AN	YES
`amount`	Recharge amount in cents	< 12 N	YES
`amount_key`	Recharge amount key	< 10 AN	NO
`terminal_type`	`01` - POS `02` - TU `03` - TAS `04` - Internet `05` - POS-Sitef/POS	= 2 N	NO
`cpf`	Customer CPF	< 20 AN	NO
`cnpj`	Customer CNPJ	< 20 AN	NO
`zip_code`	Customer zip code	< 9 AN	NO
	hashes
`general`	Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others).	= 16 AN	NO
	dealer
`code`	Dealer code	< 3 N	YES
`type_code`	Dealer type code	< 2 N	YES
	dealer.branch
`code`	Dealer branch code. Only mandatory for recharge type `others`.	11 N	COND.
	phone
`phone.ddd`	Phone area code (DDD). Only mandatory for recharge type `normal`.	= 2 N	COND.
`phone.number`	Phone number. Only mandatory for recharge type `normal`.	< 9 N	COND.
	answers[] This field adds a list of answers. Mandatory if questions were received on the list branch data service.
`code`	Code of the question to be answered	< 20 AN	COND.
`description`	Answer of the question	< 200 AN	COND.
	invoice This object contains mandatory fields for invoice payment (recharge type `invoice`).
`bar_code`	Bar code of the chosen invoice.	= 48 N	YES for `invoice` type
`description`	Description of the chosen invoice.	< 64 AN	YES for `invoice` type
`expiry_date`	Expiry date of the chosen invoice in `DDMMYYYY` format.	= 8 N	YES for `invoice` type
`reference_data`	Reference data of the chosen invoice.	< 32 AN	YES for `invoice` type
`echo`	`echo` field value as received on the list branch data call.	< 11 N	YES for `invoice` type
	payment This element should only be sent if you want to make a payment linked to the recharge.* Attention: Payment is only allowed in the `normal` recharge type. For the `others` recharge type the transaction will be invalidated.
`amount`	Payment amount in cents	< 12 N	YES*
`authorizer_id`	Authorizer ID on e-SiTef. Learn more.	< 5 N	YES*
`customer_id`	Identity document of the customer. Use alphanumeric characters only	< 20 AN	NO
`merchant_key`	Merchant key registered on e-SiTef. Must be the same merchant used to do the recharge.	< 80 AN	YES*
	payment.installment
`number`	Number of installments	< 2 N	YES*
`type`	Installment financing type: `3` - installments with interest `4` - installments without interest (use this value as default for spot sales) `6` - installments with interest (IATA) `7` - installments without interest (IATA)	= 1 N	YES*
	payment.card
`number`	Card number.	< 19 N	YES*
`token`	Card token stored on e-SiTef.	= 88 AN	YES*
`security_code`	Optional field, if sent, the main SiTef merchant code will be used instead of the recurrence code (which does not require a security code). It's mandatory depending on the agreement signed with the Card Administrators.	< 5 N	COND.
`expiry_date`	Expiry date in `MMYY` format	= 4 N	YES*
	payment.extra_param[] This field adds a list of extra parameters.
`key`	Extra parameter key	N/A	NO
`value`	Extra parameter value	N/A	NO
	used_payment_methods[] Used payment methods. This field adds a list of values that must be sent as described below.

Sending the `used_payment_methods` field

The store must use the used_payment_methods field itself to indicate to e-SiTef which payment methods were used to pay for a particular transaction, such as a recharge.

The amount of data to be written to the used_payment_methods field is limited by the payment_methods.max field. If, for example, the value 3 has been received in the payment_methods.max field, then the store can only store 3 information in the used_payment_methods field.

For each used payment method, an element (given) must be saved in the used_payment_methods field. The data to be saved in the used_payment_methods field has the following format:

TypeN:AmountN:IDCollectionN1:CollectionDataN1-IDCollectionN2:CollectionDataN2-...-IDCollectionNn:CollectionDataNn

Where:

TypeN: indicates the used payment method (as shown in the table above).
AmountN: indicates the amount used with this payment method, with two decimal digits, without the comma.
IDCollectionNn: indicates the field ID that was collected by the store (as shown in the table above).
CollectionDataNn: Indicates the content collected by the store for this field.

Notes:

If for a given payment method no field must be collected by the store, the used_payment_methods field must be valued with the following data: TypeN:AmountN.

The consistency of the values (sum of the various used payment methods, totaling the value of the transaction made) must be done by the store, and e-SiTef will only use the values the same way they were sent.

Example

Let's assume that in the execution of a recharge transaction, the store got the value 2 in the payment_methods.max field and the following values of the used_payment_methods field:

00
02:03-07-10-13(5,125)
03:10

The value 2 received in the payment_methods.max field indicates to the store that the payment of the recharge can only be done with a maximum of 2 different payment methods.

Assuming that the payment of the recharge was done as follows: R$ 30.00 in cash and R$ 20.00 with debit card processed by the acquirer Rede (Destination Network = 5; Host USN = 123456789; Confirmation data = 0520200001A6). In this case, the used_payment_methods field should be valued with the following data:

00:3000
02:2000:03:5-07:123456789-10:0520200001A6

Sending card data for payment

If it's desired to send the card token stored on e-SiTef, the other card data (card.number, card.expiry_date) will not be considered. If you want to send the open card data, the token should not be sent.

Response parameters

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

Parameter	Description	Format
`status`	Status of the recharge transaction on e-SiTef. Learn more.	= 3 AN
`order_id`	Order code generated by the store.	< 20 AN
`merchant_usn`	USN of the transaction generated by the store.	< 12 N
`tv_package_subscription_codes[]`	TV package subscription codes.	< 32 AN
`resubmit_transaction`	If this field receives the value `true`, the merchant must resend the recharge effectuation request with the `answers` field filled in as follows: `"answers":[{"code":"126","description":"<one the codes returned in the tv_package_subscription_codes field>"}]` In this case, the transaction status will be returned as `AGU`. This flow is only possible on a TV Recharge.	T/F
`send_payment_methods`	Flag that indicates that the payment methods must be sent on the next transaction. It will have the value `true` when positive.	< 5 AN
	esitef
`code`	e-SiTef response code. Any code different from `0`(zero) means failure. Learn more.	< 4 N
`message`	e-SiTef response message.	< 500 AN
`usn`	USN of the recharge transaction on e-SiTef	= 15 N
	sitef
`code`	SiTef response code	= 3 AN
`message`	SiTef response message	< 500 AN
	host
`code`	Response code returned by the authorizer	< 4 AN
`message`	Message returned by the authorizer	< 64 AN
	acquirer
`branch_code`	Recharge branch code	< 5 N
`merchant_code`	Merchant code registered on the acquirer	< 15 N
	authorization
`confirmation_data`	Confirmation code	< 128 AN
`authorizer_date`	Authorization date on the authorizer in `MMDD` format	= 4 N
`authorizer_time`	Authorization time on the authorizer in `HHmmSS` format	= 6 N
`host_usn`	Host USN	< 20 N
`sitef_usn`	SiTef USN	< 10 N
`number`	Authorization number	< 6 N
	customer
`total_copies`	Number of copies of the customer receipt	< 2 N
`receipt`	Customer receipt	< 4000 AN
	merchant
`total_copies`	Number of copies of the merchant receipt	< 2 N
`receipt`	Merchant receipt	< 4000 AN
	hashes
`general`	Identification code of the table with the data related to the recharges (dealers, branches, amount ranges, expiration periods, among others).	= 16 AN
`wallet`	Wallet hash.	< 32 AN
	payment_methods
`max`	Maximum number of payment methods	< 2 N
	payment_methods.available[] This field adds a list of available payment methods.
`name`	Name of the available payment method. Learn more.	< 200 AN
	payment This element is only returned if a payment related to a recharged was sent.
`status`	Status of the payment transaction on e-SiTef. Learn more.	= 3 AN
`amount`	Amount of the payment, the same sent on the creation of the payment transaction.	< 12 AN
`type`	Payment type of the chosen authorizer: `B` = boleto `C` = credit `D` = debit `P` = credit card Private Label `T` = bank transfer `G` = gift card `O` = other payment methods	= 1A
`authorizer_id`	Authorizer ID on e-SiTef	< 5 N
`acquirer`	Payment type	< 50 AN
	payment.esitef
`usn`	e-SiTef USN	< 15 AN
`date`	Payment date on e-SiTef in `DD/MM/YYYY hh:mm` format.	< 19A
	payment.sitef
`code`	Response code returned by SiTef	= 3 AN
	payment.customer
`receipt`	Payment customer receipt	< 4000 AN
	payment.merchant
`receipt`	Payment merchant receipt	< 4000 AN
	payment.authorization
`number`	Payment authorization number	< 6 AN
`sitef_usn`	SiTef USN	< 15 AN
`host_usn`	Authorizer USN	< 15 AN
`tid`	ID of the transaction on the authorizer, returned by some payment types.	< 40 AN
`eci`	Eletronic commerce indicator returned by some payment types.	< 3 AN
`sitef_date`	Payment date on SiTef in `DD/MM/YYYY hh:mm` format.	< 19 AN
	payment.analysis
`status`	Status of the transaction on the analysis institution.	= 3 AN
`code`	Response code of the risk analysis.	< 4 AN
`message`	Response message of the risk analysis.	< 100 AN
	payment.extra_param[]
`key`	Extra parameter key	N/A
`value`	Extra parameter value	N/A

Important:

In the case of recharges of other products (pins, games), the pin will be returned only once as part of the payment.customer.receipt field. Because it is a sensitive field, e-SiTef does not store it, so subsequent status queries will not return the pin. If a problem occurs after the return of the pin by e-SiTef, the pin can't be recovered and it will be necessary to generate another pin.

Call details

Examples

Recharge type normal with payment

Recharge type normal without payment

Recharge type others

Recharge type invoice

Request parameters

Sending the used_payment_methods field

Sending card data for payment

Response parameters

Recharge type `normal` with payment

Recharge type `normal` without payment

Recharge type `others`

Recharge type `invoice`

Sending the `used_payment_methods` field