Tokenization (Save Card)

Overview

This page will show you how to tokenize a card number. Tokenization is the process of breaking a stream of text/numbers up into words, phrases, symbols, or other meaningful elements called tokens. This token can then be used in place of a credit card number when processing a transaction. This is useful when a developer does not want to under take the security requirements of storing card data.

This command validates the card data and then returns a card reference token. The card reference token can be used in the card number field in most scenarios. Tokens only store the card number and the expiration date. Tokens can also be used across multiple merchants. They are not related to a specific merchant.

The API endpoint is as follows:

POST /api/v2/transactions

Quick Start

Request

curl -X POST https://sandbox.usaepay.com/api/v2/transactions
    -H "Content-Type: application/json"
    -H "Authorization: Basic X1Y4N1F0YjUxM0NkM3ZhYk03UkMwVGJ0SldlU284cDc6czIvYWJjZGVmZ2hpamtsbW5vcC9iNzRjMmZhOTFmYjBhMDk3NTVlMzc3ZWU4ZTIwYWE4NmQyYjkyYzNkMmYyNzcyODBkYjU5NWY2MzZiYjE5MGU2"
    -d
    '{
    "command": "cc:save",

    "creditcard": {
        "cardholder": "John Doe",
        "number": "4000100011112224",
        "expiration": "0919",
        "cvc": "123",
        "avs_street": "1234 Main",
        "avs_zip": "12345"
    }

 }

The above cURL request is an example of how to tokenize a card.

Response

{
    "type": "transaction",
    "key": "",
    "refnum": "",
    "is_duplicate": "N",
    "result_code": "A",
    "result": "Approved",
    "authcode": "",
    "creditcard": {
        "number": "4000xxxxxxxx2224"
    },
    "savedcard": {
        "type": "Visa",
        "key": "tqb9-o076-tpfk-lb8l",
        "cardnumber": "4000xxxxxxxx2224"
    }
}

The above is a sample response object sent back from the server.

Request Parameters

This is a complete overview of the request parameters that are sent. Note that each command type may only accept a subset of the parameters.

Parameter Name	Type	Description
Command	string	This specifies the type of transaction to run. cc:save validates and tokenizes a card
creditcard	object	Object which holds all credit card information

Response Variables

Variable	Type	Description
type	string	The type of sale performed. Successful tokenizations will return a value of 'transaction'.
key	string	Unique key for the transaction record. This will be empty for the cc:save command.
refnum	string	Unique key for the transaction record. This will be empty for the cc:save command.
is_duplicate	char(Y/N)	If Y, a duplicate transaction was detected. The system is showing the response from the original transaction, rather than running a duplicate.
result_code	char	Result code ('A' = Approved or 'E' = Error)
result	string	Long version of above result_code ('Approved', etc.)
authcode	integer	Authorization code. This will be empty for the cc:save command.
creditcard	object	Object which contains masked credit card information.
savedcard	object	Object which contains tokenized credit card information.

Object Definitions

creditcard

This request object holds all of the information needed to process a credit card transaction. While only some of the parameters are required by default, additional fraud modules may further put restrictions on these parameters. Parameters in bold are required.

Parameter Name	Type	Description
number	number	Credit card number or token if missing or incorrect. Error codes 11-14
expiration	string	Credit card expiration date. All numbers, and needs to be formatted as MMYY. Error codes 15-17
cardholder	string	Name of the Cardholder
cvc	integer	Card verification code on back of card. Its format should be ### or ####
avs_street	string	Street address for address verification
avs_zip	integer	Postal (Zip) code for address verification

savedcard

This response object contains the tokenized credit card information.

Parameter Name	Type	Description
type	string	The card brand of the tokenized card. Visa, MasterCard, AMEX, etc.
key	string	Unique key for the card. This is the token.
number	string	Masked credit card information.

Change Log

Date	Change
2017-11-29	Added page

Click here for the full REST API change log.