---
updatedAt: 2026-07-10T11:54:57.000Z
agentTools:
projectIndex: https://developer.integrated.finance/llms.txt
---
# Card Lifecycle
## Overview
To request a card, follow these steps:
1. Obtain the card product ID from a company offering issuer processing services. Currently, only the card product from [Thredd](https://www.thredd.com/) is supported on the IF platform.
2. Create an active client.
3. Create the user who will serve as the cardholder.
### Card Types
On the IF platform, you have the option to create two distinct types of cards:
* Virtual Cards: These cards are in an active status upon creation.
* Physical Cards: These cards start in an inactive status when initially created.
### Card Statuses
* **Pending:** Initial state, the card is not issued yet
* **Declined:** The service provider has declined the creation of the card with the provided parameters
* **Inactive:** This status is applicable only to physical cards. Card issuing is completed, and the masked PAN and expiration date are available. The card remains inactive for transactions until the card is activated by the cardholder.
* **Active:** The card is enabled for transactions. Virtual cards are automatically activated upon completion of the issuing process.
* **Suspended:** The card is disabled for transactions temporarily. This status should be used when an IF customer the cardholder decides to suspend a card. Suspended cards must have a reason of suspension specified:
* **User Requested** reason means the cardholder asked for a temporary inactivation of the card.
* **Suspected Fraud** reason means IF customer suspended the card temporarily.
* **Suspended by Third Party** reason means IF received a message from underlying service provider stating that card is suspended for any reason. Details of this can be checked using "Service Provider Information" tab of the card in IF Backoffice.
* **Terminated:** The card is disabled for transactions permanently and cannot be reverted back to an active status. Terminated cards must have a reason of termination specified:
* **Lost Card** reason means the cardholder asked for a termination because the card is lost.
* **Stolen Card** reason means the cardholder asked for a termination because the card is stolen.
* **Expired Card** reason means the card is terminated because it's expired.
* **Termination Requested** reason means the cardholder asked for a permanent termination of the card.
* **Terminated by Third Party** reason means IF received a message from underlying service provider stating that card is terminated for any reason. Details of this can be checked using "Service Provider Information" tab of the card in IF Backoffice.
### Linked Accounts
To facilitate transactions with the card, it needs to be linked to specific account(s), which must be set up by the customer. These accounts will serve as the card balance. Customers can choose to link at least one or more account IDs to the card in the [Create a Card](#create-a-card) API request. Currently, a single card can only be linked to a single account. This limitation will be removed in the future.
The [Add Linked Account to a Card](#add-linked-account-to-a-card) API can be utilised to link new accounts to the card. If you wish to remove the linked accounts of the card, you can use the [Remove Linked Account of a Card](#remove-linked-account-of-a-card) API.
Cards can be linked to both the main account and sub-accounts based on the customer's needs.
## Create a Card
***POST /cards***
```json Create Virtual Card - Request
{
"workflow": {
"code": "client.debit.issuing"
},
"data": {
"card": {
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"alias": "Platinium Plus Card",
"attributes": {
"threddCardProduct": "00000",
"threddImageId": "An image id"
},
"linkedAccounts": [
"00000000-0000-0000-0000-000000000000"
]
}
},
"connect": {
"type": "explicit",
"serviceProvider": "thredd"
},
"metadata": {}
}
```
```json Create Virtual Card - Response
{
"workflow": {
"code": "client.debit.issuing"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "pending",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Platinium Plus Card",
"bin": null,
"pan": null,
"expirationDate": null,
"attributes": {
"threddCardProduct": "00000",
"threddImageId": "An image id"
},
"linkedAccounts": [
{
"accountId": "00000000-0000-0000-0000-000000000000",
"accountStatus": "active"
}
],
"connection": {
"id": null,
"serviceProvider": "thredd",
"reference": null,
"state": "creation-in-progress",
"status": null,
"method": "built-in",
"error": null
}
}
},
"connect": {
"type": "explicit",
"serviceProvider": "thredd"
},
"metadata": {}
}
```
```json Create Physical Card - Request
{
"workflow": {
"code": "client.debit.issuing"
},
"data": {
"card": {
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "physical",
"alias": "Platinium Plus Card",
"deliveryAddress": {
"country": "GB",
"region": "England",
"city": "London",
"street": "Baker Street",
"houseNumber": "221B",
"postalCode": "XYZ ABC",
"refinement": ""
},
"attributes": {
"threddCardProduct": "00000",
"threddCardManufacturer": "AB Note",
"threddDeliveryMethod": "0",
"threddCarrierType": "Type 1",
"threddImageId": "An image id",
"threddDesignId": "DSGN-DEFAULT"
},
"linkedAccounts": [
"00000000-0000-0000-0000-000000000000"
]
}
},
"connect": {
"type": "explicit",
"serviceProvider": "thredd"
},
"metadata": {}
}
```
```json Create Physical Card - Response
{
"workflow": {
"code": "client.debit.issuing"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "physical",
"status": "pending",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Platinium Plus Card",
"bin": null,
"pan": null,
"expirationDate": null,
"deliveryAddress": {
"country": "GB",
"region": "England",
"city": "London",
"street": "Baker Street",
"houseNumber": "221B",
"postalCode": "XYZ ABC",
"refinement": ""
},
"attributes": {
"threddCardProduct": "00000",
"threddCardManufacturer": "AB Note",
"threddDeliveryMethod": "0",
"threddCarrierType": "Type 1",
"threddImageId": "An image id",
"threddDesignId": "DSGN-DEFAULT"
},
"linkedAccounts": [
{
"accountId": "00000000-0000-0000-0000-000000000000",
"accountStatus": "active"
}
],
"connection": {
"id": null,
"serviceProvider": "thredd",
"reference": null,
"state": "creation-in-progress",
"status": null,
"method": "built-in",
"error": null
}
}
},
"connect": {
"type": "explicit",
"serviceProvider": "thredd"
},
"metadata": {}
}
```
```json A Response with Error
{
"workflow": {
"code": "client.debit.issuing"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "physical",
"status": "pending",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": null,
"pan": null,
"expirationDate": null,
"deliveryAddress": {
"country": "GB",
"region": "England",
"city": "London",
"street": "Baker Street",
"houseNumber": "221B",
"postalCode": "XYZ ABC",
"refinement": ""
},
"attributes": {
"threddCardProduct": "00000",
"threddCardManufacturer": "AB Note",
"threddDeliveryMethod": "0",
"threddCarrierType": "Type 1",
"threddImageId": "An image id"
},
"linkedAccounts": [
{
"accountId": "00000000-0000-0000-0000-000000000000",
"accountStatus": "active"
}
],
"connection": {
"id": null,
"serviceProvider": "thredd",
"reference": null,
"state": "creation-failed",
"status": null,
"method": "built-in",
"error": {
"category": "technical",
"origin": "platform",
"code": "invalid_value_detected",
"message": "An error occured",
"attributes": {}
}
}
},
"connect": {
"type": "implicit",
"serviceProvider": "thredd"
},
"metadata": {}
}
}
```
1. *workflow*:
* *code*: It can be `client.debit.issuing`. This indicates that a new card will be issued at a specific service provider of your choice. In this workflow, service provider information must also be provided in `connect` section.
2. *data*:
* *card*:
* *clientId*: The ID of the active client that will create the card.
* *userId*: The ID of the user who will be the cardholder.
* *type*: The type of the card. It must be `virtual` or `physical`
* *alias*: The alias of the card.
* *deliveryAddress*: The address to which physical cards will be delivered. For virtual cards, it must remain empty. If left blank on physical cards, the user's residential address is used as the delivery address.
* *attributes*: A key value map that can be used for storing any additional metadata that you'd like to link to card. There are some reserved keys for each service provider.
* *thredd*'s reserved attributes:
* *threddCardProduct*: The unique ID of the card product linked to the card.
* *threddDesignId*: This can also be used for the tokenised card image for virtual and physical cards depending on your card configuration. For example, physical card design blue could be ID PBLUE01.
* *threddImageId*: A reference that identifies the image file of the card manufacturer to be printed on the face of the card.
* *threddLogoFrontId*: A reference that identifies the logo file of the card manufacturer to be printed on the face of the card, if applicable
* *threddLogoBackId*: A reference that identifies the logo file of the card manufacturer to be printed on the back of the card, if applicable
* *threddCardManufacturer*: The manufacturer to whom the card generation request should be sent, for example: TCT, AllPay, GNC, Gemalto, Nitecrest and Exceet.
* *threddDeliveryMethod*: The card's delivery method can be one of the following: Standard delivery, Registered mail, Direct delivery, Customised delivery
* *threddCarrierType*: The carrier product design reference as used by the card manufacturer. This is the letter onto which the card is attached when sent to the cardholder. Identifies the carrier product type of the card manufacturer.
* *threddLimitsGroup*: Velocity limit group which restricts the frequency and/or amount at which the card can be loaded or unloaded
* *threddUsageGroup*: Controls where a card can be used; for example, POS or ATM.
* *threddRecurringFeeGroup*: Controls whether a card is charged a recurring fee, such as a monthly platform fee.
* *threddWebServiceFeeGroup*: Controls the fees charged for Web service usage. Different web services can have different fees associated with them.
* *threddAuthFeeGroup*: Controls the card transaction authorisation fees.
* *threddMccGroup*: Merchant Category Code (MCC) Group. The MCC is a four-digit number used by the Card Schemes to define the trading category of the merchant.
* *threddCardLinkageGroup*: The Linkage Group set up in Smart Client controls various parameters related to linked cards. For details, check with your Implementation Manager.
* *threddCalendarGroup*: Controls when authorisations on a card are allowed. You can use this option to control when the card can be used. For example, to prevent usage on weekends or out of hours.
* *threddFxGroup*: Controls the rates for FX currency conversions if the purchase currency is different from the card's currency.
* *threddPaymentTokenUsageGroup*: Defines configuration options specific to the provisioning of a digital payment token. For details, see the Tokenisation Guide.
* *threddCardAcceptorAllowList*: Enables you to associate a card with the Card Acceptor (MerchantID) Allow list.
* *threddCardAcceptorDisallowList*: Enables you to associate a card with the Card Acceptor (MerchantID) Disallow list.
* *threddLimitedNetworkGroup*: A limited network group can restrict card acceptance to a limited network only. For example, a gift card may be limited to merchants in a particular shopping centre only. The rule for restricting card acceptance to a limited network is based on a merchant ID, as well as the address and postcode of where the card can be accepted.
* *threddFreetextOne*: Fulfilment additional text field
* *threddFreetextTwo*: Fulfilment additional text field
* *threddExpiryDate*: Expiry Date. It will be embossed on the card. Format YYYY-MM.
* *threddThermalLineOne*: Free text field which can be used for transferring extra information to be printed on the card.
* *threddThermalLineTwo*: Free text field which can be used for transferring extra information to be printed on the card.
* *linkedAccounts*: The list of accounts IDs to be linked to the card. The maximum list size is 10.
3. *connect*:
* *type*: The type of how connected service provider is decided. Currently, `explicit` is the only type supported.
* *serviceProvider*: The name of the service provider creating the card
## Update a Card
***PATCH /cards/{cardId}***
Updatable attributes of a Card:
* *alias*
* *status* can be updated based on the state diagram at the top of this page.
* *suspensionReason* must be provided when new status is *suspended*. Possible values are “user-requested", “suspected-fraud" and “suspended-by-third-party“.
* *terminationReason* must be provided when new status is *terminated*.
```json Status Inactivation - Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"status":"inactive"
}
},
"connect": {},
"metadata": {}
}
```
```json Status Inactivation - Response
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "inactive",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "inactive",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```Text Status Activation - Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"status":"active"
}
},
"connect": {},
"metadata": {}
}
```
```Text Status Activation - Response
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "physical",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Alias Update - Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"alias": "Gold Card"
}
},
"connect": {},
"metadata": {}
}
```
```json Alias Update - Response
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "terminated",
"suspensionReason": null,
"terminationReason": "terminated-by-third-party",
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "terminated-by-third-party",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Status Suspension - Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"status":"suspended",
"suspensionReason":"user-requested"
}
},
"connect": {},
"metadata": {}
}
```
```json Status Suspension - Response
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "suspended",
"suspensionReason": "user-requested",
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Platinium Plus Debit Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "user-requested",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Status Termination - Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"status":"terminated",
"terminationReason":"lost-card"
}
},
"connect": {},
"metadata": {}
}
```
```json Status Termination - Response
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "terminated",
"suspensionReason": null,
"terminationReason": "lost-card",
"serviceProvider": "thredd",
"alias": "Platinium Plus Debit Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "terminated-by-third-party",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json User Update - Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"userId":"00000000-0000-0000-0000-000000000000"
}
},
"connect": {},
"metadata": {}
}
```
```json User Update - Response
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Platinium Plus Debit Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "terminated-by-third-party",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
## Get a Card
***GET /cards/{cardId}***
This endpoint supports a single optional query parameter named as `metadata.include`. The possible values that can be passed in it are listed below:
| key | description |
| :----------------- | :---------------------------------------------------------- |
| connect.connection | Includes information about provider connection of the card. |
Connection can have the following states:
| state | description |
| :------------------- | :--------------------------------------------------------------- |
| pending | Pending for user connection to reach the appropriate state. |
| creation-in-progress | Card creation is in progress. |
| update-in-progress | Card update is in progress. |
| dependency-completed | User connection is in the appropriate state. |
| completed-up-to-date | Card connection has been successfully created and is up to date. |
| completed-outdated | Card connection update failed. |
| dependency-failed | User connection is not in the appropriate state. |
| creation-failed | Card creation is failed. |
```json Get Virtual Card - Response
{
"workflow": {},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
## List Cards
***GET /cards***
Supported query parameters:
| parameter | description |
| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| metadata.page.number | 0-indexed, default=0 |
| metadata.page.size | default=20, max=100 |
| data.card.clientId | ID of client |
| data.card.userId | ID of user |
| data.card.type | virtual, physical |
| data.card.alias | Alias of the card |
| data.card.status | pending, declined, active, inactive, suspended, terminated |
| data.card.serviceProvider | |
| data.card.attributes\[key] | A key from attributes map. Example usage:
If there is an *threddCardProduct* defined in attributes with value of *10023*, it can be searched using the query of *data.card.attributes\[threddCardProduct]=10023* |
```json List Cards - Response
{
"workflow": {},
"data": {
"cards": [
{
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "physical",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Physical Gold",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"deliveryAddress": {
"country": "GB",
"region": "England",
"city": "London",
"street": "Baker Street",
"houseNumber": "221B",
"postalCode": "XYZ ABC",
"refinement": ""
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "REF-01234",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
},
{
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "pending",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"serviceProvider": "thredd",
"state": "creation-failed",
"method": "built-in",
"error": {
"category": "technical",
"origin": "platform",
"code": "invalid_value_detected",
"message": "An error occured",
"attributes": {}
}
}
},
{
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
]
},
"connect": {},
"metadata": {}
}
```
## Renew a Card
***POST /cards/{cardId}/renewals***
This endpoint allows you to renew an existing card.
Clients can optionally request that the renewed card keeps the same expiry date as the original card only for physical cards.
* ***keepExpiryDate***: It enables you to renew a card (for example, if it has been damaged) with the same expiry date and details. It is valid only for physical cards.
```json Renew a virtual card - Request
{
"workflow": {
"code": "client.direct"
},
"data": {},
"connect": {},
"metadata": {}
}
```
```json Renew a virtual card - Response
{
"workflow": {},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Renew a physical card - Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"keepExpiryDate": true
}
},
"connect": {},
"metadata": {}
}
```
```json Renew a physical card - Response
{
"workflow": {},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "physical",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Silver Card",
"bin": "999999",
"pan": "999999******1234",
"expirationDate": "02/35",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
## Replace a Card
***POST /cards/{cardId}/replacements***
This endpoint allows you to replace an existing card (for example, due to loss, damage, or theft).
***keepExpiryDate***: It enables you to replace a card (for example, if it is lost, stolen or damaged) with the same expiry date. It is valid only for physical cards.
```json Replace a virtual card - Request
{
"workflow": {
"code": "client.direct"
},
"data": {},
"connect": {},
"metadata": {}
}
```
```json Replace a virtual card - Response
{
"workflow": {},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Replace a physical card - Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"keepExpiryDate": true
}
},
"connect": {},
"metadata": {}
}
```
```json Replace a physical card - Response
{
"workflow": {},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "physical",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Silver Card",
"bin": "999999",
"pan": "999999******1234",
"expirationDate": "02/35",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
## Add Linked Account to a Card
***POST /cards/{cardId}/linked-accounts***
```json Add Linked Account - Request
{
"workflow": {
"code": "direct"
},
"data": {
"linkedAccount": {
"accountId": "00000000-0000-0000-0000-000000000000"
}
},
"connect": {},
"metadata": {}
}
```
```json Add Linked Account - Response
{
"workflow": {
"code": "direct"
},
"data": {
"linkedAccount": {
"accountId": "00000000-0000-0000-0000-000000000000",
"accountStatus": "active"
}
},
"connect": {},
"metadata": {}
}
```
## Remove Linked Account of a Card
***DELETE /cards/{cardId}/linked-accounts/{linkedAccountId}***
```json Remove Linked Account - Response
{
"workflow": {},
"data": {
"linkedAccount": {
"accountId": "00000000-0000-0000-0000-000000000000",
"accountStatus": "active"
}
},
"connect": {},
"metadata": {}
}
```
## List Linked Account of a Card
***GET /cards/{cardId}/linked-accounts***
**Supported query parameters:**
| parameter | description |
| :------------------------------- | :------------------- |
| metadata.page.number | 0-indexed, default=0 |
| metadata.page.size | default=10 |
| data.linkedAccount.accountStatus | status of account |
```json List Linked Accounts - Response
{
"workflow": {},
"data": {
"linkedAccounts": [
{
"accountId": "00000000-0000-0000-0000-000000000000",
"accountStatus": "active"
},
{
"accountId": "00000000-0000-0000-0000-000000000000",
"accountStatus": "active"
},
]
},
"connect": {},
"metadata": {
"page": {
"size": 20,
"totalElements": 1,
"totalPages": 1,
"number": 0
}
}
}
```
## Reveal Card PIN
***GET /cards/{cardId}/pin***
This endpoint returns the personal identification number (PIN) of the card:
```json Reveal Card PIN - Response
{
"workflow": {},
"data": {
"card": {
"pin": "1234"
}
},
"connect": {},
"metadata": {}
}
```
## Set Card PIN
***POST /cards/{cardId}/pin***
This endpoint allows you to set the personal identification number (PIN) of the card:
```json Set Card PIN - Request
{
"workflow": {
"code": "client.direct"
},
"data": {
"card": {
"pin":"1234"
}
},
"connect": {},
"metadata": {}
}
```
```json Set Card PIN - Response
{
"workflow": {},
"data": {
"card": {
"pin": "1234"
}
},
"connect": {},
"metadata": {}
}
```
## Webhooks
Card webhooks have "cards" in the `module` field in the `webhook` container object.
There are a total of 13 different webhooks for cards, 7 of which show changes on the card and 6 of which show changes on the service provider of the card:
Card
* card-instructed
* card-activated
* card-inactivated
* card-suspended
* card-declined
* card-terminated
Card Connection
* connection-creation-instructed
* connection-created
* connection-creation-failed
* connection-update-instructed
* connection-updated
* connection-update-failed
These types are exposed in the `webhook.type` field.
```json Card Instructed Example
{
"webhook": {
"module": "cards",
"type": "card-instructed"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "pending",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": null,
"serviceProvider": "thredd",
"reference": null,
"state": "creation-in-progress",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Card Activated Example
{
"webhook": {
"module": "cards",
"type": "card-activated"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Card Inactivated Example
{
"webhook": {
"module": "cards",
"type": "card-inactivated"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "physical",
"status": "inactive",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"deliveryAddress": {
"country": "GB",
"region": "England",
"city": "London",
"street": "Baker Street",
"houseNumber": "221B",
"postalCode": "XYZ ABC",
"refinement": ""
},
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "inactive",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Card Suspended Example
{
"webhook": {
"module": "cards",
"type": "card-suspended"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "suspended",
"suspensionReason": "suspected-fraud",
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/21",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "suspected-fraud",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Card Declined Example
{
"webhook": {
"module": "cards",
"type": "card-declined"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "declined",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/26",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": null,
"serviceProvider": "thredd",
"reference": null,
"state": "creation-failed",
"method": "built-in",
"error": {
"category": "technical",
"origin": "platform",
"code": "invalid_value_detected",
"message": "An error occured",
"attributes": {}
}
}
}
},
"connect": {},
"metadata": {}
}
```
```json Card Terminated Example
{
"webhook": {
"module": "cards",
"type": "card-terminated"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "terminated",
"suspensionReason": null,
"terminationReason": "expired-card",
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/21",
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "000000000",
"serviceProvider": "thredd",
"reference": "000000000",
"state": "completed-up-to-date",
"status": "expired-card",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
The `connection` section is optional. Once the card creation process has been initiated at the service provider, the current connection information can also be displayed.
Connection can have the following states:
| state | description |
| :------------------- | :------------------------------------------------------------------------- |
| creation-in-progress | Card creation is in progress. |
| creation-failed | Card creation is failed. |
| update-in-progress | Card update is in progress. |
| completed-up-to-date | Card connection has been successfully created / updated and is up to date. |
| completed-outdated | Card connection update failed. |
```json Connection Instructed
{
"webhook": {
"module": "cards",
"type": "connection-creation-instructed"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "pending",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": null,
"pan": null,
"expirationDate": null,
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": null,
"serviceProvider": "thredd",
"reference": null,
"state": "creation-in-progress",
"status": null,
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Connection Created
{
"webhook": {
"module": "cards",
"type": "connection-created"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/21",
"attributes": {
"threddCardProduct": "00000",
"threddImageId": "An image id"
},
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"serviceProvider": "thredd",
"reference": "000000",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Connection Creation Failed
{
"webhook": {
"module": "cards",
"type": "connection-creation-failed"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "pending",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": null,
"pan": null,
"expirationDate": null,
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": null,
"serviceProvider": "thredd",
"reference": null,
"state": "creation-failed",
"status": null,
"method": "built-in",
"error": {
"category": "technical",
"origin": "platform",
"code": "invalid_value_detected",
"message": "An error occured",
"attributes": {}
}
}
}
},
"connect": {},
"metadata": {}
}
```
```json Connection Update Instructed
{
"webhook": {
"module": "cards",
"type": "connection-update-instructed"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "pending",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Gold Card",
"bin": null,
"pan": null,
"expirationDate": null,
"attributes": {
"threddCardProduct": "00000"
},
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"serviceProvider": "thredd",
"reference": "REF-01234",
"state": "update-in-progress",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Connection Updated
{
"webhook": {
"module": "cards",
"type": "connection-updated"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Silver Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/21",
"attributes": {
"threddCardProduct": "00000",
"threddImageId": "An image id"
},
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"serviceProvider": "thredd",
"reference": "REF-01234",
"state": "completed-up-to-date",
"status": "active",
"method": "built-in",
"error": null
}
}
},
"connect": {},
"metadata": {}
}
```
```json Connection Update Failed
{
"webhook": {
"module": "cards",
"type": "connection-update-failed"
},
"data": {
"card": {
"id": "00000000-0000-0000-0000-000000000000",
"clientId": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"type": "virtual",
"status": "active",
"suspensionReason": null,
"terminationReason": null,
"serviceProvider": "thredd",
"alias": "Platinium Card",
"bin": "999999",
"pan": "999999******6526",
"expirationDate": "12/21",
"attributes": {
"threddCardProduct": "00000",
"threddImageId": "An image id"
},
"connection": {
"id": "00000000-0000-0000-0000-000000000000",
"serviceProvider": "thredd",
"reference": "000000",
"state": "completed-outdated",
"status": "active",
"method": "built-in",
"error": {
"category": "technical",
"origin": "platform",
"code": "invalid_value_detected",
"message": "An error occured",
"attributes": {}
}
}
}
},
"connect": {},
"metadata": {}
}
```
## Card Tokenisation Webhooks
```json Token Activation Request Accepted
{
"webhook": {
"module": "cards",
"type": "token-activation-request-accepted"
},
"data": {
"cardToken": {
"cardId": "00000000-0000-0000-0000-000000000000",
"status": "accepted",
"paymentToken": {
"id": "1360507",
"creator": "MC-MDES",
"expiryDate": "2028-08-31",
"type": "SE",
"status": "00",
"creatorStatus": "A",
"wallet": "APPLE",
"deviceType": "M",
"languageCode": "en",
"deviceTelephoneNumber": "4567",
"deviceIpAddress": "5610AFB3",
"deviceId": "045117CD0E2190024005098121408915035E0670C15980E1",
"deviceName": "..",
"activationCode": "",
"activationExpiryDateTime": "2025-07-16 11:18:00.000",
"activationMethodData": "+447501234567",
"activationMethod": "1"
}
}
},
"connect": {},
"metadata": {}
}
```
```json Token Activation Request Declined
{
"webhook": {
"module": "cards",
"type": "token-activation-request-declined"
},
"data": {
"cardToken": {
"cardId": "00000000-0000-0000-0000-000000000000",
"status": "declined",
"statusNote": "DR: Card expiry check failed with Emboss Expiry date (DE014)",
"paymentToken": {
"id": "1360507",
"creator": "MC-MDES",
"expiryDate": "2028-08-31",
"type": "SE",
"status": "00",
"creatorStatus": "A",
"wallet": "APPLE",
"deviceType": "M",
"languageCode": "en",
"deviceTelephoneNumber": "4567",
"deviceIpAddress": "5610AFB3",
"deviceId": "045117CD0E2190024005098121408915035E0670C15980E1",
"deviceName": "..",
"activationCode": "",
"activationExpiryDateTime": "2025-07-16 11:18:00.000",
"activationMethodData": "+447501234567",
"activationMethod": "1"
}
}
},
"connect": {},
"metadata": {}
}
```
```json Token Activation Code Created
{
"webhook": {
"module": "cards",
"type": "token-activation-code-created"
},
"data": {
"cardToken": {
"cardId": "00000000-0000-0000-0000-000000000000",
"paymentToken": {
"id": "1360507",
"creator": "MC-MDES",
"expiryDate": "2028-08-31",
"type": "SE",
"status": "00",
"creatorStatus": "A",
"wallet": "APPLE",
"deviceType": "M",
"languageCode": "en",
"deviceTelephoneNumber": "4567",
"deviceIpAddress": "5610AFB3",
"deviceId": "045117CD0E2190024005098121408915035E0670C15980E1",
"deviceName": "..",
"activationCode": "123456",
"activationExpiryDateTime": "2025-07-16 11:18:00.000",
"activationMethodData": "+447501234567",
"activationMethod": "1"
}
}
},
"connect": {},
"metadata": {}
}
```
```json Token Completed Notification
{
"webhook": {
"module": "cards",
"type": "token-activation-request-completed"
},
"data": {
"cardToken": {
"cardId": "00000000-0000-0000-0000-000000000000",
"paymentToken": {
"id": "1360507",
"creator": "MC-MDES",
"expiryDate": "2028-08-31",
"type": "SE",
"status": "00",
"creatorStatus": "A",
"wallet": "APPLE",
"deviceType": "M",
"languageCode": "en",
"deviceTelephoneNumber": "4567",
"deviceIpAddress": "5610AFB3",
"deviceId": "045117CD0E2190024005098121408915035E0670C15980E1",
"deviceName": "..",
"activationCode": "123456",
"activationExpiryDateTime": "2025-07-16 11:18:00.000",
"activationMethodData": "+447501234567",
"activationMethod": "1"
}
}
},
"connect": {},
"metadata": {}
}
```