Card Tokenization

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 Carat Portal. The production and certification codes will be different.	< 15 AN	YES
`merchant_key`	Merchant authentication key on Carat Portal. 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:

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl 
    --request POST "https://{{url}}/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":"5444445555555555",
       },
       "authorizer_id":"2",
       "merchant_usn":"16013439434",
       "customer_id":"11122211122"
    }
    --verbose

To use this example, don't forget to define the variable {{url}} with the value
esitef-homologacao.softwareexpress.com.br

curl 
    --request POST "https://{{url}}/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",
      "bin": "544444"

   },
   "store":{
      "status":"CON",
      "nsua":"18051600000560A",
      "merchant_usn":"16013439434",
      "customer_id":"11122211122",
      "authorizer_id":"2"
   }
}

Response codes

See reference on API codes - response codes

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 Carat Portal. Learn more.	< 3 N	YES
`merchant_usn`	Unique sequential number for each order, created by the merchant.	< 12 N	NO
`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, Carat Portal 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`	Carat Portal response code. Any code different from `0`(zero) means failure. Learn more.	< 4 N
`message`	Carat Portal response message.	< 500 AN
store
`status`	Status of the storage transaction on Carat Portal. Learn more.	= 3 AN
`nsua`	Unique sequential number of the storage transaction on Carat Portal.	= 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 Carat Portal.	= 88 AN
`suffix`	Last 4 digits of the customer’s card number.	= 4 AN
`bin`	First 6 digits of the customer’s card.	= 6 AN