Payment with card storage service
Carat Portal 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 Carat Portal’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 Carat Portal. JSON request with card storage example:
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:
To use this example, don't forget to define the variable {{url}} to the value
esitef-homologacao.softwareexpress.com.br
In table below, the additional returned fields are presented:
| Parameter | Description | Format |
|---|---|---|
nita | Storage transaction identifier on Carat Portal. | = 65 A |
nsua | Unique Sequential Number of the storage transaction on Carat Portal. | = 15 N |
Store Notification#
In the payment with card storage processing, Carat Portal sends two POSTS HTTPS to the merchant’s servers.
Carat Portal 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 Carat Portal in case of success. | = 65 A |
nsua | USN generated by Carat Portal 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 Carat Portal. Learn more. | = 3 A |
hash | Identifier code of the stored card on Carat Portal. | = 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 Carat Portal) used by the customer when performing a payment. Learn more. | < 10 N |
Important:
In addition to the above parameters, Carat Portal 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), Carat Portal 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 Carat Portal 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
- Carat Portal will send the storage data on the merchant's store notification URL registered on Carat Portal.
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:
| Homologation Environment |
|---|
| https://esitef-homologacao.softwareexpress.com.br/e-sitef-hml/armazenamento/consultarArmazenamento.se?nita=XXXX |
| Production Environment |
| https://eesitef.softwareexpress.com.br/e-sitef/armazenamento/consultarArmazenamento.se?nita=XXXX |
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 Carat Portal on the query order.
The response will be OK if the NITA of the storage is correct and the communication is ended.
Then, Carat Portal 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 Carat Portal 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, Carat Portal will try to re-send the message after an established period of time.
The returned parameters are same described in the Store Notification section.