--- updatedAt: 2025-05-20T20:12:22.000Z agentTools: projectIndex: https://dev.caxton.io/llms.txt --- # Card Management # 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](https://dash.readme.com/project/caxton/v1.0/docs/wallet-mangement). Once you have generated the `WalletId`, you can proceed with the steps below: 1. Call the [`POST - Create a Card`](https://dev.caxton.io/reference/currencycardapi_ordercard) 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** | Name | Description | Type | Required/Optional | | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----- | :---------------- | | `FirstName` | The Card Holder's First Name. | string | Required | | `LastName` | The Card Holder's Last Name. | string | Required | | `Gender` | The Card Holder's gender. Must be Male or Female. | string | Required | | `Email` | Email is not a compulsory value and if not set, the Card can be activated but does not provide the Card Holder with platform access to view balances and recent transactions. Conversely, if the email value is set, the Card Holder receives an email with Sign-up details, that enables them to create an account and gain access to the aforementioned features. | string | Optional | | `DateOfBirth` | The Card Holder's date of birth, as per [RFC3339](https://www.rfc-editor.org/rfc/rfc3339#section-5.6) date format yyyy-mm-dd. | string | Required | **RESPONSE** A successful response is shown below, note the `CardId` created on line four. ```json { "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`](https://dev.caxton.io/reference/currencycardapi_assigncard) endpoint and entering an email address in the request, sends an email to the Card Holder with the instructions 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`](https://dev.caxton.io/reference/currencycardapi_getpayauthactivationdetails) 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** | Name | Description | | :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WalletId` | The WalletId for the Wallet where the Card is being stored. | | `CardId` | The CardId for the Card being activated. | | `SequenceNumber` | **Must** be set to 0 for new Cards. Each time the Card is renewed, the number is updated sequentially. E.g., The Card is renewed for the first time, the value is set to 1. If it was renewed for the second time, the value would be set to 2, and so on. | **RESPONSE** ```json { "Content": { "Model": { "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": "John.Doe@company.io", "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`](https://dev.caxton.io/reference/currencycardapi_payauthactivatecard) 2. Enter the `CardActivationToken` created in Step 1, and the missing Card digits as required. **REQUEST** ```json { "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** ```json { "Content": { "Model": { "ApiStatusCode": 100, "ApiStatus": "IsValid", "ApiStatusDescription": "Valid Operation" }, "ExpectedResponses": [ "IsValid" ] }, "AuthorisedClientModel": { "ClientId": "", "ClientRef": "", "ApiStatusCode": 100, "ApiStatus": "IsValid", "ApiStatusDescription": "Valid Operation" }, "AuthorisedUserModel": { "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 Owner`](https://dev.caxton.io/reference/currencycardapi_activatecardless)endpoint. **REQUEST** | Name | Description | | :--------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WalletId` | The WalletId for the Wallet where the Card is being stored. | | `CardId` | The CardId for the Card being activated. | | `SequenceNumber` | **Must**be set to 0 for new Cards. Each time the Card is renewed, the number is updated sequentially. E.g., The Card is renewed for the first time, the value is set to 1. If it was renewed for the second time, the value would be set to 2, and so on. | **RESPONSE** ```json { "Content": { "Model": { "ApiStatusCode": 100, "ApiStatus": "IsValid", "ApiStatusDescription": "Valid Operation" }, "ExpectedResponses": [ "IsValid" ] }, "AuthorisedClientModel": { "ClientId": "", "ClientRef": "", "ApiStatusCode": 100, "ApiStatus": "IsValid", "ApiStatusDescription": "Valid Operation" }, "AuthorisedUserModel": { "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 PIN`](https://dev.caxton.io/reference/currencycardapi_getcardpinnew)endpoint. 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`](https://dev.caxton.io/reference/currencycardapi_blockcard). This endpoint blocks a specified Card. Once blocked, transactions are disabled and prevented from being carried out. **UNBLOCK** - [`PUT - Unblock Card`](https://dev.caxton.io/reference/currencycardapi_unblockcard). 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](https://dev.caxton.io/reference/currencycardapi_lostcard). This endpoint marks a specified Card as Lost, and assigns it the corresponding 'Lost' status. **STOLEN** [PUT - Card Stolen](https://dev.caxton.io/reference/currencycardapi_stolencard). 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`](https://dev.caxton.io/reference/currencycardapi_getallcards). 2. Enter the `WalletId`. # Move a Card To move a Card to a different Wallet: 1. [`POST - Move a Card`](https://dev.caxton.io/reference/currencycardapi_movecard) 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`](https://dev.caxton.io/reference/transactionhistoryapi_getwalletcardtransaction). 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](https://dev.caxton.io/docs/card-management#filter-card-transactions). ## 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`](https://dev.caxton.io/reference/transactionhistoryapi_getrecentwalletcardtransactionbycurrency-1). 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](https://www.iso.org/iso-4217-currency-codes.html). 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](https://dev.caxton.io/docs/card-management#filter-card-transactions). ## 3. List Recent Card Transactions To show recent transactions for a given Card: 1. Call [`POST - List Recent Card Transactions`](https://dev.caxton.io/reference/transactionhistoryapi_getrecentwalletcardtransaction). 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](https://dev.caxton.io/docs/card-management#filter-card-transactions). ## 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. | Value | Name | Description | | :---- | :---------------- | :------------------------------------------------------ | | 1 | CardGroupLoads | Deposits made to the Wallet. | | 2 | AtmWithdrawals | Withdrawals made via cash machine. | | 3 | PosTransactions | Transactions carried out using a POS (Point of Sale). | | 4 | Redemptions | Card balances that are transferred to the Main Balance. | | 5 | Reversals | Refunded and/or reversed transactions by Merchant. | | 6 | Fees | Describes any fees charged while using the Card. | | 7 | BalanceAdjustment | Caxton fees. | | 8 | SwitchBalance | Balances moved from one currency to another. |