--- updatedAt: 2026-04-21T09:28:39.000Z agentTools: projectIndex: https://customer-api.getpliant.com/llms.txt --- # Issue Card (Instant as PCI-DSS) This endpoint offers similar card issuing functionality as [the main card issuing endpoint](./issue-card), but specifically allows for a _synchronous_ and _instant_ card issuing, **including PCI-DSS compliant sensitive card data retrieval**, which can be then found in the response as object `sensitiveCardData`. This endpoint issues cards instantly in a synchronous fashion and returns the sensitive card data like the cards PAN and CVV directly. Meaning the card is active and usable when this endpoint returns a `200 Ok` response and you can directly use the card data to do a purchase of any kind. The use case being here a fully automated card issuing flow, followed by an immediate card usage on API level. **This endpoint can only be used after a separate configuration done by Pliant and the partner using this endpoint needs to be PCI-DSS certified!** **A dedicated host URL `pci-api.getpliant.com` is used for this endpoint!** Please refer to the [documentation](/docs/api-pliant-pci-dss-certified) for more information. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "contact": { "name": "API Support", "email": "support@getpliant.com", "url": "https://www.getpliant.com" }, "title": "Pliant Customer API", "description": "Pliant Customer API", "version": "2.1.0", "license": { "name": "MIT", "url": "https://opensource.org/license/MIT" } }, "servers": [ { "url": "https://partner-api.getpliant.com/api", "description": "Pliant Production Server" }, { "url": "https://sandbox.partner-api.getpliant.com/api", "description": "Pliant Sandbox Server" }, { "url": "https://pci-api.getpliant.com", "description": "PCI Vault Production Server" }, { "url": "https://pci-sandbox.partner-api.getpliant.com", "description": "PCI Vault Sandbox Server" } ], "x-readme": { "explorer-enabled": false, "samples-languages": [ "curl", "java", "kotlin" ], "headers": [ { "key": "Pliant-API-Version", "value": "2.1.0" } ] }, "tags": [ { "name": "Card Accounts", "description": "This tag is for operations related to card accounts" }, { "name": "Cards", "description": "This tag is for operations related to cards" }, { "name": "Card Controls", "description": "This tag is for operations related to card controls" } ], "paths": { "/card-accounts/{cardAccountId}/deactivate": { "post": { "summary": "Deactivate Card Account", "description": "Deactivates a card account. The organization ownership is automatically determined from the card account. A card account with `status` `SUPERSEDED` cannot be deactivated, since it is already in a terminal state.", "tags": [ "Card Accounts" ], "operationId": "deactivate-card-account", "parameters": [ { "name": "cardAccountId", "in": "path", "required": true, "description": "The unique identifier of the card account to deactivate.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Card account successfully deactivated.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts/post/responses/201/content/application~1json/schema" } } } }, "400": { "description": "Bad Request - Cannot deactivate the default card account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "errorCode": { "type": "string", "description": "The error code" }, "exceptionId": { "type": "string", "format": "uuid", "description": "The id of the exception that was thrown" }, "message": { "type": "string", "description": "The cause of the error or further explanations on the error" } } } } } }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "404": { "$ref": "#/paths/~1cards/post/responses/404" }, "429": { "$ref": "#/paths/~1cards/get/responses/429" }, "500": { "$ref": "#/paths/~1cards/get/responses/500" } } } }, "/cards": { "get": { "summary": "List Cards", "description": "Returns a list of cards. You can use the `limit`, `page`, `sortBy` and `sortDirection` parameters to filter and sort the results.\n\n**This endpoint has changed in comparison to the previous version of the API.** The following changes were made:\n- changed the enumeration for the status field in the response body\n", "tags": [ "Cards" ], "operationId": "get-cards", "parameters": [ { "name": "organizationId", "in": "query", "description": "The ID of the organization to filter by.", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "cardAccountId", "in": "query", "description": "The ID of the card account to filter by. A card always carries the card account it is currently assigned to. Once a card has been reassigned (see the `CARD_REASSIGNED` callback), it is only returned for its new card account, not for the superseded one.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "description": "A list of statuses of cards to filter by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "PENDING", "PENDING_ACTIVATION", "PENDING_ISSUANCE", "PENDING_REGISTRATION", "REQUEST_APPROVED", "REQUESTED", "REQUEST_CANCELLED", "REQUEST_REJECTED", "ACTIVE", "LOCKED", "LOCKED_PIN", "EXPIRED", "TERMINATED", "TERMINATED_LOST", "TERMINATED_STOLEN" ] } } }, { "name": "cardholderId", "in": "query", "description": "The ID of the [cardholder](/docs/cardholder-entity) to filter by.", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "deprecated": true, "description": "**DEPRECATED**: Use `cardConfig` parameter instead. A list of types of cards to filter by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "VIRTUAL", "SINGLE_USE", "TRAVEL", "PHYSICAL", "BLACK" ] } } }, { "name": "cardConfig", "in": "query", "description": "Filter by exact card configuration (e.g., PLIANT_PHYSICAL, PLIANT_VIRTUAL_TRAVEL, PLIANT_SINGLE_USE). Can be specified multiple times for filtering by multiple configurations.", "schema": { "type": "array", "items": { "type": "string" } } }, { "name": "fromDate", "in": "query", "description": "The `from` date to filter by as zero-offset UTC time. The date boundary is inclusive. Meaning we compare with `>=`.", "schema": { "type": "string", "format": "date-time", "example": "2024-07-19T15:00:00.000000Z" } }, { "name": "toDate", "in": "query", "description": "The `to` date to filter by as zero-offset UTC time. The date boundary is inclusive. Meaning we compare with `<=`.", "schema": { "type": "string", "format": "date-time", "example": "2024-07-19T15:00:00.000000Z" } }, { "name": "byDateField", "in": "query", "description": "The date field to filter by if `fromDate` and `toDate` are present.", "schema": { "type": "string", "nullable": true, "enum": [ "createdAt", "updatedAt" ], "default": "createdAt" } }, { "name": "limit", "in": "query", "description": "The maximum number of items to return per page. The default value if not provided is 100, the maximum allowed value is 1000.", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "description": "The page number to return, starting with 0, this counts up to the total number of pages. The total number of pages is determined by the total number of records divided by the limit.", "schema": { "type": "integer" } }, { "name": "sortBy", "in": "query", "description": "The field to sort by.", "schema": { "type": "string", "enum": [ "organizationId", "status", "cardholderId", "updatedAt" ] } }, { "name": "sortDirection", "in": "query", "description": "The direction to sort by.", "schema": { "type": "string", "enum": [ "ASC", "DESC" ] } } ], "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "cardId": { "type": "string", "format": "uuid", "description": "The unique identifier of the card." }, "organizationId": { "type": "string", "format": "uuid", "description": "The unique identifier of the organization." }, "cardAccountId": { "type": "string", "format": "uuid", "description": "The unique identifier of the card account." }, "cardholderId": { "type": "string", "format": "uuid", "description": "The unique identifier of the cardholder." }, "type": { "type": "string", "deprecated": true, "nullable": true, "description": "Deprecated, please use `cardConfig` instead.\n`VIRTUAL` - Virtual credit card\n`SINGLE_USE` - One-time virtual credit card (only one authorization allowed per card)\n`PHYSICAL` - Physical credit card\n`BLACK` - Physical black premium credit card\n`TRAVEL` - Virtual cards used specifically in travel industry related use cases\n", "enum": [ "VIRTUAL", "SINGLE_USE", "PHYSICAL", "BLACK", "TRAVEL" ] }, "cardConfig": { "type": "string", "description": "The Pliant card configuration of this card. This describes all feature of this card in one single configuration, e.g. the type of the card and also the design of the card etc. It replaces the deprecated card `type`. Please refer to the [guide section](/docs/card-entity) to learn more about possible values." }, "platformFee": { "type": "boolean", "description": "Whether the card is used for the internal Pliant platform fee or not." }, "cardDesignId": { "type": "string", "format": "uuid", "description": "The unique identifier of the card design used for this specific card." }, "cardDesignLogoName": { "type": "string", "nullable": true, "description": "The name of the card design used for this specific card." }, "createdAt": { "type": "string", "format": "date-time", "description": "The date-time when card was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The date-time when card was updated." } } } }, "hasNextPage": { "type": "boolean", "description": "Indicates whether there is a next page available." } } } } } }, "400": { "description": "Bad Request. The API consumer sent a malformed request which could not be processed.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } }, "401": { "description": "Unauthorized. The API consumer is not authorized to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } }, "403": { "description": "Forbidden. The API consumer is not allowed to access the requested resource.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } }, "429": { "description": "Too Many Requests. The API consumer has sent too many requests in a given amount of time. Please check our [API guidelines](/docs/pliant-api-guidelines#api-rate-limits).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Detailed description of the error and breached rate limit." } } } } } }, "500": { "description": "Internal Server Error. The request was not completed due to an internal error.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } } } }, "post": { "summary": "Issue Card with Cardholder", "description": "Issue a new credit card for an existing or a new cardholder. A detailed explanation of different types and statuses can be found in our [guides](/docs/card-entity) section. Hint: you can also [replace](./replace-card) an existing card instead.\nIf the cardholder is in the invited state at the time of issuing the card, we will park the card issuing request and automatically issue the card once the cardholder is active.\nPlease be aware that card issuing is (as many other processes in Pliant's API) an [asynchronous process](/docs/core-concepts#mutating-data-happens-asynchronously). This means you need to rely on the callback for the card being active, before you can start using it.\n", "tags": [ "Cards" ], "operationId": "issue-card-with-cardholder", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "organizationId", "limit", "transactionLimit", "cardConfig" ], "properties": { "cardholderId": { "type": "string", "format": "uuid", "nullable": true, "description": "The id of the [cardholder](/docs/cardholder-entity) to issue the card for. This cardholder needs to have a phone number, otherwise 3DS security mechanism during a purchase will not work. If not provided, you must provide a `cardholder` object to create a new cardholder as part of the card issuing process." }, "organizationId": { "type": "string", "format": "uuid", "description": "The ID of the organization to issue the card for." }, "cardAccountId": { "type": "string", "format": "uuid", "description": "The ID of the [card account](/docs/card-account) to issue the card for. If not provided, the card will be issued for the default [card account](/docs/card-account) of the organization. If the given card account has `status` `SUPERSEDED`, the request is transparently resolved to its successor (`supersededBy`) and the response carries the id of that successor card account." }, "cardConfig": { "type": "string", "description": "The Pliant card configuration of this card.\nThis describes all features of this card in one single configuration, e.g. the type of the card and also the design of the card etc.\nPlease refer to the [guide section](/docs/card-entity) to learn more about possible values.\n" }, "cardDesignId": { "type": "string", "format": "uuid", "nullable": true, "description": "The unique identifier of the card design used for this card.\nThis field can only be set when creating virtual cards.\nAvailable designs for a card config can be retrieved via the [available cards endpoint](/reference/get-available-cards).\n" }, "label": { "type": "string", "description": "Mandatory only for virtual cards with a `cardConfig` containing `VIRTUAL` or `TRAVEL`, the maximum length is 40 characters.", "maxLength": 40, "nullable": true }, "purpose": { "type": "string", "description": "Mandatory only for virtual cards with `cardConfig` ending with `SINGLE_USE`", "maxLength": 200 }, "validityPeriod": { "type": "number", "description": "Number of months when card expires.\n- Mandatory for `cardConfig` containing `VIRTUAL` and `TRAVEL`\n- For `cardConfig` ending with `PHYSICAL` or `BLACK`: set to 36 months automatically\n- For `cardConfig` ending with `SINGLE_USE`: set to 12 months automatically\n- For `cardConfig` containing `INSURANCE`:\n - Physical insurance: set to 24 months automatically\n - Virtual insurance (excluding single-use): validated from enum, defaults to 36 months\n - Single-use insurance: set to 12 months automatically\nFor cards with fixed validity periods, user input is ignored.\n", "enum": [ 3, 6, 9, 12, 18, 24, 30, 36 ] }, "validFrom": { "type": "string", "format": "date", "nullable": true, "description": "Optional field to describe a fixed date range in which the card is usable for purchases, replaces the `validityPeriod` if used. Outside of this date range, the card cannot be used for any purchases, only for zero-amount card-checks, and is shown with `status` `PENDING`. If not provided, the card is active immediately. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the provided date is already a valid day to use the card. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The earliest possible date is the current date. The `validFrom` date needs to be before the `validTo` date. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all. This field can be [updated later](/reference/update-card-validity-period). This field must be `null` when issuing benefit cards." }, "validTo": { "type": "string", "format": "date", "nullable": true, "description": "Optional field to describe a fixed date range in which the card is usable for purchases, replaces the `validityPeriod` if used. After the specified date, the card is automatically terminated. If not provided, the card is active until the `validityPeriod` ends. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the card will be terminated one day after this date. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The earliest possible date is the current date. The latest possible date is the end date of the `validityPeriod`. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all. This field can be [updated later](/reference/update-card-validity-period). This field must be `null` when issuing benefit cards." }, "validTimezone": { "type": "string", "description": "Optional field to describe the timezone for the `validFrom` and `validTo` fields. This field is mandatory if `validFrom` and `validTo` fields are used. A list of valid timezones can be found in our [guide section](/docs/card-controls-1). This field can be [updated later](/reference/update-card-validity-period). This field must be `null` when issuing benefit cards.", "example": "Europe/Berlin" }, "maxTransactionCount": { "type": "number", "minimum": 1, "maximum": 999999999, "description": ":exclamation: IMPORTANT: if the `cardConfig` is `TRAVEL` and this field is not set, the **default value will be `5`**.\nOptional field to describe the maximum number of transactions within the range of `1..999999999` that can be performed with this card.\nIf not provided, the card can be used for an unlimited number of transactions until the card expires.\n" }, "limit": { "type": "object", "description": "The limit of the card. The limit renews according to the `limitRenewFrequency` or never, if `limitRenewFrequency` is set to `TOTAL`. This limit can later be adjusted via the [update limit endpoint](/reference/update-card-limit). 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. The limit must be `0` (of the card's currency) when issuing benefit cards.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro. This has to match the currency of the respective [card account](/docs/card-account)!" } } }, "limitRenewFrequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "ANNUAL", "TOTAL" ], "description": "The frequency of the card limit renewal.\n* `DAILY` - The card limit is renewed every day\n* `WEEKLY` - The card limit is renewed every week\n* `MONTHLY` - The card limit is renewed every calendar month, this is the default setting.\n* `QUARTERLY` - The card limit is renewed every calendar quarter.\n* `ANNUAL` - The card limit is renewed every year.\n* `TOTAL` - The card limit is never going to be renewed. After the limit is spent the card cannot be used anymore.\n" }, "transactionLimit": { "type": "object", "description": "The transaction limit of the card. Meaning the maximum amount of a single transaction. This is always below or equal to the `limit` of the card. This limit can later be adjusted via the [update limit endpoint](/reference/update-card-limit). 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. The transaction limit must be `0` (of the card's currency) when issuing benefit cards.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro. This has to match the currency of the respective [card account](/docs/card-account)!" } } }, "customFirstName": { "type": "string", "description": "Optional first name on `TRAVEL` cards which will be used on the card. When used, this replaces the [cardholder](/docs/cardholder-entity) first name, which normally is used on the card. The maximum length of `customFirstName` is 50 characters. If used, both fields (`customFirstName` and `customLastName`) have to be provided with at least one character each. It is important to note, that only the following characters are allowed for issuing cards: `A-Z`, `a-z`, `0-9`, `äöüÄÖÜ.-`", "nullable": true, "maxLength": 50 }, "customLastName": { "type": "string", "description": "Optional last name on `TRAVEL` cards which will be used on the card. When used, this replaces the [cardholder](/docs/cardholder-entity) last name, which normally is used on the card. The maximum length of `customLastName` is 50 characters. If used, both fields (`customFirstName` and `customLastName`) have to be provided with at least one character each. It is important to note, that only the following characters are allowed for issuing cards: `A-Z`, `a-z`, `0-9`, `äöüÄÖÜ.-`", "nullable": true, "maxLength": 50 }, "cardControls": { "type": "object", "description": "Optionally, the card controls which will be applied to this card.", "$ref": "#/paths/~1cards~1{cardId}~1card-controls/put/requestBody/content/application~1json/schema/allOf/0", "nullable": true }, "customFields": { "type": "array", "nullable": true, "description": "Optional custom fields which can be set on a card. A custom field may have a default value which will be copied to every transaction made with this card. You can identify a custom field either by its `id` or its `label`. If both are provided, the `id` will be used. You can also create new custom fields (of type `TEXT`) on-the-fly by providing a newly, unused label and the corresponding default value you want to set. So mainly two uses cases exist: 1. Use an existing custom field on the card, mostly identified via its `id`. 2. Create a new custom field (of type `TEXT`) on-the-fly via the `label` and set it on the card.", "items": { "type": "object", "required": [ "defaultValue" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The id of the custom field, to identify an existing custom field which should be set on this card. Either `id` or `label` has to be provided. If both are provided, the `id` will be used." }, "label": { "type": "string", "description": "The label of the custom field, to identify which custom field should be set on this card. Or, to create a new custom field on-the-fly, if the label is currently unused. Either `id` or `label` has to be provided. If both are provided, the `id` will be used." }, "defaultValue": { "type": "string", "description": "The default value of the custom field to set on this card. This default value will be copied to every transaction made with this card. This is not the default value of the custom field itself, but the default value of the custom field on this card! The maximum length of the default value is 64kB.", "maxLength": 65536 } } } }, "teamId": { "type": "string", "format": "uuid", "description": "The ID of the team to issue the card for.", "nullable": true }, "projectId": { "type": "string", "format": "uuid", "description": "The ID of the project to issue the card for.", "nullable": true }, "copilots": { "type": "object", "nullable": true, "description": "Optional feature for `TRAVEL` cards. This feature allows to assign cardholders or teams as copilots to the card. The copilot also has access to the card and its card details alongside with the cardholder of the card itself.", "properties": { "cardholderIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the cardholders to assign as copilot to the card.", "nullable": true }, "teamIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the teams to assign as copilot to the card.", "nullable": true } } }, "deliverTo": { "type": "string", "nullable": true, "enum": [ "ORGANIZATION", "CARDHOLDER" ], "description": "Optionally, specifies where the physical card should be delivered.\n* `ORGANIZATION` - Ship to organization address (default)\n* `CARDHOLDER` - Ship to cardholder's personal delivery address\n\nThis field is only applicable for physical cards.\nIf not provided, the card will be shipped to the organization address.\n\n\nThe request will fail if the cardholder's personal delivery address is not set and `deliverTo` is set to `CARDHOLDER`.\n" }, "cardholder": { "type": "object", "description": "Optional description of a new [cardholder](/docs/cardholder-entity) to be created alongside the card. If `cardholderId` is not provided, this field is required.", "nullable": true, "required": [ "firstName", "lastName", "email", "language" ], "properties": { "membershipType": { "type": "string", "nullable": true, "description": "Defines how the cardholder is onboarded and accesses their cards.\n`STANDARD` - Cardholders receive an invitation email to register, set up a password and MFA, and become registered members with access to the Pliant web app according to their assigned role.\n`LIMITED` - For distributing cards via access links without requiring registration. This is also intended for direct customers sharing cards with recipients outside their organization. Cardholders do not receive a registration invitation and cannot access the Pliant web app. Instead, they access their cards through access links shared with them, with access limited to card-related functionality. The `GUEST` role is assigned automatically and does not need to be provided.\n`EMBEDDED` - Reserved for partners embedding the cardholder experience in their own application. No invitation email is sent. The partner is responsible for obtaining acceptance of the terms and conditions and verifying the cardholder's phone number.\nIf not provided, `STANDARD` is applied. `LIMITED` and `EMBEDDED` always have to be requested explicitly.", "enum": [ "STANDARD", "LIMITED", "EMBEDDED" ] }, "salutation": { "type": "string", "enum": [ "MR", "MRS" ], "description": "The Salutation used for email communication." }, "email": { "type": "string", "maxLength": 50, "description": "The email address of the cardholder. This will be used for email communication. If a cardholder with this email address already exists, all the information from the existing cardholder will be used, the cardholder information sent in this request will be ignored." }, "firstName": { "type": "string", "description": "The first name of the cardholder. This will be printed on credit cards as the cardholder. It is important to note, that only the following characters are allowed for issuing cards: `A-Z`, `a-z`, `0-9`, `äöüÄÖÜ.-` The combined length of first name and last name must not exceed 24 characters. One additional character is reserved for the space inserted between them when displayed on the card (25 characters in total)." }, "lastName": { "type": "string", "description": "The last name of the cardholder. This will be printed on credit cards as the cardholder. It is important to note, that only the following characters are allowed for issuing cards: `A-Z`, `a-z`, `0-9`, `äöüÄÖÜ.-` The combined length of first name and last name must not exceed 24 characters. One additional character is reserved for the space inserted between them when displayed on the card (25 characters in total)." }, "language": { "type": "string", "enum": [ "en", "de", "es", "fi", "fr", "it", "pt", "nl", "et", "el", "lv", "lt", "sk", "sl", "pl", "hu" ], "description": "Used for setting the language in Pliant apps as well as for email communication." }, "dateOfBirth": { "type": "string", "format": "date", "nullable": true, "description": "The date-of-birth of the cardholder." }, "nationality": { "type": "string", "nullable": true, "description": "The nationality of the cardholder (ISO 3166-1 alpha-2)." }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "ACCOUNT_OWNER,", "ORG_ADMIN,", "ACCOUNTANT,", "CARDHOLDER,", "LEGAL_REP", "GUEST" ] }, "description": "Roles of the cardholder to be created. Usually, the regular cardholder uses the `CARDHOLDER` role, granting them full access to the Pliant platform. Alternatively the `GUEST` role can be provided to give the cardholder limited access to Pliant apps.\nRequired for `STANDARD` memberships. For `LIMITED` the `GUEST` role is assigned automatically and cannot be combined with any other role, so you do not need to provide this property. For `EMBEDDED` roles do not apply and `CARDHOLDER` is used when none is provided." }, "phoneNumber": { "type": "string", "maxLength": 16, "pattern": "^\\+[0-9]{8,15}$", "nullable": true, "description": "Phone number of the cardholder. If provided, must start with `+` followed by 8 to 15 numbers, e.g. `+49123456789`." }, "personalAddress": { "type": "object", "description": "The personal address of the cardholder.", "nullable": true, "properties": { "country": { "type": "string", "maxLength": 2, "description": "The country of the address in ISO 3166-1 alpha-2 notation.", "nullable": true }, "state": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "description": "The US state (e.g. `CA`, `NY`). Only applicable when `country` is `US`.", "nullable": true }, "city": { "type": "string", "maxLength": 50, "description": "The city of the address.", "nullable": true }, "postalCode": { "type": "string", "maxLength": 10, "description": "The postal code of the address. Must match the country-specific format (e.g. 5 digits for `DE`/`FR`/`ES`, 4 digits for `AT`/`BE`). Both `postalCode` and `country` must be provided together.", "nullable": true }, "streetName": { "type": "string", "maxLength": 50, "description": "The street name of the address.", "nullable": true }, "streetNumber": { "type": "string", "maxLength": 50, "description": "The street number of the address.", "nullable": true }, "additionalInformation": { "type": "string", "maxLength": 50, "nullable": true, "description": "Optional additional address information." } } }, "deliveryAddress": { "type": "object", "description": "The delivery address of the cardholder.", "nullable": true, "properties": { "country": { "type": "string", "maxLength": 2, "description": "The country of the address in ISO 3166-1 alpha-2 notation.", "nullable": true }, "state": { "type": "string", "minLength": 2, "maxLength": 2, "pattern": "^[A-Z]{2}$", "description": "The US state (e.g. `CA`, `NY`). Only applicable when `country` is `US`.", "nullable": true }, "city": { "type": "string", "maxLength": 50, "description": "The city of the address.", "nullable": true }, "postalCode": { "type": "string", "maxLength": 10, "description": "The postal code of the address. Must match the country-specific format (e.g. 5 digits for `DE`/`FR`/`ES`, 4 digits for `AT`/`BE`). Both `postalCode` and `country` must be provided together.", "nullable": true }, "streetName": { "type": "string", "maxLength": 50, "description": "The street name of the address.", "nullable": true }, "streetNumber": { "type": "string", "maxLength": 50, "description": "The street number of the address.", "nullable": true }, "additionalInformation": { "type": "string", "maxLength": 50, "nullable": true, "description": "Optional additional address information." } } } } } } } ] } } } }, "responses": { "200": { "description": "Ok. The card can be used after you received the callback for the card being active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "format": "uuid", "description": "The Pliant card id (UUIDv4) of the card." }, "type": { "type": "string", "deprecated": true, "nullable": true, "enum": [ "VIRTUAL", "SINGLE_USE", "PHYSICAL", "BLACK", "TRAVEL" ], "description": "Deprecated, please use `cardConfig` instead.\n`VIRTUAL` - Virtual credit card\n`SINGLE_USE` - One-time virtual credit card (only one authorization allowed per card)\n`PHYSICAL` - Physical credit card\n`BLACK` - Physical black premium credit card\n`TRAVEL` - Virtual cards used specifically in travel industry related use cases\nEither `type` or `cardConfig` has to be provided. Please prefer `cardConfig`.\n" }, "cardConfig": { "type": "string", "description": "The Pliant card configuration of this card. This describes all feature of this card in one single configuration, e.g. the type of the card and also the design of the card etc. It replaces the deprecated card `type`. Please refer to the [guide section](/docs/card-entity) to learn more about possible values. Either `type` or `cardConfig` has to be provided. Please prefer `cardConfig`." }, "cardDesignId": { "type": "string", "format": "uuid", "nullable": true, "description": "The unique identifier of the card design used for this card. Present only for virtual cards." }, "cardholderId": { "type": "string", "format": "uuid", "description": "The ID of the [cardholder](/docs/cardholder-entity) this card is issued for." }, "organizationId": { "type": "string", "format": "uuid", "description": "The ID of the organization this card is issued for." }, "cardAccountId": { "type": "string", "format": "uuid", "description": "The ID of the [card account](/docs/card-account) this card is issued for." }, "transactionLimit": { "type": "object", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "monthlyLimit": { "type": "object", "deprecated": true, "description": "Use `limit` instead", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "limit": { "type": "object", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "limitRenewFrequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "ANNUAL", "TOTAL" ], "description": "* `DAILY` - The card limit is renewed every day\n* `WEEKLY` - The card limit is renewed every week\n* `MONTHLY` - The card limit is renewed every calendar month\n* `QUARTERLY` - The card limit is renewed every calendar quarter\n* `ANNUAL` - The card limit is renewed every year\n* `TOTAL` - The card limit is never going to be renewed. After the limit is spent the card cannot be used anymore.\n" }, "expiryDate": { "type": "string", "format": "date-time" }, "label": { "type": "string", "description": "Available only for virtual cards with a `cardConfig` containing `VIRTUAL` or `TRAVEL`. The maximum length is 40 characters.", "maxLength": 40, "nullable": true }, "purpose": { "type": "string", "description": "Available only for cards with type `SINGLE_USE`", "nullable": true }, "customFirstName": { "type": "string", "description": "Optional first name on `TRAVEL` cards which is used on the card, instead of the regular [cardholder](/docs/cardholder-entity) name. If empty, the regular [cardholder](/docs/cardholder-entity) name is used.", "nullable": true }, "customLastName": { "type": "string", "description": "Optional last name on `TRAVEL` cards which is used on the card, instead of the regular [cardholder](/docs/cardholder-entity) name. If empty, the regular [cardholder](/docs/cardholder-entity) name is used.", "nullable": true }, "cardControls": { "type": "object", "$ref": "#/paths/~1cards~1{cardId}~1card-controls/put/requestBody/content/application~1json/schema/allOf/0", "nullable": true }, "validFrom": { "type": "string", "format": "date", "nullable": true, "description": "Optional field to describe a fixed date range in which the card is usable for purchases. Outside of this date range, the card cannot be used for any purchases, only for zero-amount card-checks, and is shown with `status` `PENDING`. If not provided, the card is active immediately. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the provided date is already a valid day to use the card. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The earliest possible date is the current date. The `validFrom` date needs to be before the `validTo` date. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all.", "example": "2023-12-01" }, "validTo": { "type": "string", "format": "date", "nullable": true, "description": "Optional field to describe a fixed date range in which the card is usable for purchases. After the specified date, the card is automatically terminated. If not provided, the card is active until the `validityPeriod` ends. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the card will be terminated one day after this date. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The latest possible date is the end date of the `validityPeriod`. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all.", "example": "2023-12-31" }, "validTimezone": { "type": "string", "description": "Optional field to describe the timezone for the `validFrom` and `validTo` fields. This field is mandatory if `validFrom` and `validTo` fields are used. A list of valid timezones can be found in our [guide section](/docs/card-controls-1)." }, "maxTransactionCount": { "type": "number", "minimum": 1, "maximum": 999999999, "description": "Optional field to describe the maximum number of transactions within the range of `1..999999999` that can be performed with this card. If not provided, the card can be used for an unlimited number of transactions until the card expires." }, "clickToPayInfo": { "type": "object", "nullable": true, "description": "Click to Pay enrollment information for this card. Only present for Visa cards that support Click to Pay.\nThis object may be `null` if Click to Pay is not supported generally (e.g., per country), but normally it will be present with a `status` of `NOT_SUPPORTED` if the card type doesn't support Click to Pay (e.g., Mastercard or Travel Purchasing Cards).\n", "properties": { "status": { "type": "string", "description": "The Click to Pay enrollment status of the card.\n* `NOT_SUPPORTED` - Card type doesn't support Click to Pay (e.g., Mastercard or Travel Purchasing Cards)\n* `NOT_ENROLLED` - Card is eligible but not enrolled in Click to Pay\n* `PENDING` - Card enrollment is awaiting the cardholder's Click to Pay member enrollment to complete\n* `ENROLLED` - Card is currently enrolled in Click to Pay\n", "enum": [ "NOT_SUPPORTED", "NOT_ENROLLED", "PENDING", "ENROLLED" ], "x-enumDescriptions": { "NOT_SUPPORTED": "Card type doesn't support Click to Pay (e.g., Mastercard or Travel Purchasing Cards).", "NOT_ENROLLED": "Card is eligible but not enrolled in Click to Pay.", "PENDING": "Card enrollment is awaiting the cardholder's Click to Pay member enrollment to complete. Once the member is enrolled, the card enrollment is triggered automatically.", "ENROLLED": "Card is currently enrolled in Click to Pay." } }, "enrolledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date-time when the card was enrolled in Click to Pay. `null` if the card has never been enrolled." }, "unenrolledAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Date-time when the card was unenrolled from Click to Pay. `null` if the card has never been unenrolled." } } }, "customFields": { "type": "array", "description": "The [custom fields](/docs/custom-fields-on-transactions) set on this card. These [custom fields](/docs/custom-fields-on-transactions) are used as default values for every transaction made with this card. If no [custom fields](/docs/custom-fields-on-transactions) are assigned to the card, we return an empty list.", "items": { "type": "object", "$ref": "#/paths/~1cards~1{cardId}~1custom-fields/patch/responses/202/content/application~1json/schema/items" } }, "copilots": { "type": "object", "nullable": true, "description": "Optional feature for `TRAVEL` cards. The copilot also has access to the card and its card details alongside with the cardholder of the card itself.", "properties": { "cardholderIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the cardholders assigned as copilots to the card." }, "teamIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the teams assigned as copilots to the card." } } }, "additionalLimits": { "type": "array", "description": "Additional limits set on the card. Empty when none were configured at creation.", "items": { "type": "object", "description": "An additional limit applied to this card.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of this additional limit. Use this `id` when updating or removing the limit via `PUT /api/cards/limits/{cardId}`." }, "limitRenewFrequency": { "type": "string", "enum": [ "PER_TRANSACTION", "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "ANNUAL", "TOTAL" ], "description": "The renewal frequency of this additional limit. `PER_TRANSACTION` is only valid for additional limits, not for the card's primary limit.\n* `PER_TRANSACTION` - Limit applies to each individual transaction.\n* `DAILY` - The limit is renewed every day.\n* `WEEKLY` - The limit is renewed every week.\n* `MONTHLY` - The limit is renewed every calendar month.\n* `QUARTERLY` - The limit is renewed every calendar quarter.\n* `ANNUAL` - The limit is renewed every year.\n* `TOTAL` - The limit is never renewed. Once spent, no further transactions are allowed under this limit.\n" }, "limit": { "type": "object", "description": "The monetary cap for this additional limit.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "maxTransactionCount": { "type": "number", "nullable": true, "minimum": 1, "maximum": 999999999, "description": "Maximum number of transactions allowed under this additional limit within its renewal period. Null if no transaction-count cap is configured." }, "scope": { "type": "object", "nullable": true, "description": "The scope restriction of this additional limit. Null when no scope is defined (`categories` and `acceptanceMethods` empty, `atmWithdrawal` false, `currency` null).", "properties": { "categories": { "type": "array", "description": "Merchant category types this limit applies to. Empty when no category restriction is set.", "items": { "type": "string", "enum": [ "ADVERTISING_AND_MARKETING", "COMPUTING_AND_SOFTWARE", "EDUCATION_AND_TRAINING", "ELECTRONICS_AND_IT_EQUIPMENT", "ENTERTAINMENT_AND_WELLNESS", "FOOD_AND_DRINKS", "GIFTS_AND_VOUCHERS", "HEALTHCARE", "MATERIALS_AND_PACKAGING", "OFFICE_SUPPLIES_AND_EQUIPMENT", "SERVICES", "TRAVEL_AND_ACCOMMODATION", "OTHER" ] } }, "acceptanceMethods": { "type": "array", "description": "The card acceptance methods this limit applies to. Empty when no acceptance-method restriction is set.", "items": { "type": "string", "enum": [ "ONLINE", "MOBILE_WALLET", "MANUAL_ENTRY", "CONTACTLESS", "CHIP_DIP", "NOT_AVAILABLE", "MAGNETIC_STRIPE", "OTHER" ] } }, "atmWithdrawal": { "type": "boolean", "description": "When `true`, this additional limit applies to ATM withdrawal transactions." }, "currency": { "type": "string", "nullable": true, "description": "ISO 4217 currency code this limit is scoped to, e.g. `PLN`. Null when no currency scope is defined." } } }, "balanceInfo": { "type": "object", "nullable": true, "description": "Spending balance information for this additional limit. Null when no balance record exists.", "properties": { "balance": { "type": "object", "description": "Amount spent under this additional limit in the current renewal period.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "availableLimit": { "type": "object", "description": "Remaining amount available under this additional limit in the current renewal period.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "limitRenewDate": { "type": "string", "format": "date", "nullable": true, "description": "Date when this additional limit's balance will next be renewed, e.g. `2026-06-01`. Null for `TOTAL` frequency limits." } } } } } } } } } } }, "400": { "$ref": "#/paths/~1cards/get/responses/400" }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "404": { "description": "Not Found. The requested resource could not be found.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } }, "422": { "description": "Unprocessable Content. The request could not be completed due to contents of the request. The syntax of the request content was correct.", "content": { "application/json": { "schema": { "$ref": "#/paths/~1card-accounts~1{cardAccountId}~1deactivate/post/responses/400/content/application~1json/schema" } } } }, "429": { "$ref": "#/paths/~1cards/get/responses/429" }, "500": { "$ref": "#/paths/~1cards/get/responses/500" } } } }, "/cards/{cardholderId}": { "post": { "summary": "Issue Card", "description": "Issue a new credit card for a specific cardholder. A detailed explanation of different types and statuses can be found in our [guides](/docs/card-entity) section. Hint: you can also [replace](./replace-card) an existing card instead.\nIf the cardholder is in the invited state at the time of issuing the card, we will park the card issuing request and automatically issue the card once the cardholder is active.\nPlease be aware that card issuing is (as many other processes in Pliant's API) an [asynchronous process](/docs/core-concepts#mutating-data-happens-asynchronously). This means you need to rely on the callback for the card being active, before you can start using it.\n\n**This endpoint has changed in comparison to the previous version of the API.** The following changes were made:\n- added `cardControls` to request and response body\n- deprecated `type` and replaced it with `cardConfig`\n", "tags": [ "Cards" ], "operationId": "issue-card", "parameters": [ { "name": "cardholderId", "in": "path", "required": true, "description": "The id of the [cardholder](/docs/cardholder-entity) to issue the card for. This cardholder needs to have a phone number, otherwise 3DS security mechanism during a purchase will not work.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "organizationId", "limit", "transactionLimit", "cardConfig" ], "properties": { "organizationId": { "type": "string", "format": "uuid", "description": "The ID of the organization to issue the card for." }, "cardAccountId": { "type": "string", "format": "uuid", "description": "The ID of the [card account](/docs/card-account) to issue the card for. If not provided, the card will be issued for the default [card account](/docs/card-account) of the organization. If the given card account has `status` `SUPERSEDED`, the request is transparently resolved to its successor (`supersededBy`) and the response carries the id of that successor card account." }, "type": { "type": "string", "nullable": true, "deprecated": true, "enum": [ "VIRTUAL", "SINGLE_USE", "PHYSICAL", "BLACK", "TRAVEL" ], "description": "Deprecated, please use `cardConfig` instead.\n`VIRTUAL` - Virtual credit card\n`SINGLE_USE` - One-time virtual credit card (only one authorization allowed per card) \n`PHYSICAL` - Physical credit card\n`BLACK` - Physical black premium credit card\n`TRAVEL` - Virtual cards used specifically in travel industry related use cases\nEither `type` or `cardConfig` has to be provided. Please prefer `cardConfig`.\n" }, "cardConfig": { "type": "string", "description": "The Pliant card configuration of this card.\nThis describes all features of this card in one single configuration, e.g. the type of the card and also the design of the card etc.\nIt replaces the deprecated card `type`. Please refer to the [guide section](/docs/card-entity) to learn more about possible values.\nEither `type` or `cardConfig` has to be provided. Please prefer `cardConfig`.\n**Required** for INSURANCE cards - the deprecated `type` field cannot be used.\n" }, "cardDesignId": { "type": "string", "format": "uuid", "nullable": true, "description": "The unique identifier of the card design used for this card.\nThis field can only be set when creating virtual cards.\nAvailable designs for a card config can be retrieved via the [available cards endpoint](/reference/get-available-cards).\n" }, "label": { "type": "string", "description": "Mandatory only for virtual cards with a `cardConfig` containing `VIRTUAL` or `TRAVEL`, the maximum length is 40 characters.", "maxLength": 40, "nullable": true }, "purpose": { "type": "string", "description": "Mandatory only for virtual cards with `cardConfig` ending with `SINGLE_USE`", "maxLength": 200 }, "validityPeriod": { "type": "number", "description": "Number of months when card expires.\n- Mandatory for `cardConfig` containing `VIRTUAL` and `TRAVEL`\n- For `cardConfig` ending with `PHYSICAL` or `BLACK`: set to 36 months automatically\n- For `cardConfig` ending with `SINGLE_USE`: set to 12 months automatically\n- For `cardConfig` containing `INSURANCE`:\n - Physical insurance: set to 24 months automatically\n - Virtual insurance (excluding single-use): validated from enum, defaults to 36 months\n - Single-use insurance: set to 12 months automatically\nFor cards with fixed validity periods, user input is ignored.\n", "enum": [ 3, 6, 9, 12, 18, 24, 30, 36 ] }, "validFrom": { "type": "string", "format": "date", "nullable": true, "description": "Optional field to describe a fixed date range in which the card is usable for purchases, replaces the `validityPeriod` if used. Outside of this date range, the card cannot be used for any purchases, only for zero-amount card-checks, and is shown with `status` `PENDING`. If not provided, the card is active immediately. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the provided date is already a valid day to use the card. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The earliest possible date is the current date. The `validFrom` date needs to be before the `validTo` date. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all. This field can be [updated later](/reference/update-card-validity-period). This field must be `null` when issuing benefit cards." }, "validTo": { "type": "string", "format": "date", "nullable": true, "description": "Optional field to describe a fixed date range in which the card is usable for purchases, replaces the `validityPeriod` if used. After the specified date, the card is automatically terminated. If not provided, the card is active until the `validityPeriod` ends. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the card will be terminated one day after this date. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The earliest possible date is the current date. The latest possible date is the end date of the `validityPeriod`. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all. This field can be [updated later](/reference/update-card-validity-period). This field must be `null` when issuing benefit cards." }, "validTimezone": { "type": "string", "description": "Optional field to describe the timezone for the `validFrom` and `validTo` fields. This field is mandatory if `validFrom` and `validTo` fields are used. A list of valid timezones can be found in our [guide section](/docs/card-controls-1). This field can be [updated later](/reference/update-card-validity-period). This field must be `null` when issuing benefit cards.", "example": "Europe/Berlin" }, "maxTransactionCount": { "type": "number", "minimum": 1, "maximum": 999999999, "description": ":exclamation: IMPORTANT: if the `cardConfig` is `TRAVEL` and this field is not set, the **default value will be `3`**.\nOptional field to describe the maximum number of transactions within the range of `1..999999999` that can be performed with this card.\nIf not provided, the card can be used for an unlimited number of transactions until the card expires.\n" }, "monthlyLimit": { "type": "object", "deprecated": true, "description": "Use `limit` instead.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro. This has to match the currency of the respective [card account](/docs/card-account)!" } } }, "limit": { "type": "object", "description": "The limit of the card. The limit renews according to the `limitRenewFrequency` or never, if `limitRenewFrequency` is set to `TOTAL`. This limit can later be adjusted via the [update limit endpoint](/reference/update-card-limit). 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. The limit must be `0` (of the card's currency) when issuing benefit cards.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro. This has to match the currency of the respective [card account](/docs/card-account)!" } } }, "limitRenewFrequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "ANNUAL", "TOTAL" ], "description": "The frequency of the card limit renewal.\n* `DAILY` - The card limit is renewed every day\n* `WEEKLY` - The card limit is renewed every week\n* `MONTHLY` - The card limit is renewed every calendar month, this is the default setting.\n* `QUARTERLY` - The card limit is renewed every calendar quarter.\n* `ANNUAL` - The card limit is renewed every year.\n* `TOTAL` - The card limit is never going to be renewed. After the limit is spent the card cannot be used anymore.\n" }, "transactionLimit": { "type": "object", "description": "The transaction limit of the card. Meaning the maximum amount of a single transaction. This is always below or equal to the `limit` of the card. This limit can later be adjusted via the [update limit endpoint](/reference/update-card-limit). 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. The transaction limit must be `0` (of the card's currency) when issuing benefit cards.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro. This has to match the currency of the respective [card account](/docs/card-account)!" } } }, "customFirstName": { "type": "string", "description": "Optional first name on `TRAVEL` cards which will be used on the card. When used, this replaces the [cardholder](/docs/cardholder-entity) first name, which normally is used on the card. The maximum length of `customFirstName` is 50 characters. If used, both fields (`customFirstName` and `customLastName`) have to be provided with at least one character each. It is important to note, that only the following characters are allowed for issuing cards: `A-Z`, `a-z`, `0-9`, `äöüÄÖÜ.-`", "nullable": true, "maxLength": 50 }, "customLastName": { "type": "string", "description": "Optional last name on `TRAVEL` cards which will be used on the card. When used, this replaces the [cardholder](/docs/cardholder-entity) last name, which normally is used on the card. The maximum length of `customLastName` is 50 characters. If used, both fields (`customFirstName` and `customLastName`) have to be provided with at least one character each. It is important to note, that only the following characters are allowed for issuing cards: `A-Z`, `a-z`, `0-9`, `äöüÄÖÜ.-`", "nullable": true, "maxLength": 50 }, "cardControls": { "type": "object", "description": "Optionally, the card controls which will be applied to this card.", "$ref": "#/paths/~1cards~1{cardId}~1card-controls/put/requestBody/content/application~1json/schema/allOf/0", "nullable": true }, "customFields": { "$ref": "#/paths/~1cards/post/requestBody/content/application~1json/schema/allOf/0/properties/customFields" }, "teamId": { "type": "string", "format": "uuid", "description": "The ID of the team to issue the card for.", "nullable": true }, "projectId": { "type": "string", "format": "uuid", "description": "The ID of the project to issue the card for.", "nullable": true }, "copilots": { "type": "object", "nullable": true, "description": "Optional feature for `TRAVEL` cards. This feature allows to assign cardholders or teams as copilots to the card. The copilot also has access to the card and its card details alongside with the cardholder of the card itself.", "properties": { "cardholderIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the cardholders to assign as copilot to the card.", "nullable": true }, "teamIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the teams to assign as copilot to the card.", "nullable": true } } }, "deliverTo": { "type": "string", "nullable": true, "enum": [ "ORGANIZATION", "CARDHOLDER" ], "description": "Optionally, specifies where the physical card should be delivered.\n* `ORGANIZATION` - Ship to organization address (default)\n* `CARDHOLDER` - Ship to cardholder's personal delivery address\n\nThis field is only applicable for physical cards.\nIf not provided, the card will be shipped to the organization address.\n\n\nThe request will fail if the cardholder's personal delivery address is not set and `deliverTo` is set to `CARDHOLDER`.\n" }, "additionalLimits": { "type": "array", "nullable": true, "description": "Optional additional limits to set on the card at creation time.", "items": { "$ref": "#/paths/~1cards~1limits~1{cardId}/put/requestBody/content/application~1json/schema/allOf/1/properties/additionalLimits/items" } } } } ] } } } }, "responses": { "200": { "description": "Ok. The card can be used after you received the callback for the card being active.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/paths/~1cards/post/responses/200/content/application~1json/schema" } } } }, "400": { "$ref": "#/paths/~1cards/get/responses/400" }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "404": { "$ref": "#/paths/~1cards/post/responses/404" }, "500": { "$ref": "#/paths/~1cards/get/responses/500" } } } }, "/cards/{cardholderId}/instant-pci": { "post": { "summary": "Issue Card (Instant as PCI-DSS)", "description": "This endpoint offers similar card issuing functionality as [the main card issuing endpoint](./issue-card), but specifically allows for a _synchronous_ and _instant_ card issuing, \n**including PCI-DSS compliant sensitive card data retrieval**, which can be then found in the response as object `sensitiveCardData`.\nThis endpoint issues cards instantly in a synchronous fashion and returns the sensitive card data like the cards PAN and CVV directly.\nMeaning the card is active and usable when this endpoint returns a `200 Ok` response and you can directly use the card data to do a purchase of any kind.\nThe use case being here a fully automated card issuing flow, followed by an immediate card usage on API level.\n\n**This endpoint can only be used after a separate configuration done by Pliant and the partner using this endpoint needs to be PCI-DSS certified!**\n\n**A dedicated host URL `pci-api.getpliant.com` is used for this endpoint!** Please refer to the [documentation](/docs/api-pliant-pci-dss-certified) for more information.\n", "tags": [ "Cards" ], "operationId": "issue-card-instant-with-pci", "parameters": [ { "name": "cardholderId", "in": "path", "required": true, "description": "The id of the [cardholder](/docs/cardholder-entity) to issue the card for. This cardholder needs to have a phone number, otherwise 3DS security mechanism during a purchase will not work.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1cards~1{cardholderId}/post/requestBody/content/application~1json/schema/allOf/0" } ] } } } }, "responses": { "200": { "description": "Ok. The card can be directly used now.", "content": { "application/json": { "schema": { "type": "object", "$ref": "#/paths/~1cards~1instant-pci/post/responses/200/content/application~1json/schema" } } } }, "400": { "$ref": "#/paths/~1cards/get/responses/400" }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "404": { "$ref": "#/paths/~1cards/post/responses/404" }, "422": { "$ref": "#/paths/~1cards/post/responses/422" }, "429": { "$ref": "#/paths/~1cards/get/responses/429" }, "500": { "$ref": "#/paths/~1cards/get/responses/500" } } } }, "/cards/instant-pci": { "post": { "summary": "Issue Card with Cardholder (Instant as PCI-DSS)", "description": "This endpoint offers similar card issuing functionality as [the main card issuing and cardholder creation endpoint](./issue-card-with-cardholder), but specifically allows for a _synchronous_ and _instant_ card issuing and cardholder creation, \n**including PCI-DSS compliant sensitive card data retrieval**, which can be then found in the response as object `sensitiveCardData`.\nThis endpoint issues cards instantly in a synchronous fashion and returns the sensitive card data like the cards PAN and CVV directly.\nMeaning the card is active and usable when this endpoint returns a `200 Ok` response and you can directly use the card data to do a purchase of any kind.\nThe use case being here a fully automated card issuing flow, followed by an immediate card usage on API level.\n\n**This endpoint can only be used after a separate configuration done by Pliant and the partner using this endpoint needs to be PCI-DSS certified!**\n\n**A dedicated host URL `pci-api.getpliant.com` is used for this endpoint!** Please refer to the [documentation](/docs/api-pliant-pci-dss-certified) for more information.\n", "tags": [ "Cards" ], "operationId": "issue-card-with-cardholder-instant-with-pci", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/paths/~1cards/post/requestBody/content/application~1json/schema/allOf/0" } ] } } } }, "responses": { "200": { "description": "Ok. The card can be directly used now.", "content": { "application/json": { "schema": { "type": "object", "properties": { "cardId": { "type": "string", "format": "uuid", "description": "The Pliant card id (UUIDv4) of the card." }, "type": { "type": "string", "deprecated": true, "nullable": true, "enum": [ "VIRTUAL", "SINGLE_USE", "PHYSICAL", "BLACK", "TRAVEL" ], "description": "Deprecated, please use `cardConfig` instead.\n`VIRTUAL` - Virtual credit card\n`SINGLE_USE` - One-time virtual credit card (only one authorization allowed per card)\n`PHYSICAL` - Physical credit card\n`BLACK` - Physical black premium credit card\n`TRAVEL` - Virtual cards used specifically in travel industry related use cases\nEither `type` or `cardConfig` has to be provided. Please prefer `cardConfig`.\n" }, "cardConfig": { "type": "string", "description": "The Pliant card configuration of this card. This describes all feature of this card in one single configuration, e.g. the type of the card and also the design of the card etc. It replaces the deprecated card `type`. Please refer to the [guide section](/docs/card-entity) to learn more about possible values. Either `type` or `cardConfig` has to be provided. Please prefer `cardConfig`." }, "cardDesignId": { "type": "string", "format": "uuid", "nullable": true, "description": "The unique identifier of the card design used for this card. Present only for virtual cards." }, "cardholderId": { "type": "string", "format": "uuid", "description": "The ID of the [cardholder](/docs/cardholder-entity) this card is issued for." }, "organizationId": { "type": "string", "format": "uuid", "description": "The ID of the organization this card is issued for." }, "cardAccountId": { "type": "string", "format": "uuid", "description": "The ID of the [card account](/docs/card-account) this card is issued for." }, "transactionLimit": { "type": "object", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "monthlyLimit": { "type": "object", "deprecated": true, "description": "Use `limit` instead", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "limit": { "type": "object", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "limitRenewFrequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "ANNUAL", "TOTAL" ], "description": "* `DAILY` - The card limit is renewed every day\n* `WEEKLY` - The card limit is renewed every week\n* `MONTHLY` - The card limit is renewed every calendar month\n* `QUARTERLY` - The card limit is renewed every calendar quarter\n* `ANNUAL` - The card limit is renewed every year\n* `TOTAL` - The card limit is never going to be renewed. After the limit is spent the card cannot be used anymore.\n" }, "expiryDate": { "type": "string", "format": "date-time" }, "label": { "type": "string", "description": "Available only for virtual cards with a `cardConfig` containing `VIRTUAL` or `TRAVEL`. The maximum length is 40 characters.", "maxLength": 40, "nullable": true }, "purpose": { "type": "string", "description": "Available only for cards with type `SINGLE_USE`", "nullable": true }, "customFirstName": { "type": "string", "description": "Optional first name on `TRAVEL` cards which is used on the card, instead of the regular [cardholder](/docs/cardholder-entity) name. If empty, the regular [cardholder](/docs/cardholder-entity) name is used.", "nullable": true }, "customLastName": { "type": "string", "description": "Optional last name on `TRAVEL` cards which is used on the card, instead of the regular [cardholder](/docs/cardholder-entity) name. If empty, the regular [cardholder](/docs/cardholder-entity) name is used.", "nullable": true }, "cardControls": { "type": "object", "$ref": "#/paths/~1cards~1{cardId}~1card-controls/put/requestBody/content/application~1json/schema/allOf/0", "nullable": true }, "validFrom": { "type": "string", "format": "date", "nullable": true, "description": "Optional field to describe a fixed date range in which the card is usable for purchases. Outside of this date range, the card cannot be used for any purchases, only for zero-amount card-checks, and is shown with `status` `PENDING`. If not provided, the card is active immediately. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the provided date is already a valid day to use the card. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The earliest possible date is the current date. The `validFrom` date needs to be before the `validTo` date. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all.", "example": "2023-12-01" }, "validTo": { "type": "string", "format": "date", "nullable": true, "description": "Optional field to describe a fixed date range in which the card is usable for purchases. After the specified date, the card is automatically terminated. If not provided, the card is active until the `validityPeriod` ends. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the card will be terminated one day after this date. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The latest possible date is the end date of the `validityPeriod`. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all.", "example": "2023-12-31" }, "validTimezone": { "type": "string", "description": "Optional field to describe the timezone for the `validFrom` and `validTo` fields. This field is mandatory if `validFrom` and `validTo` fields are used. A list of valid timezones can be found in our [guide section](/docs/card-controls-1)." }, "maxTransactionCount": { "type": "number", "minimum": 1, "maximum": 999999999, "description": "Optional field to describe the maximum number of transactions within the range of `1..999999999` that can be performed with this card. If not provided, the card can be used for an unlimited number of transactions until the card expires." }, "clickToPayInfo": { "$ref": "#/paths/~1cards/post/responses/200/content/application~1json/schema/properties/clickToPayInfo" }, "customFields": { "type": "array", "description": "The [custom fields](/docs/custom-fields-on-transactions) set on this card. These [custom fields](/docs/custom-fields-on-transactions) are used as default values for every transaction made with this card. If no [custom fields](/docs/custom-fields-on-transactions) are assigned to the card, we return an empty list.", "items": { "type": "object", "$ref": "#/paths/~1cards~1{cardId}~1custom-fields/patch/responses/202/content/application~1json/schema/items" } }, "sensitiveCardData": { "type": "object", "description": "The sensitive card data like the PAN and CVV of the card. This is only available for PCI-DSS certified companies.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The Pliant internal ID of the card." }, "pan": { "type": "string", "minLength": 16, "maxLength": 16, "description": "The PAN (Primary Account Number) of the card, also known as the credit card number." }, "cvv": { "type": "string", "minLength": 3, "maxLength": 3, "description": "The CVV (Card Verification Value) of the card, also known as the card security code." }, "expiryMonth": { "type": "integer", "description": "The expiry month of the card." }, "expiryYear": { "type": "integer", "description": "The expiry year of the card." } } }, "teamId": { "type": "string", "format": "uuid", "description": "The ID of the team the card is issued for.", "nullable": true }, "teamName": { "type": "string", "description": "Name of the team the card is issued for.", "nullable": true }, "projectId": { "type": "string", "format": "uuid", "description": "The ID of the project the card is issued for.", "nullable": true }, "projectName": { "type": "string", "description": "Name of the project the card is issued for.", "nullable": true }, "copilots": { "type": "object", "nullable": true, "description": "Optional feature for `TRAVEL` cards. The copilot also has access to the card and its card details alongside with the cardholder of the card itself.", "properties": { "cardholderIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the cardholders assigned as copilots to the card." }, "teamIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "The IDs of the teams assigned as copilots to the card." } } } } } } } }, "400": { "$ref": "#/paths/~1cards/get/responses/400" }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "404": { "$ref": "#/paths/~1cards/post/responses/404" }, "422": { "$ref": "#/paths/~1cards/post/responses/422" }, "429": { "$ref": "#/paths/~1cards/get/responses/429" }, "500": { "$ref": "#/paths/~1cards/get/responses/500" } } } }, "/cards/{cardId}/custom-fields": { "patch": { "summary": "Update/Add Custom Fields", "description": "Update the default values of [custom fields](/docs/custom-fields-on-transactions) related to a card or add new ones by `label`. All [custom fields](/docs/custom-fields-on-transactions) need to be provided, by not providing a custom field, the default value of that custom field will be removed, i.e. set to `null`. Updates of existing custom fields may happen via `id` or `label`. Adding new fields is only possible by providing a currently unused `label`. Note: the `label` needs to be unique per organization.", "tags": [ "Cards" ], "operationId": "update-custom-fields-on-card", "parameters": [ { "name": "cardId", "in": "path", "required": true, "description": "The unique identifier of the card.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customFields": { "description": "The [custom fields](/docs/custom-fields-on-transactions) to update/add on the card. All [custom fields](/docs/custom-fields-on-transactions) need to be provided, by not providing a custom field, the default value of that custom field will be removed, i.e. set to `null`. Updates of existing custom fields may happen via `id` or `label`. Adding new fields is only possible by providing a currently unused `label`. Note: the `label` needs to be unique per organization.", "$ref": "#/paths/~1cards/post/requestBody/content/application~1json/schema/allOf/0/properties/customFields" } } } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "array", "description": "The [custom fields](/docs/custom-fields-on-transactions) set on this card after the update. These [custom fields](/docs/custom-fields-on-transactions) are used as default values for every transaction made with this card. If no [custom fields](/docs/custom-fields-on-transactions) are assigned to the card, we return an empty list.", "items": { "type": "object", "required": [ "id", "label" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The id of the custom field used on this card." }, "label": { "type": "string", "description": "The label of the custom field used on this card." }, "defaultValue": { "type": "string", "nullable": true, "description": "The default value of the custom field on this card. This default value will be copied to every transaction made with this card." } } } } } } }, "400": { "$ref": "#/paths/~1cards/get/responses/400" }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "404": { "$ref": "#/paths/~1cards/post/responses/404" }, "429": { "$ref": "#/paths/~1cards/get/responses/429" }, "500": { "$ref": "#/paths/~1cards/get/responses/500" } } } }, "/cards/limits/{cardId}": { "put": { "summary": "Update Card Limit", "description": "Change the card limit for a given virtual or physical card, as long as the card is not terminated. This is unrelated to the renew frequency of the card.\nMeaning you can update the limit of a card with a `TOTAL` renew frequency (equals no limit renewal) as well as a `MONTHLY` renew frequency etc.\n\n**Additional limits:** Use the `additionalLimits` field to create, update, or remove additional limits on the card in the same request.\n- Entries **with** an `id` → update the matching existing additional limit.\n- Entries **without** an `id` → create a new additional limit.\n- Existing additional limits **omitted** from the array → soft-delete (removed).\n- Passing `null` or omitting `additionalLimits` → leave existing additional limits unchanged.\n- Passing an **empty array `[]`** → remove all additional limits from the card.\n\n**Response:** This endpoint returns `204 No Content`. To read the updated limit state use `GET /api/cards/{cardId}` or subscribe to the `CARD_LIMITS_CHANGED` callback.\n", "tags": [ "Cards" ], "operationId": "update-card-limit", "parameters": [ { "name": "cardId", "in": "path", "description": "The ID of the card to update the limit for.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "required": [ "limit", "transactionLimit" ], "properties": { "limit": { "type": "object", "description": "The limit of the card. The limit renews according to the `limitRenewFrequency` or never, if `limitRenewFrequency` is set to `TOTAL`.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar. This has to match the currency of the respective [card account](/docs/card-account)!" } } }, "limitRenewFrequency": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "ANNUAL", "TOTAL" ], "description": "The frequency of the card limit renewal.\n* `DAILY` - The card limit is renewed every day\n* `WEEKLY` - The card limit is renewed every week\n* `MONTHLY` - The card limit is renewed every calendar month, this is the default setting.\n* `QUARTERLY` - The card limit is renewed every calendar quarter.\n* `ANNUAL` - The card limit is renewed every year.\n* `TOTAL` - The card limit is never going to be renewed. After the limit is spent the card cannot be used anymore.\n" }, "transactionLimit": { "type": "object", "description": "The transaction limit of the card. Meaning the maximum amount of a single transaction. This is always below or equal to the `limit` of the card.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar. This has to match the currency of the respective [card account](/docs/card-account)!" } } }, "maxTransactionCount": { "type": "number", "minimum": 1, "maximum": 999999999, "description": "Optional field to describe the maximum number of transactions within the range of `1..999999999` that can be performed with this card.\nIf not provided, the card can be used for an unlimited number of transactions until the card expires.\n" }, "monthlyLimit": { "type": "object", "deprecated": true, "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar. This has to match the currency of the respective [card account](/docs/card-account)!" } } } } }, { "type": "object", "properties": { "additionalLimits": { "type": "array", "nullable": true, "description": "Additional limits to create, update, or remove. See endpoint description for update semantics.", "items": { "type": "object", "description": "An additional limit to set on a card.\n\n**Update semantics (applies to `PUT /api/cards/limits/{cardId}`):**\n- Entries **with** an `id` → update the matching existing additional limit.\n- Entries **without** an `id` → create a new additional limit.\n- Existing additional limits **omitted** from the array → soft-delete (removed from the card).\n- Passing `null` or omitting `additionalLimits` entirely → leave existing additional limits unchanged.\n- Passing an **empty array `[]`** → remove all additional limits from the card.\n\nThe `id` field is only meaningful for `PUT /api/cards/limits/{cardId}` and `POST /api/cards/limits/requests`. It is ignored in all other contexts.\n", "properties": { "id": { "type": "string", "format": "uuid", "nullable": true, "description": "Identifies an existing additional limit to update. Omit or set to null to create a new limit. Only meaningful for `PUT /api/cards/limits/{cardId}` and `POST /api/cards/limits/requests`." }, "limitRenewFrequency": { "type": "string", "enum": [ "PER_TRANSACTION", "DAILY", "WEEKLY", "MONTHLY", "QUARTERLY", "ANNUAL", "TOTAL" ], "description": "The renewal frequency for this additional limit. `PER_TRANSACTION` is only valid for additional limits, not for the card's primary limit.\n* `PER_TRANSACTION` - Limit applies to each individual transaction.\n* `DAILY` - The limit is renewed every day.\n* `WEEKLY` - The limit is renewed every week.\n* `MONTHLY` - The limit is renewed every calendar month.\n* `QUARTERLY` - The limit is renewed every calendar quarter.\n* `ANNUAL` - The limit is renewed every year.\n* `TOTAL` - The limit is never renewed. Once spent, no further transactions are allowed under this limit.\n" }, "limit": { "type": "object", "description": "The monetary cap for this additional limit. For unscoped limits and limits with `categories`, `acceptanceMethods`, or `atmWithdrawal` scope, the currency must match the card account currency. For currency-scoped limits (`scope.currency` is set), the currency must match `scope.currency`.", "properties": { "value": { "type": "number", "description": "The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts." }, "currency": { "type": "string", "description": "The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar." } } }, "maxTransactionCount": { "type": "number", "nullable": true, "minimum": 1, "maximum": 999999999, "description": "Max number of transactions per renewal period (`1..999999999`). Null means no cap." }, "scope": { "type": "object", "nullable": true, "description": "Restricts when this limit applies. Null for a general (unscoped) limit. At least one of `categories`, `acceptanceMethods`, `atmWithdrawal: true`, or `currency` must be set for a scoped limit.", "properties": { "categories": { "type": "array", "nullable": true, "description": "Merchant category types this limit applies to.", "items": { "type": "string", "enum": [ "ADVERTISING_AND_MARKETING", "COMPUTING_AND_SOFTWARE", "EDUCATION_AND_TRAINING", "ELECTRONICS_AND_IT_EQUIPMENT", "ENTERTAINMENT_AND_WELLNESS", "FOOD_AND_DRINKS", "GIFTS_AND_VOUCHERS", "HEALTHCARE", "MATERIALS_AND_PACKAGING", "OFFICE_SUPPLIES_AND_EQUIPMENT", "SERVICES", "TRAVEL_AND_ACCOMMODATION", "OTHER" ] } }, "acceptanceMethods": { "type": "array", "nullable": true, "description": "The card acceptance methods this limit applies to.", "items": { "type": "string", "enum": [ "ONLINE", "MOBILE_WALLET", "MANUAL_ENTRY", "CONTACTLESS", "CHIP_DIP", "NOT_AVAILABLE", "MAGNETIC_STRIPE", "OTHER" ] } }, "atmWithdrawal": { "type": "boolean", "nullable": true, "description": "When `true`, this additional limit applies to ATM withdrawal transactions." }, "currency": { "type": "string", "nullable": true, "description": "ISO 4217 currency code this limit applies to, e.g. `PLN` or `USD`. When set, the limit tracks spending in that currency only and is independent of the card's billing currency.\nConstraints:\n* Must differ from the card account's billing currency.\n* The `limit` amount currency must equal this value.\n" } } } } } } } } ] } } } }, "responses": { "204": { "description": "Ok" }, "400": { "$ref": "#/paths/~1cards/get/responses/400" }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "404": { "$ref": "#/paths/~1cards/post/responses/404" }, "429": { "$ref": "#/paths/~1cards/get/responses/429" }, "500": { "$ref": "#/paths/~1cards/get/responses/500" } } } }, "/cards/{cardId}/card-controls": { "put": { "summary": "Change Card Controls", "description": "Updates card controls for a single card. If the card control does not exist, it will be created. If the card control exists, it will be updated with the given values. Thus when updating, you have to provide all the values for the card control you want to set. Missing or not provided values are deleted if they exist.", "tags": [ "Card Controls" ], "operationId": "update-card-controls-by-card", "parameters": [ { "name": "cardId", "in": "path", "required": true, "description": "The unique identifier of the card.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "categories": { "type": "object", "nullable": true, "required": [ "type", "values", "restriction" ], "properties": { "type": { "type": "string", "enum": [ "MCC", "CATEGORY" ], "description": "Type of the category control to use. `MCC` represents the merchant category code as defined by card networks, whereas `CATEGORY` is a Pliant internal grouping of transactions done with a credit card. Both values can be found in the response from the [transaction details endpoint](./get-transactions-detail-batch) or in our [guide section](/docs/card-controls-1)." }, "values": { "type": "array", "items": { "type": "string" }, "description": "Values for this category control which should be allowed or blocked. Can be either a list of `MCCs` or Pliant's payment categories. Both values can be found in the response from the [transaction details endpoint](./get-transactions-detail-batch) or in our [guide section](/docs/card-controls-1)." }, "restriction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED" ] } } }, "merchants": { "type": "object", "nullable": true, "required": [ "type", "values", "restriction" ], "properties": { "type": { "type": "string", "enum": [ "MATCH_TERM", "MID" ], "description": "Type of the merchant control to use. `MATCH_TERM` is the merchant name to match. Matching here works by checking if the provided term is part of a merchant name, the check is case insensitive. `MID` represents the merchant identifier as assigned by the card network. It can be found in the [transaction details response](./get-transactions-detail-batch). There it is named `mid`." }, "values": { "type": "array", "items": { "type": "string" }, "description": "Values for this merchant control which should be allowed or blocked." }, "restriction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED" ] } } }, "dates": { "type": "object", "nullable": true, "required": [ "type", "values", "timezone", "restriction" ], "properties": { "type": { "type": "string", "enum": [ "YEARLY", "MONTHLY", "WEEKLY", "FIXED" ], "description": "Type of the date control to use. `YEARLY`, `MONTHLY` and `WEEKLY` are recurring dates, whereas `FIXED` is a fixed date range." }, "values": { "type": "array", "items": { "type": "string" }, "description": "Values for this date control which should be allowed or blocked.\n`YEARLY`, `MONTHLY` and `FIXED` each take exactly one value. A second value is rejected.\n`WEEKLY` takes one or more weekdays.\nPatterns:\n`YEARLY`: one range `dd.MM-dd.MM`.\n`MONTHLY`: one range `dd-dd`. Days are `01` to `28`, or `last`, `last-1` or `last-2` for the last day of the month or one to two days before.\n`WEEKLY`: one or more of `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`.\n`FIXED`: one range `dd.MM.yyyy-dd.MM.yyyy`.\nTo block transactions at the end of the month, use `MONTHLY` with the single value `20-last`.\n" }, "timezone": { "type": "string", "description": "Timezone to use for the date control. A list of valid timezones can be found in our [guide section](/docs/card-controls-1)." }, "restriction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED" ] } } }, "times": { "type": "object", "nullable": true, "required": [ "type", "values", "timezone", "restriction" ], "properties": { "type": { "type": "string", "enum": [ "TIMERANGE" ], "description": "Type of the time control. Currently only `TIMERANGE` is supported." }, "values": { "type": "array", "items": { "type": "string" }, "description": "Only one time range is allowed for this control. The allowed pattern is `HH:mm-HH:mm`.\nSo for example if you want to block all transactions between 10pm and 6am, you can use `TIMERANGE` with the value `22:00-06:00`.\n" }, "timezone": { "type": "string", "description": "Timezone to use for the time control. A list of valid timezones can be found in our [guide section](/docs/card-controls-1)." }, "restriction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED" ] } } }, "locations": { "type": "object", "nullable": true, "required": [ "type", "values", "restriction" ], "properties": { "type": { "type": "string", "enum": [ "POSTAL_CODE", "REGION" ], "description": "Type of the location-based control.\n- `POSTAL_CODE`: Then `values` are postal codes\n- `REGION`: Then `values` are region IDs of your organization\n" }, "values": { "type": "array", "items": { "type": "string" }, "description": "Values for this location control which should be allowed or blocked.\nFor `POSTAL_CODE`, each value is matched in full and case-insensitively against the merchant postal code. A shorter value is not a prefix, and `*` is not a wildcard: `68` matches only `68`, and `68*` matches only the literal `68*`.\nFor `REGION`, each value is a region ID of your organization.\nIf the transaction has no merchant postal code, this control does not decline it.\nExample: to block postal codes `12345` and `67890`, send both values with restriction `BLOCKED`.\n" }, "restriction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED" ] } } }, "countries": { "type": "object", "nullable": true, "required": [ "restriction", "values" ], "description": "Optional object defining country-based transaction restrictions.\nYou can configure cards to either allow transactions only in specified countries (whitelist)\nor block transactions in specified countries (blacklist).\nCountry codes must be valid ISO 3166-1 alpha-3 codes (e.g., `DEU`, `AUT`, `USA`).\nThis control is not available for US-issued cards.\n", "properties": { "restriction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED" ], "description": "Defines the restriction type for the country control.\n- `ALLOWED`: Only transactions in the listed countries are permitted (whitelist).\n- `BLOCKED`: Transactions in the listed countries are declined (blacklist).\n" }, "values": { "type": "array", "items": { "type": "string" }, "description": "List of ISO 3166-1 alpha-3 country codes (e.g., `DEU`, `AUT`, `USA`).\nAt least one country code must be provided.\n" } } }, "currencies": { "type": "object", "nullable": true, "required": [ "restriction", "values" ], "description": "Optional object defining currency-based transaction restrictions.\nYou can configure cards to either allow transactions only in specified currencies (whitelist)\nor block transactions in specified currencies (blacklist).\nCurrency codes must be valid ISO 4217 codes (e.g., `EUR`, `GBP`, `USD`).\n", "properties": { "restriction": { "type": "string", "enum": [ "ALLOWED", "BLOCKED" ], "description": "Defines the restriction type for the currency control.\n- `ALLOWED`: Only transactions in the listed currencies are permitted (whitelist).\n- `BLOCKED`: Transactions in the listed currencies are declined (blacklist).\n" }, "values": { "type": "array", "items": { "type": "string" }, "description": "List of ISO 4217 currency codes (e.g., `EUR`, `GBP`, `USD`).\nAt least one currency code must be provided.\n" } } }, "acceptanceMethods": { "type": "object", "nullable": true, "required": [ "type", "values", "restriction" ], "description": "Optional object defining which acceptance methods are permitted.\nThis control is an allow-list only. `restriction` must be `ALLOWED`.\nThe methods in `values` are the only ones permitted; every other method is declined.\nThere is no block-list. Do not send `BLOCKED`: it is not applied, and the methods in `values` are stored as the allowed set.\n", "properties": { "type": { "type": "string", "enum": [ "ACCEPTANCE_METHOD" ], "description": "Type of the acceptance method control to use. Currently only `ACCEPTANCE_METHOD` is supported.\n" }, "values": { "type": "array", "items": { "type": "string", "enum": [ "ONLINE", "MOBILE_WALLET", "MANUAL_ENTRY", "CONTACTLESS", "CHIP_DIP", "NOT_AVAILABLE", "MAGNETIC_STRIPE", "OTHER" ] }, "description": "List of acceptance methods that are allowed for transactions. \nOnly the methods listed here will be permitted if this control is provided.\nPossible values:\n- `ONLINE`: Card-not-present transactions\n- `MOBILE_WALLET`: Payments via mobile wallets (e.g., Apple Pay, Google Pay)\n- `MANUAL_ENTRY`: Card number entered manually\n- `CONTACTLESS`: Tap-based payments\n- `CHIP_DIP`: Inserted chip transactions\n- `NOT_AVAILABLE`: Transactions where acceptance method information is unavailable\n- `MAGNETIC_STRIPE`: Swipe-based payments\n- `OTHER`: Any other unspecified acceptance method\n" }, "restriction": { "type": "string", "enum": [ "ALLOWED" ], "description": "Must be `ALLOWED`. Only the methods in `values` are permitted.\n`BLOCKED` is not a supported restriction and does not block the methods in `values`.\n" } } } } } ] } } } }, "responses": { "204": { "description": "No Content. The card controls are saved when this response is returned." }, "400": { "$ref": "#/paths/~1cards/get/responses/400" }, "401": { "$ref": "#/paths/~1cards/get/responses/401" }, "403": { "$ref": "#/paths/~1cards/get/responses/403" }, "404": { "$ref": "#/paths/~1cards/post/responses/404" }, "500": { "$ref": "#/paths/~1cards/get/responses/500" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "This API uses oAuth2 with client credentials flow to [obtain the Bearer Token](/docs/authenticated-api-usage).", "bearerFormat": "JWT" } } }, "security": [ { "bearerAuth": [] } ] } ```