This section provides instructions on how to load or unload card funds in your card's currency and perform balance adjustments. If GPS maintains the balance on cards on your behalf, you can manage balances using the Load / Unload card & adjust balance endpoint.

📘

Note

Loads, unloads and balance adjustments are relevant to customers using External Host Interface (EHI) mode 3, where GPS maintains the card balance and performs transaction authorisation.

GPS can support the following transaction types:

• Load - used to add a positive balance onto a card
• Unload - used to remove or partially remove a balance from a card
• BalanceAdjustment - used to adjust the balance on a card up or down

👍

API Explorer

See the Load / Unload card & adjust balance endpoint.

Loading or Unloading a Card

Step 1: Retrieve card details

Before loading a card, identify the corresponding Public Token for the card to be used.
A card's public token is returned in the response to creating a card within the publicToken object.

Step 2: Unload or load a card

After identifying the public token for the card and the amount you wish to load onto the card, you can create a transaction to move the balance on or off the card. To do this, execute a POST request to the transactions endpoint with the corresponding TransactionType.

Below are examples of a load and unload payload requests for the value of £10.00 GBP

{
    "TransactionType": "Load",
    "Amount": 10.00,
    "CurrencyCode": "GBP",
    "LoadedBy": "System",
    "Description": "Card Top up for Lunch"
}

{
    "TransactionType": "Unload",
    "Amount": 10.00,
    "CurrencyCode": "GBP",
    "LoadedBy": "System",
    "Description": "Moving of funds"
}

{
    "TransactionType": "BalanceAdjustment",
    "Amount": 5.23,
    "CurrencyCode": "GBP",
    "LoadedBy": "System",
    "Description": "Credit Adjustment"
}

A successful response will return a 200 with the card's load transaction and the updated balance in the response.

🚧

A card's status impacts the ability to load

Note that certain card status values will not allow you to load a balance onto a card. For more information on card status values, see Card Status Change.

Retrieving the Card Balance

You can use this endpoint to check the current balance on the card

Step 1: Retrieve card details

Identify the corresponding Public Token for the card to be used.
A card's public token is returned in the response to creating a card within the publicToken object.

Step 2: List card balance

After identifying the public token for the card you wish to use, you can retrieve the balance on the card using the List card balance(s) endpoint.

👍

API Explorer

See the List card balance(s) endpoint.

Balance Transfers

This section describes how to transfer a balance from one card to another card within the GPS system.

Step 1: Retrieve card details

Before loading a card, identify the corresponding Public Tokens for the card to have the balance transferred from (the source) and the card to have the balance transferred to (the recipient).

Step 2: Execute an unload transaction request from the source card

Execute an unload request for the source card with the value you wish to transfer. You may also consider adding "Balance Transfer" to the description of the unload transaction.

For an example unload request, see Loading or Unloading a Card.

Step 3: Execute a load request for the recipient card

Execute a load request for the target card with the value you wish to unload. You may also consider adding "Balance Transfer" to the description of the unload transaction.

For an example unload request, see Loading or Unloading a Card.