Phone Icon
  1. PayJunction API Documentation
  2. Tutorials

Storing Accounts for Future Use with Transaction IDs or Vault IDs

Storing account information for future use is the process of exchanging sensitive account information (credit card, checking account number, etc) for a Transaction ID or Vault ID. You can store a Transaction ID or Vault ID in your system so you can re-bill or refund the account at a later time without actually storing the account number. By saving a Transaction ID or Vault ID for future use, your liability is reduced and you greatly simplify PCI compliance requirements. If you choose to store account numbers instead of storing Transaction IDs or Vault IDs then you are required to pass an annual PCI audit. Per PCI, you should never store card track or CVV.

As mentioned above, there are two ways to store account information for future use 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.

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

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 tranasctionId 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 the vaultId, 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 vaultId.

 

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.

Related articles