Payment with card storage
e-SiTef provides to the merchant the option to store, securely, the customer card number for future use on purchase transactions or refunds.
The flow used to perform a payment with card storage is exactly the same used by the payment previously described.
In the case of a payment with storage, the customer’s card is encrypted and then stored on e-SiTef’s database. This storage is performed according to the PCI (Payment Card Industry) standards.
Some observations:
- 1. It’s important to know that only the card number and the expiry date are stored. It isn’t permitted to store the security code (CVV, CVC2, CAV2 or CID) of the card;
- 2. This feature is allowed for credit cards and;
- 3. For the following voucher cards:
- a. Alelo Cultura
- b. Alelo Refeição
- c. Alelo Alimentação
- d. Sodexo Cultura
- e. Sodexo Refeição
- f. Sodexo Alimentação
- g. Coopercard Cultura
- 4. The card is only stored if the payment transaction is performed successfully.
To do a card storage, the merchant must send some extra parameters when initializing a payment transaction on e-SiTef. JSON request with card storage example:
{
"merchant_id":"MERCHANT_ID",
"amount":"100",
"order_id":"12345",
"store_card":"true",
"additional_data":{
"payer":{
"store_identification":"PAYER_ID"
}
}
}
In this case, in addition to the payment transaction NIT, a transaction with nita is created (i.e. the NIT of the storage transaction) that is returned on the creation operation of the payment transaction. JSON response example:
{
"responseCode":0,
"description":"OK. Transaction successful.",
"url":"https://esitef-homologacao.softwareexpress.com.br/e-sitef/do.se?input['nit']=1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"nsuesitef":"123456789012345",
"nit":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqr",
"nita":"12345678901234a",
"nsua":"1234567890abcdefghijklmnopqrstuvwxyz1234567890abcdefghijklmnopqs"
}
In table below, the additional returned fields are presented:
| Parameter | Description | Format |
|---|---|---|
nita | Storage transaction identifier on e-SiTef. | = 65 A |
nsua | Unique Sequential Number of the storage transaction on e-SiTef. | = 15 N |
Store Notification
In the payment with card storage processing, e-SiTef sends two POSTS HTTPS to the merchant’s servers.
e-SiTef will send a POST to the Status Notification URL with the response parameters of the payment transaction and another POST to the HASH submission URL with the response parameters of the card storage transaction, with the stored card identifier.
The fields sent on the storage notification are described in the table below:
| Parameter | Description | Format |
|---|---|---|
nita | NITA code (Storage Transaction Identification Number) that identifies the storage transaction of the card on e-SiTef in case of success. | = 65 A |
nsua | USN generated by e-SiTef for the storage transaction that will be used on back-office reports. | = 15 N |
nsu | Unique Sequential Number for each order, created by the merchant. This USN will be used during the whole communication with the merchant, identifying the order. As this field is used by the merchant, it’s required that this field is formatted and sent by the merchant’s application. | < 12 N |
status | Card storage status on e-SiTef. Learn more. | = 3 A |
hash | Identifier code of the stored card on e-SiTef. | = 88 C |
bin | First six digits of the stored card. | = 6 N |
final | Last four digits of the stored card. | = 4 N |
autorizadora | Authorizer code (on e-SiTef) used by the customer when performing a payment. Learn more. | < 10 N |
Important:
In addition to the above parameters, e-SiTef can return other ones without prior notice. Please, be prepared to receive extra parameters besides the parameters in the table above that can be ignored.
It isn’t necessary to return data on the POST. However, if the POST is not successful (HTTP Status-Code 200: OK), e-SiTef will try again until the configured number of times in the system, before giving up and leaving the transaction as pending notification.
Recurring payment
The recurring payment takes place from the need of the merchant to keep scheduled debits in the customer card, with fixed or variable amounts, with scheduled quantity of occurrences or perennial until the customer determines the termination of the debits.
Recurrence is the capability of e-SiTef to process new payments without the card information of the customer, using the data previously stored. The need comes up in cases of subscription renewal, monthly fee, etc.
Important:
For recurring transactions, only the card number and expiry date will be stored. The security code (CVV, CVC2, CAV2 or CID) can’t be stored or sent on the recurring payment. The storage of the security code, encrypted or not, is prohibited by the PCI SSC (Payment Card Industry Security Standards Council) standards. It is the responsibility of the merchant to negotiate with the acquirers to perform payments without the requirement of the security code. Otherwise, this parameter will be requested during the transaction flow.
However, even if the acquirers allow transactions without the security code (CVV2), there is no guarantee that the issuer (Financial Institution) accepts a transaction with this condition (no security code).
To perform a recurring payment, use our REST payment interface.
Storage data query
The storage data query of the card will follow the following flow:
- The merchant’s server sends a storage query providing its merchant code and the nita
- e-SiTef will send the storage data on the merchant's store notification URL registered on e-SiTef.
The merchant’s server can query the storage data, as in the figure below:
To perform the query, the merchant must do a POST on the following address:
Warning:
Do not change the domain esitef-ec.softwareexpress.com.br for the IP address. Our IP address can be replaced without notice.
Where XXXX is the encrypted NITA with 65 alphanumeric characters, received by the site of e-SiTef on the query order.
The response will be OK if the NITA of the storage is correct and the communication is ended.
Then, e-SiTef will send a POST HTTPS on the HASH sending URL registered by the merchant.
The merchant must be prepared to deal with these parameters and with eventual new parameters that can be sent without previous warning (these new parameters, after being received, can be ignored by the merchant) and with the HTTPS (SSL) call on the registered HASH sending URL.
The POST HTTPS of the e-SiTef may not be immediate, but yes, it will be asynchronous, in which the time can vary according to the server’s load and the Internet. If there’s any problem on the sending, e-SiTef will try to re-send the message after an established period of time.
The returned parameters are same described in the Store Notification section.