Overview

Company Cards can be created for customers and employees alike. Once ordered, Cards are delivered within 3 - 5 working days. After the Card is activated, simply load the balance in the currency of choice, and it's ready to make purchases. Alternatively, the Card may be activated by the Main Account holder without having to wait for the physical Card to arrive.

Scope

In this guide, we explore some of the key concepts required to formulate the understanding of Card products.

Create a Card

To create a Card you must first Create a Wallet. Once you have generated the WalletId, you can proceed with the steps below:

1. Call the POST - Create a Card endpoint.
2. Enter the WalletId in the path parameters.
3. Enter the corresponding details for the Card Holder, as shown in the request body parameters table below.
4. A successful response returns a CardId.

REQUEST BODY PARAMS

RESPONSE

A successful response is shown below, note the CardId created on line four.

{
    "Content": {
        "Model": {
            "CardId": "12345678",
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
        },
    }
}

Assign a Card

If the email address is not assigned when creating a Card, the Card Holder won't have platform access to view balances and recent transactions.

However, calling the POST - Assign a Card to a User endpoint and entering an email address in the request, sends an email to the Card Holder with the instructions for how to create credentials and access these features.

Activate Card

There are two available methods to activate a Card:

Method 1. Card Holder Activates the Card.

Method 2. Activate the Card via the Main Account.

1. Card Holder Activates the Card.

This option consists of a two-step process, whereby the Card Holder carries out the activation.

Step 1

1. Call the Get - Activate Card - Step One endpoint.
2. When the request is carried out successfully, a CardActivationToken is created, which expires after five minutes. A successful response, also returns the corresponding Index numbers to the digits on the Card which must be entered to activate the Card. These are fixed for 7, 8, 9, 10, 11 and 12.

REQUEST

RESPONSE

{
    "Content": {
        "Model": {
            "CardActivationToken": "<cardactivationtoken>",
            "Index5": 11,
            "Index6": 12,
            "WalletId": 123456,
            "Name": "Wallet 19",
            "Card": {
                "CardId": 12345678,
                "MaskedPan": "5173-5200-5445-3490",
                "Expiry": "2611",
                "Last4Digits": "3490",
                "CardState": "Inactive",
                "CardHolderName": "John Doe",
                "CardHolderEmail": "[email protected]",
                "CardSequenceNumber": "0",
                "IsRenewed": false,
                "CanBeRenewed": false,
                "ReissueBlocked": false,
                "ReissueFailure": false,
                "IsExpired": false,
                "DateIssued": "2023-11-22T15:24:07.3333333",
                "IsExpiring": false,
                "IsBlockedByClient": false,
                "IsContactless": true,
                "MobileNumber": "",
                "PanTypeCode": 4,
                "BasePanTypeCode": 4,
                "IsPrimaryPan": false,
                "GpsToken": "731851671",
                "CanBeAssigned": false,
                "ApiStatusCode": 100,
                "ApiStatus": "IsValid",
                "ApiStatusDescription": "Valid Operation"
            },
            "Index1": 7,
            "Index2": 8,
            "Index3": 9,
            "Index4": 10,
            "TokenDurationMinutes": 5,
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
        },
    }
}

Step 2

1. Call POST - Activate Card - Step Two
2. Enter the CardActivationToken created in Step 1, and the missing Card digits as required.

REQUEST

{
   "CardActivationToken":"<cardactivationtoken>",
   "Digit1":"0",
   "Digit2":"0",
   "Digit3":"5",
   "Digit4":"4",
   "Digit5":"4",
   "Digit6":"5",
   "Index1":"7",
   "Index2":"8",
   "Index3":"9",
   "Index4":"10",
   "Index5":"11",
   "Index6":"12"
}

RESPONSE

{
    "Content": {
        "Model": {
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
        },
        "ExpectedResponses": [
            "IsValid"
        ]
    },
    "AuthorisedClientModel": {
        "ClientId": "<clientid>",
        "ClientRef": "<clientref>",
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    },
    "AuthorisedUserModel": {
        "UserId": "<userid>",
        "AppVersion": null,
        "TokenStartDate": "2023-11-01T00:00:00",
        "TokenEndDate": "2023-12-01T00:00:00",
        "LoginTimestamp": "2023-11-21T11:07:05.7411671",
        "ApiLoginType": 0,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

2. Activate the Card via the Main Account.

Activating the Card via this method means purchases are enabled much sooner. To do this, call the POST - Activate Card by Ownerendpoint.

REQUEST

RESPONSE

{
    "Content": {
        "Model": {
            "ApiStatusCode": 100,
            "ApiStatus": "IsValid",
            "ApiStatusDescription": "Valid Operation"
        },
        "ExpectedResponses": [
            "IsValid"
        ]
    },
    "AuthorisedClientModel": {
        "ClientId": "<clientid>",
        "ClientRef": "<clientref>",
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    },
    "AuthorisedUserModel": {
        "UserId": "<userid>",
        "AppVersion": null,
        "TokenStartDate": "2023-11-01T00:00:00",
        "TokenEndDate": "2023-12-01T00:00:00",
        "LoginTimestamp": "2023-11-21T11:07:05.7411671",
        "ApiLoginType": 0,
        "ApiStatusCode": 100,
        "ApiStatus": "IsValid",
        "ApiStatusDescription": "Valid Operation"
    }
}

View PIN

When a Card is activated, this endpoint shows the corresponding PIN number for that Card. To

1. Call the GET - View PINendpoint.
2. A successful response returns a URL showing an image of the PIN number - when clicked.

Block/Unblock a Card

Cards may need to be blocked or unblocked, the following endpoints are available:

BLOCK - PUT - Block Card. This endpoint blocks a specified Card. Once blocked, transactions are disabled and prevented from being carried out.

UNBLOCK - PUT - Unblock Card. This endpoint unblocks a specified Card. Once unblocked, transactions are enabled to be carried out.

Lost or Stolen Card

In the event a Card is lost or stolen, the following endpoints are available. Cards become inactive once they are marked as lost or stolen, preventing any transactions from being carried out:

LOST PUT - Card Lost. This endpoint marks a specified Card as Lost, and assigns it the corresponding 'Lost' status.

STOLEN PUT - Card Stolen. This endpoint marks a specified Card as Stolen, and assigns it the corresponding 'Stolen' status.

List All Cards

To find all Cards within a Wallet:

1. Call GET - List Cards.
2. Enter the WalletId.

Move a Card

To move a Card to a different Wallet:

1. POST - Move a Card
2. Enter the WalletId where the Card to be moved is located.
3. Enter the CardId for the corresponding Card to move.
4. Enter the WalletId for the Wallet the Card is to be moved to.

Lookup Card Transactions

To identify Card transactions in a Pending or Settled state, call any of the endpoints listed in this section. When the value IsAuthorisation is set to true, the transaction is Pending and an AuthorizationNumber is displayed. Conversely, if the value IsTransaction is set to true, the transaction is Settled and a ValitorTransactionId is displayed.

1. Using CardId and WalletId

To search transactions for a specific Card within a Wallet:

1. Call POST - Lookup Card Transactions by CardId and WalletId.
2. Enter the WalletId.
3. Enter the CardId.
4. Enter the DateFrom and DateTo, to query a particular date range
5. The TransactionHistoryTypeFilter allows you to search for transactions that are pending using the "Transaction" filter, transactions that are settled using the "Authorisation" filter, or both using the "Both" filter.
6. The TransactionTypeFilter allows you to query a particular transaction. For more information, see Transaction Types.

2. Using CardId and Currency

A Card may have various transactions in different currencies, to search for transactions made in a specific currency:

1. Call POST - Lookup Card Transactions by CardId and Currency.
2. Enter the WalletId.
3. Enter the CardId.
4. Enter a value for the number of transactions to retrieve. i.e. to show the four most recent transactions, enter "4".
5. Enter the ccy. This is the corresponding currency code as per ISO 4217.
6. Enter the DateFrom and DateTo, to query a particular date range.
7. The TransactionHistoryTypeFilter allows you to search for transactions that are pending using the "Transaction" filter, transactions that are settled using the "Authorisation" filter, or both using the "Both" filter.
8. The TransactionTypeFilter allows you to query a particular transaction. For more information, see Transaction Types.

3. List Recent Card Transactions

To show recent transactions for a given Card:

1. Call POST - List Recent Card Transactions.
2. Enter the WalletId.
3. Enter the CardId.
4. Enter a value for the number of transactions to retrieve. i.e. to show the four most recent transactions, enter "4".
5. Enter the DateFrom and DateTo, to query a particular date range.
6. The TransactionHistoryTypeFilter allows you to search for transactions that are pending using the "Transaction" filter, transactions that are settled using the "Authorisation" filter, or both using the "Both" filter.
7. The TransactionTypeFilter allows you to query a particular transaction. For more information, see Transaction Types.

4. Receive an SMS

To keep track of purchases, an SMS can be sent out to the Card Holder. To do so, call the PUT - 3DS endpoint.

Filter Card Transactions

The following table outlines the various Transaction Types available to query any particular transactions. Each Type has an assigned value which is used to filter.