---
title: "Create card"
method: POST
path: "/wallet/v2/cards"
tags: ["Cards"]
---

# Create card

`POST /wallet/v2/cards`

Create a virtual or physical (plastic/metal) card.

Refer to the [Cards management](https://developers.pismo.io/pismo-docs/docs/cards-overview-1) guide for more information about physical and virtual cards.

For more information about embossing, refer to [Embossing flows](https://developers.pismo.io/pismo-docs/docs/physical-card-embossing#embossing-flow).

This endpoint generates a [Card created](https://developers.pismo.io/events/docs/cards-create-1) event. The card's PCI data is created asynchronously as is the Card created event. Any operation that tries to access a card before this event, such as update password or get PCI information, is going to return a **404, not found** error.

## Headers

- `x-customer-id` integer, required
- `x-idempotency-key` string

## Request body

- CreateCard — Card create request payload
  - `name` string, required — Card alias name for a `VIRTUAL` card. This field is **REQUIRED** to be unique for each `VIRTUAL` card a customer owns. No matter what is passed for a `PLASTIC` card, the value is always `PLASTIC`.
  - `type` 'PLASTIC' | 'VIRTUAL' | 'RECURRING' | 'TEMPORARY', required — Card type
  - `printed_name` string — Printed name on physical card
  - `pin_length` 4 | 6 — PIN length - 4 or 6 digits. Default is `4`.
  - `cvv_rotation_interval_hours` integer — <b>REQUIRED</b> for a virtual card. Virtual card CVV rotation interval in hours. To force a rotation manually, call the [Rotate virtual card CVV](https://developers.pismo.io/pismo-docs/reference/post-v2-reset-cvv) endpoint. If `0` is passed, the CVV will **NOT** be rotated.
  - `transaction_limit` string — Optional for virtual cards. Maximum amount allowed per transaction. Set up to the approved limit. If not set, account limit is used.
  - `metadata` string — Any data object with key/value pairs. No limit on length. **Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis#metadata).
  - `embossing_group` string — Embossing group name. Clients can work with multi-embossers. You can use this field to notify an embosser about a card request. If this parameter is not passed, and you work with multi-embossers, the default embosser is used. For more information, refer to the [Physical card embossing](https://developers.pismo.io/pismo-docs/docs/physical-card-embossing) guide.
  - `embossing_custom_field` string — For physical cards. Additional information for embossing company. For example: tracking number or whether the card should be plastic or metal. You can use this field for any embossing needs specific to your business. Whatever is sent must be agreed upon with the embosser&mdash;what to send, what values to send, what format to send, what size to send for each value, and so on.
  - `contactless_enabled` boolean — For physical cards. Is card enabled for contactless transactions? With contactless transactions, you hold or tap the card on contactless-enabled card reader to complete a transaction. This requires that both the card and the terminal have Near Field Communication (NFC) technology. Most embossers can create plastic contactless cards. Default is `true`.
  - `abu_enabled` boolean — This field is **DEPRECATED**. For more information, refer to the [ABU documentation](https://developers.pismo.io/pismo-docs/docs/cards-overview-1#mastercards-automatic-billing-updater-option) in the Cards overview guide. When a card is created or reissued, or its account credentials change, Mastercard is notified if this feaure is enabled. Notification updates are sent to Mastercard on a daily basis. For more information, refer to Mastercard's <a href="https://developer.mastercard.com/product/automatic-billing-updater-abu/" target="_blank">ABU</a> documentation.
  - `template_id` string — Template ID. Templates are used to implement the BIN override feature. For more information, refer to the [BIN override](https://developers.pismo.io/pismo-docs/docs/bin-override-feature) guide.
  - `mode_type` 'SINGLE' | 'COMBO' — Mode type enum - `SINGLE` or `COMBO`. A combo card can have both a credit and debit *mode*, meaning it is associated with both a credit and debit program and account. A single card has one mode - credit or debit. Refer to the [mode documentation](https://developers.pismo.io/pismo-docs/docs/cards-overview-1#create-a-combination-card-with-card-modes) in the Card overview guide for more information.
  - `generate_pvv` boolean — For physical cards. Should a PIN Verification Value (PVV) be generated and inserted into the card tracks during embossing, or should the PVV be generated and sent to Visa when updating the card's PIN? Visa's PIN Verification Service (PVS) **must** be enabled. The default is `false`.
  - `validity_period_hours` integer — How long, in hours, the card is valid. Cannot exceed the card's `expiration_date`. Once this period is exceeded, and the card has a `NORMAL`, `BLOCKED`, `PENDING`, `WARNING` or `REISSUED` status, its status becomes `INOPERATIVE`. This field is used to calculate the datetime value for `valid_until`. For `VIRTUAL` and `PLASTIC` cards. Setting this field for `TEMPORARY` or `RECURRING` cards returns a **400 Bad request** error.
  - `status` 'PENDING' | 'PROCESSING' | 'CANCELLED' | 'SETTLED' | 'PROCESSED' — PENDING: Charge is scheduled and waiting for the cycle to close. PROCESSING: Cycle closing process has started and is awaiting completion. CANCELLED: Charge canceled due to link cancellation. SETTLED: Amount is zero and/or `minimum_spend_to_charge` has not been reached. PROCESSED: Charge was posted on the statement."
  - `brand` 'VISA' | 'MASTERCARD' | 'ELO' | 'RUPAY' | 'PRIVATE' — Card network that overrides the one set up by the card's program. **REQUIRED** when the `status` field is used for `UNNUMBERED` cards.
  - `expiration_date` string — Card expiration date (format = yymm). If passed, the card expiration date is not calculated using the "Card expiration (# of months)" program parameter.
  - `atm_change_online_pin_when_script_sent` boolean — During ATM transactions, should the card's online PIN be updated when the offline PIN change script is sent to the terminal for execution? If `false`, the online PIN is only updated after a subsequent transaction, once the Pismo platform verifies - via the card's CVR (Card Verification Results) — that the offline script was successfully applied. Default is `false`.

## Response `200`

Card creation response when `x-idempotency-key` is passed and the card had already been created in a preivous call.

- CreateCardResponse — Card creation response object
  - `id` integer — ID of card to create relationship for
  - `name` string — Card alias name for a `VIRTUAL` card. This field is **REQUIRED** to be unique for each `VIRTUAL` card a customer owns. No matter what is passed for a `PLASTIC` card, the value is always `PLASTIC`.
  - `status` 'ACTIVE' | 'SUSPENDED' | 'PENDING' — Card status
  - `type` 'PLASTIC' | 'VIRTUAL' | 'RECURRING' | 'TEMPORARY' — Card type
  - `transaction_limit` string — Optional for virtual cards. Maximum amount allowed per transaction. Set up to the approved limit. If not set, account limit is used.
  - `metadata` string — Any data object with key/value pairs. No limit on length. **Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis#metadata).
  - `cvv_rotation_interval_hours` integer — <b>REQUIRED</b> for a virtual card. Virtual card CVV rotation interval in hours. To force a rotation manually, call the [Rotate virtual card CVV](https://developers.pismo.io/pismo-docs/reference/post-v2-reset-cvv) endpoint. If `0` is passed, the CVV will **NOT** be rotated.
  - `embossing_custom_field` string — For physical cards. Additional information for embossing company. For example: tracking number or whether the card should be plastic or metal. You can use this field for any embossing needs specific to your business. Whatever is sent must be agreed upon with the embosser&mdash;what to send, what values to send, what format to send, what size to send for each value, and so on.
  - `contactless_enabled` boolean — For physical cards. Is card enabled for contactless transactions? With contactless transactions, you hold or tap the card on contactless-enabled card reader to complete a transaction. This requires that both the card and the terminal have Near Field Communication (NFC) technology. Most embossers can create plastic contactless cards. Default is `true`.
  - `abu_enabled` boolean — This field is **DEPRECATED**. For more information, refer to the [ABU documentation](https://developers.pismo.io/pismo-docs/docs/cards-overview-1#mastercards-automatic-billing-updater-option) in the Cards overview guide. When a card is created or reissued, or its account credentials change, Mastercard is notified if this feaure is enabled. Notification updates are sent to Mastercard on a daily basis. For more information, refer to Mastercard's <a href="https://developer.mastercard.com/product/automatic-billing-updater-abu/" target="_blank">ABU</a> documentation.
  - `template_id` string — Template ID. Templates are used to implement the BIN override feature. For more information, refer to the [BIN override](https://developers.pismo.io/pismo-docs/docs/bin-override-feature) guide.
  - `mode_type` 'SINGLE' | 'COMBO' — Mode type enum - `SINGLE` or `COMBO`. A combo card can have both a credit and debit *mode*, meaning it is associated with both a credit and debit program and account. A single card has one mode - credit or debit. Refer to the [mode documentation](https://developers.pismo.io/pismo-docs/docs/cards-overview-1#create-a-combination-card-with-card-modes) in the Card overview guide for more information.
  - `validity_period_hours` integer — How long, in hours, the card is valid. Cannot exceed the card's `expiration_date`. Once this period is exceeded, and the card has a `NORMAL`, `BLOCKED`, `PENDING`, `WARNING` or `REISSUED` status, its status becomes `INOPERATIVE`. This field is used to calculate the datetime value for `valid_until`. For `VIRTUAL` and `PLASTIC` cards. Setting this field for `TEMPORARY` or `RECURRING` cards returns a **400 Bad request** error.
  - `valid_until` string — Card is valid until this datetime. ISO 8601 format. Once this time is exceeded, and the card has a `NORMAL`, `BLOCKED`, `PENDING`, `WARNING` or `REISSUED` status, its status becomes `INOPERATIVE`. This field's value is calculated using the `validity_period_hours`.

## Other responses

- `201` — Card creation response - with or without `x-idempotency-key` passed.
- `401` — Access token is missing or invalid
- `403` — The request has been lost
- `409` — You already have a card with this type and name active
- `500` — Internal server error

---

[API](https://skmtc.net/pismo/apis/platform-authentication.md) · [All operations](https://skmtc.net/pismo/apis/platform-authentication/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pismo/platform-authentication/versions/935b62e16de4/schema)