Follow

Tokenizing and Storing Accounts to Improve Security

Tokenization is the process of exchanging sensitive account information (credit card, checking account number, etc) for a token. You store this token in your system so you can re-bill or refund the account at a later time without actually storing the account number. By tokenizing sensitive data your liability is reduced and you greatly simplify PCI compliance requirements. If you choose to store account numbers and not tokenize then you are required to pass an annual PCI audit. Per PCI, you should never store card track or CVV.

There are two ways to tokenize data with our REST Api.

  1. Charge an account and store the transactionId for future billing.
  2. Exchange the account for a vaultId without charging it and use it for future billing.

Method 1: Charging an Account and Storing the Transaction ID as a Token.

Step 1: Charge the card and if approved, save the transactionId as a token.

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "action=CHARGE" \
    -d "cardNumber=4444333322221111" \
    -d "cardExpMonth=01" \
    -d "cardExpYear=2020" \
    -d "amountBase=1.00" \
    "https://api.payjunction.com/transactions"

Response

{
     "transactionId": 22953,
    "uri": "https://api.payjunction.com/transactions/22953",
    "terminalId": 1,
    "action": "CHARGE",
    "amountBase": "1.00",
    "amountTotal": "1.00",
    "status": "CAPTURE",
    "created": "2014-01-22T21:38:25Z",
    "lastModified": "2014-01-22T21:38:25Z",
    "response": {
         "approved": true,
        "code": "00",
        "message": "Approved",
        "processor": {
            "authorized": true,
            "approvalCode": "PJ20AP",
            "avs": {
                "status": "NOT_REQUESTED"
            },
            "cvv": {
                "status": "NOT_REQUESTED"
            }
        }
    },
    "settlement": {
        "settled": false
    },
    "vault": {
        "type": "CARD",
        "accountType": "VISA",
        "lastFour": "1111"
    }
}

You want to verify that the transaction approved response is true, then you want to store the transactionId for future billing of the accounts.

Method 1: Re-billing the Account by Transaction ID

If you want to re-bill the account ( REFUND or CHARGE ) at a later time you simply send the transactionId, amount and action. If only send the transactionIdthen the amount and action from the referenced transactionId will be used.

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "action=CHARGE" \
    -d "transactionId=22953" \
    -d "amountBase=2.00" \
    "https://api.payjunction.com/transactions"

Response

{
    "transactionId": 22954,
    "uri": "https://api.payjunction.com/transactions/22954",
    "terminalId": 1,
    "action": "CHARGE",
    "amountBase": "2.00",
    "amountTotal": "2.00",
    "status": "CAPTURE",
    "created": "2014-01-22T21:38:25Z",
    "lastModified": "2014-01-22T21:38:25Z",
    "response": {
         "approved": true,
        "code": "00",
        "message": "Approved",
        "processor": {
            "authorized": true,
            "approvalCode": "PJ20AP",
            "avs": {
                "status": "NOT_REQUESTED"
            },
            "cvv": {
                "status": "NOT_REQUESTED"
            }
        }
    },
    "settlement": {
        "settled": false
    },
    "vault": {
        "type": "CARD",
        "accountType": "VISA",
        "lastFour": "1111"
    }
}

There is no need to update your systems with the new tranasctionId. Just keep the initial transactionId from the first transaction. Just verify that the transaction was approved. If you need to update the token for a customer you will need to repeat the process for the new account and store the new transactionId.

 

Method 2: Exchanging an Account for a Vault ID. This Does Not Charge the Account.

Step 1: Add a customer.

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "firstName=John" \
    -d "lastName=Smith" \
    "https://api.payjunction.com/customers"

Response

{
     "customerId": 2969,
    "uri": "https://api.payjunction.com/customers/2969",
    "firstName": "John",
    "lastName": "Smith",
    "created": "2014-01-22T22:34:47Z",
    "lastModified": "2014-01-22T22:34:47Z"
}


Step 2: Add the vault to the customer.

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "cardNumber=4444333322221111" \
    -d "cardExpMonth=01" \
    -d "cardExpYear=2020" \
    "https://api.payjunction.com/customers/2969/vaults"

Response for CARD vault

{
     "vaultId": 2078,
    "uri": "https://api.payjunction.com/customers/2969/vaults/2078",
    "type": "CARD",
    "accountType": "VISA",
    "lastFour": "1111",
    "cardExpMonth": 5,
    "cardExpYear": 2020,
    "created": "2014-01-22T22:36:27Z",
    "lastModified": "2014-01-22T22:36:27Z"
}

Response for ACH vault

{
     "vaultId": 2079,
    "uri": "https://api.payjunctionlabs.com/customers/2969/vaults/2079",
    "type": "ACH",
    "accountType": "CHECKING",
    "lastFour": "6789",
    "achRoutingNumber": "121000358",
    "achType": "PPD",
    "created": "2014-01-22T22:38:05Z",
    "lastModified": "2014-01-22T22:38:05Z"
}

Now you can store the vaultId for future billing.

 

Method 2: Re-billing the Account by Vault ID.

If you want to re-bill the account ( REFUND or CHARGE ) at a later time you simply send thevaultId, amount and action. You will always need to specify the baseAmount and action when re-billing by vaultId. 

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "action=CHARGE" \
    -d "vaultId=14833" \
    -d "amountBase=2.00" \
    "https://api.payjunction.com/transactions"

Response

{
    "transactionId": 22959,
    "uri": "https://api.payjunction.com/transactions/22959",
    "terminalId": 1,
    "action": "CHARGE",
    "amountBase": "2.00",
    "amountTotal": "2.00",
    "status": "CAPTURE",
    "created": "2014-01-22T22:39:38Z",
    "lastModified": "2014-01-22T22:39:38Z",
    "response": {
         "approved": true,
        "code": "00",
        "message": "Approved",
        "processor": {
            "authorized": true,
            "approvalCode": "PJ20AP",
            "avs": {
                "status": "NOT_REQUESTED"
            },
            "cvv": {
                "status": "NOT_REQUESTED"
            }
        }
    },
    "settlement": {
        "settled": false
    },
    "vault": {
        "type": "CARD",
        "accountType": "VISA",
        "lastFour": "1111"
    },
    "billing": {
        "firstName": "John",
        "lastName": "Smith"
    }
}

The vaultId will remain the same so there is no need to update your token.

 

Method 2: Updating an Existing Vault.

There may be cases where you want to update an existing Vault. For example, updating the billing address, or updating the expiration date of the card. 

Production Request

curl -X POST -u "login:password" -H "Accept: application/json" -H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
    -d "cardExpMonth=11" \
    -d "cardExpYear=2045" \
    "https://api.payjunction.com/customers/2969/vaults/2078"

Response

{
    "vaultId": 2078,
    "uri": "https://api.payjunctionlabs.com/customers/2969/vaults/2078",
    "type": "CARD",
    "accountType": "VISA",
    "lastFour": "1111",
    "cardExpMonth": 11,
    "cardExpYear": 2045,
    "created": "2014-01-22T22:36:27Z",
    "lastModified": "2014-01-22T22:36:27Z"
}

The vaultId will remain the same.