Card
Credit cards are one of the main entities for Pliant. The most important things to know about Pliant credit cards are
- the different
cardConfig
s, which determine the type of the card and how it looks, - the
limit
s on those cards and how often they renew, - the
status
of the card and - optional
cardControls
, to block or allow certain merchants for instance.
Data Model
Field | Type | Description |
---|---|---|
cardId | uuid | Unique identifier for the card |
organizationId | uuid | Unique identifier for the organization |
cardholderId | uuid | Unique identifier for the cardholder |
cardConfig | string | The card config describes the configuration and look of the card you want to issue. Per default, Pliant offers the following card configs. Please keep in mind that not all of those might be relevant or applicable for you. If in doubt, double-check with Pliant directly. - PLIANT_BLUE - PLIANT_BLACK - PLIANT_VIRTUAL - PLIANT_SINGLE_USE - PLIANT_VIRTUAL_TRAVEL (only after separate activation)- PLIANT_VIRTUAL_TRAVEL_CC_*** (only after separate activation)Also, if you have your own set of cards, the values will differ as well. See below for more details. |
status | string | The current status of the card, can be either:PENDING_ACTIVATION PENDING_ISSUANCE PENDING_REGISTRATION PENDING_VALIDITY REQUEST_APPROVED REQUESTED REQUEST_CANCELLED REQUEST_REJECTED ACTIVE LOCKED LOCKED_PIN EXPIRED TERMINATED TERMINATED_LOST TERMINATED_STOLEN |
label | string | Card label. Can be optionally assigned by a cardholder. Available only for virtual cards with type VIRTUAL. |
validityPeriod | number | For physical cards the validity is set to 36 months automatically. For single-use cards the validity is set to 12 months automatically. For virtual cards the validity can be set within a certain range when issuing a card. |
purpose | string | Available only for cards with type SINGLE_USE |
refNum | string | Last 4 digits of the card |
issuingDate | date-time | Date when the card was issued |
expiryDate | date-time | Date when the card is going to expire |
limit | object | The card limit defines the maximum total amount that can be spent with a card within the limit frequency renewal period.value (decimal)currency (string)The limit can be up to the organization's overall limit. For instance an organization with a limit of 1,000,000 EUR can have a card with a limit up to 1,000,000 EUR. It is also possible to have more than one card with the maximum limit. For example you can have two cards each with a limit of 1,000,000 EUR. The card limits are not added up on creation, only the transactions happening on the card are added up and checked against the organization's overall limit. |
limitRenewFrequency | object | MONTHLY - The card limit is renewed every calendar monthQUARTERLY - The card limit is renewed every calendar quarterANNUAL - The card limit is renewed every yearTOTAL - The card limit is never going to be renewed. After the limit is spent the card cannot be used anymore. |
spendingBalance | object | The amount that has already been spent by the cardholder using the card since the start of the limit periodvalue (decimal)currency (string) |
availableBalance | object | The available amount that can be used in payments until the end of the limit periodvalue (decimal)currency (string) |
transactionLimit | object | The transaction limit defines the maximum amount that can be spent with a card per single transaction. Please note that subsequent incremental charges to a card (common for e.g. hotel bookings) will be counted as a single transaction for this purpose. The transaction limit can be up to the card's limit. For instance a card with a limit of 1,000 EUR can have a transaction limit up to 1,000 EUR.value (decimal)currency (string) |
token | string | The internal VISA id for this card. Necessary when fetching sensitive card data for this card. |
cardDesign | string | The visual design assigned to this card. |
productRef | string | The internal configuration of this card. |
platformFee | boolean | Denotes if this is an internally used card to collect Pliant platform fees. These cards are not issued by cardholders, they are just internal representations to collect fees from customers. They are hidden in the Pliant app. |
limitPeriodEnd | date-time | Date and time when the current limit period ends. |
limitRenewDate | date | Date when the limit will be renewed. |
limitRenewFrequency | string | The limit renewal frequency defines when the card limit is being reset. There are time-based values possible e.g. MONTHLY or QUARTERLY but customers are also able to issue cars with TOTAL limit renewal frequency which means the limit is not going to be renewed at all |
cardControls | string | Custom card controls to block or allow certain merchants, dates, times etc. |
Card Configs / Types
The cardConfig
is the full configuration of a card in Pliants platform. It entails for example the VISA type of the card, whether it is physical or virtual and also how the card is displayed or printed.
Please note, that not all listed card configurations might be available to you. It depends on the setup of the organization and partnership. To get the real-time view on available card configurations, please consult the endpoint for listing all available cardConfig
s for a given organization.
Note regarding physical cards
Each member can only have one single physical card at the same time (per organization account). Before activating a second physical card, the first one has to be terminated. This means the total number of physical cards that can be issued for your organization matches its total number of members.
PLIANT_BLUE
PLIANT_BLUE
A physical VISA Platinum Business credit card, including global acceptance and high limits to facilitate any purchase.
PLIANT_BLACK
PLIANT_BLACK
A physical VISA Infinite Business credit card, including the features of the VISA Platinum Business cards plus world-class travel insurance, unlimited worldwide airport lounge access and exclusive offers from selected partners.
PLIANT_VIRTUAL
PLIANT_VIRTUAL
A virtual VISA Platinum Business credit card with global acceptance and high limits to facilitate any purchase. Similar to the physical one, just virtual and available immediately without any shipping.
PLIANT_SINGLE_USE
PLIANT_SINGLE_USE
A virtual single-use VISA Platinum Business credit card with the same feature set as the virtual card. This card can be used exactly for one purchase. Card-checks are not counted towards the limit of one purchase and also refunds are possible up to 3 months after the card issuing date.
PLIANT_VIRTUAL_TRAVEL
PLIANT_VIRTUAL_TRAVEL
A virtual VISA Platinum Business credit card for travel use cases. These cards are exempted from 3DS for a smooth automated API usage. Merchant-based card controls can be set up for these cards, just like with other cards.
Only available after separate activation and depending on the account group the organization is in! You can always check available card configurations via the endpoint.
PLIANT_VIRTUAL_TRAVEL_CC_***
PLIANT_VIRTUAL_TRAVEL_CC_***
A virtual Visa Commercial Choice Travel credit card for travel use cases. For Travel industry customers and depending on your commercial agreement, Pliant can also provide you with Visa Commercial Choice Travel cards, providing a wider range of interchange levels selectable by the customer. Please get in touch with your Pliant representative in case you require further details.
The ***
have to be replaced with the desired interchange level bps (basis points) for the card. Valid card configurations are as follows.
PLIANT_VIRTUAL_TRAVEL_CC_100
PLIANT_VIRTUAL_TRAVEL_CC_120
PLIANT_VIRTUAL_TRAVEL_CC_150
PLIANT_VIRTUAL_TRAVEL_CC_180
PLIANT_VIRTUAL_TRAVEL_CC_200
PLIANT_VIRTUAL_TRAVEL_CC
(which defaults to 200 bps)
Only available after separate activation and depending on the account group the organization is in! You can always check available card configurations via the endpoint.
Card Status
PENDING_REGISTRATION
- A virtual card was issued for a cardholder who has not completed cardholder registration yet.PENDING_ISSUANCE
- Intermediate status betweenPENDING_REGISTRATION
andPENDING_ACTIVATION
/ACTIVE
. If issuing fails, card remains in this status.PENDING_ACTIVATION
- A physical card is issued, but the cardholder has not activated it yet.REQUESTED
- The card has been requested, but is not yet approved or rejected.REQUEST_CANCELLED
- The card request was cancelled by the cardholder.REQUEST_APPROVED
- The card request has been approved by an admin.REQUEST_REJECTED
- The card request was rejected by an admin.ACTIVE
- The card is active.LOCKED
- The card is locked, this can have several reasons, e.g. due to date/time card controls.LOCKED_PIN
- The PIN for a physical card was entered incorrectly for 3 times.EXPIRED
- The card is expired.TERMINATED
- The card was terminated.TERMINATED_LOST
- The card was terminated, because it was lost.TERMINATED_STOLEN
- The card was terminated, because it was stolen.
Changing card limits and card limit frequencies
When changing the limit
or the limitRenewFrequency
of a card, you might wonder how this affects the availableBalance
of the card. Here is the calculation we do:
- when the
limit
of a card is updated, then:availableLimit
=newLimit
+balance
. Where thebalance
is the current account balance calculated as the sum of transactions within the limit renew period (between the resets, i.e.month
,quarter
,year
,total
). - when the
limitRenewFrequency
of a card is updated, then we first recalculate the balance as a sum of transactions in the new limit renew period and then use the previous formula:availableLimit
=newLimit
+balance
.
Note that the balance
here will be mostly negative. Purchases are negative and refunds are positive. And since this is a credit card, purchases will be the majority of transactions on a card.
platformFee
The platformFee
refers to a card designed to handle fee-related transactions, such as platform fees or foreign exchange (FX) fees.
Important note: if you notice platform fee cards and their corresponding card check transactions (through relevant API calls or in the Pliant dashboard), we suggest to hide them from the end customer unless actual fees have been charged.
Example Data
{
"cardId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"cardholderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "VIRTUAL",
"status": "ACTIVE",
"label": "my credit card",
"purpose": null,
"refNum": "1234",
"issuingDate": "2023-02-27T10:38:24.801Z",
"expiryDate": "2023-02-27T10:38:24.801Z",
"limit": {
"value": 10000,
"currency": "EUR"
},
"spendingBalance": {
"value": 0,
"currency": "EUR"
},
"availableBalance": {
"value": 10000,
"currency": "EUR"
},
"transactionLimit": {
"value": 5000,
"currency": "EUR"
},
"token": "123456",
"cardDesign": "PLIANT_VIRTUAL_RED",
"productRef": "PRD_REF",
"platformFee": false,
"limitPeriodEnd": "2023-02-27T10:38:24.801Z",
"limitRenewDate": "2023-02-27",
"limitRenewFrequency": "MONTHLY",
"cardConfig": "ADALOVELACE_VIRTUAL"
}
State Machine
Important remarks
Replacing an existing card
- For physical cards, you can provide a reason:
- if
LOST
,STOLEN
the current card gets automatically terminated, - if
EXPIRING_SOON
,DAMAGED
orDAMAGED
the current card gets terminated when the new one is activated. Additionally,EXPIRING_SOON
can only be used if the card expires within the next three months.
- if
- For virtual cards, you can provide
STOLEN
(for compromised card details) orOTHER
. In both cases, the replaced card gets immediately terminated. - A replacement of a card is only possible if the card is not in one of the following statuses:
PENDING_ISSUANCE
,PENDING_REGISTRATION
,REQUESTED
. Also, single-use cards cannot be replaced at all.
Updated about 1 month ago