REST Card Storage

e-SiTef allows storing credit or voucher cards for further use on payments, reversals or pre-authorizations without the need to request the customer’s card data again. However, it’s important to note that the security code is not stored.

As a result for this operation, the merchant will receive a token, which must be used instead of the customer’s card for performing transactions with e-SiTef.

In case of communication errors, the merchant must perform the same call again.

Expired stored card tokens are removed after 1 year. Example: A stored card token that expires in feb/2020 will be removed in feb/2021.

Call details

Resource: /v1/cards
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

Flow

Examples

Below are some examples of the card storage service call using the cURL tool.

Storing a card

Request:

Card

Digital Wallet

curl
    --request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cards"
    --header "Content-Type: application/json"
    --header "merchant_id: xxxxxxxxxxx"
    --header "merchant_key: xxxxxxxxxxx"
    --data-binary
    {
       "card":{
          "expiry_date":"1222",
          "number":"5555555555555555",
       },
       "authorizer_id":"2",
       "merchant_usn":"16013439434",
       "customer_id":"11122211122"
    }
    --verbose

curl
    --request POST "https://esitef-homologacao.softwareexpress.com.br/e-sitef/api/v1/cards"
    --header "Content-Type: application/json"
    --header "merchant_id: xxxxxxxxxxx"
    --header "merchant_key: xxxxxxxxxxx"
    --data-binary
    {
       "card":{
          "wallet_transaction_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=="
       },
       "authorizer_id":"2",
       "merchant_usn":"16013439434",
       "customer_id":"11122211122"
    }
    --verbose

Response:

{
   "code":"0",
   "message":"OK. Transaction successful.",
   "card":{
      "token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==",
      "suffix":"5555"
   },
   "store":{
      "status":"CON",
      "nsua":"18051600000560A",
      "merchant_usn":"16013439434",
      "customer_id":"11122211122",
      "authorizer_id":"2"
   }
}

Request parameters

The table below describes the request parameters of the card storage service:

Parameter	Description	Format	Mandatory
`authorizer_id`	Code of the authorizer on e-SiTef. Learn more.	< 3 N	YES
`merchant_usn`	Unique sequential number for each order, created by the merchant.	< 12 N	YES
`customer_id`	Identification of the customer for card storage. This identification must be unique for each of the merchant’s users. But attention, this uniqueness assurance is of total responsibility of the merchant, e-SiTef won’t do any validations.	< 20 AN	YES
	card
`number`	Customer’s card number (PAN). It should not be entered with the wallet identifier.	< 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.

`wallet_transaction_id`	Identifier generated by the digital wallet. It should not be entered with the card number.	< 2048 AN	COND.

You should not use the card number and wallet identifier in the same request, as they are different storage modalities.

Response parameters

If successful, 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 card storage service:

Parameter	Description	Format
`code`	e-SiTef response code. Any code different from `0`(zero) means failure. Learn more.	< 4 N
`message`	e-SiTef response message.	< 500 AN
	store
`status`	Status of the storage transaction on e-SiTef. Learn more.	= 3 AN
`nsua`	Unique sequential number of the storage transaction on e-SiTef.	= 15 AN
`merchant_usn`	Unique sequential number generated by the merchant.	< 12 N
`customer_id`	Customer identification for card storage.	< 20 AN
`authorizer_id`	Code of the authorizer used on this storage transaction.	< 3 N
	card
`token`	Identification of the stored card. This token must be used instead of the customer’s card for performing transactions on e-SiTef.	= 88 AN
`suffix`	Last 4 digits of the customer’s card number.	= 4 AN