Card Tokenization

Call details#

  • Resource: /v1/cards
  • HTTP Method: POST
  • Request format: JSON
  • Response format: JSON
  • Header parameters:
ParameterDescriptionFormatMandatory
merchant_idMerchant code on Carat Portal. The production and certification codes will be different.< 15 ANYES
merchant_keyMerchant authentication key on Carat Portal. The production and certification keys will be different.< 80 ANYES
Content-TypeIt must be sent with the value application/json.= 15 ANYES

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:

ParameterDescriptionFormatMandatory
authorizer_idCode of the authorizer on Carat Portal. Learn more.< 3 NYES
merchant_usnUnique sequential number for each order, created by the merchant.< 12 NNO
customer_idIdentification 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 ANYES
card
numberCustomer’s card number (PAN). It should not be entered with the wallet identifier.< 19 NYES
expiry_dateCard expiry date in MMYY format. Its requirement depends on the selected acquirer. In most cases, this field is mandatory.= 4 NCOND.
wallet_transaction_idIdentifier generated by the digital wallet. It should not be entered with the card number.< 2048 ANCOND.

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:

ParameterDescriptionFormat
codeCarat Portal response code. Any code different from 0(zero) means failure. Learn more.< 4 N
messageCarat Portal response message.< 500 AN
store
statusStatus of the storage transaction on Carat Portal. Learn more.= 3 AN
nsuaUnique sequential number of the storage transaction on Carat Portal.= 15 AN
merchant_usnUnique sequential number generated by the merchant.< 12 N
customer_idCustomer identification for card storage.< 20 AN
authorizer_idCode of the authorizer used on this storage transaction.< 3 N
card
tokenIdentification of the stored card. This token must be used instead of the customer’s card for performing transactions on Carat Portal.= 88 AN
suffixLast 4 digits of the customer’s card number.= 4 AN
binFirst 6 digits of the customer’s card.= 6 AN