Credit cards are one of the main entities for Pliant. The most important things to know about Pliant credit cards are

  • the different cardConfigs, which determine the type of the card and how it looks,
  • the limits 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

FieldTypeDescription
cardIduuid Unique identifier for the card
organizationIduuidUnique identifier for the organization
cardholderIduuidUnique identifier for the cardholder
cardConfigstringThe 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.
statusstringThe 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
labelstringCard label. Can be optionally assigned by a cardholder. Available only for virtual cards with type VIRTUAL.
validityPeriodnumberFor 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.
purposestringAvailable only for cards with type SINGLE_USE
refNumstringLast 4 digits of the card
issuingDatedate-timeDate when the card was issued
expiryDatedate-timeDate when the card is going to expire
limitobjectThe 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.
limitRenewFrequencyobjectMONTHLY - The card limit is renewed every calendar month
QUARTERLY - The card limit is renewed every calendar quarter
ANNUAL - The card limit is renewed every year
TOTAL - The card limit is never going to be renewed. After the limit is spent the card cannot be used anymore.
spendingBalanceobjectThe amount that has already been spent by the cardholder using the card since the start of the limit period
value (decimal)
currency (string)
availableBalanceobjectThe available amount that can be used in payments until the end of the limit period
value (decimal)
currency (string)
transactionLimitobjectThe 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)
tokenstringThe internal VISA id for this card. Necessary when fetching sensitive card data for this card.
cardDesignstringThe visual design assigned to this card.
productRefstringThe internal configuration of this card.
platformFeebooleanDenotes 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.
limitPeriodEnddate-timeDate and time when the current limit period ends.
limitRenewDatedateDate when the limit will be renewed.
limitRenewFrequencystringThe 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
cardControlsstringCustom 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 cardConfigs 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

A physical VISA Platinum Business credit card, including global acceptance and high limits to facilitate any purchase.

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

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

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

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_***

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 between PENDING_REGISTRATION and PENDING_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 the balance 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 or DAMAGED 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.
  • For virtual cards, you can provide STOLEN (for compromised card details) or OTHER. 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.