v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB

Cards on file

Create card on file

Create a card on file - an existing card that has been tokenized and stored in a digital wallet. The token is then used for payment transactions to avoid exposing sensitive data like the card's PAN and CVV.<br> The card can be a Pismo-issued card or an external card. The card is added to the customer's digital wallet.<br>

This endpoint generates a Card on file created event.

Note: This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.

post/cardsonfile/v2/cardsonfile/cards

Query parameters

skip_validationboolean

Skip acquirer and anti-fraud validation? Default is false.

Headers

Authorizationstring required

Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in an <b>Unauthorized</b> message.

Request body

card_namestring required

Card alias name. No limit.

cvvstring required

Card Verification Code (CVV) (the three numbers behind the card).

expiration_datestring required

Card expiration date (mmyy)

namestring required

Cardholder printed name. No limit.

panstring required

Primary Account Number (PAN) to store. The PAN shown here is a fictional example used for documentation purposes. It does not represent a real card number.

acquirerstring

Acquirer ID.

card_profilestring

Network card profile identifier or HEX color. A profile or HEX color determines a card's appearance in a mobile payment app or payment system. Issuers are responsible for configuring card profiles with the card network.

card_stored_uuidstring

API-generated card token from registration. This is NOT a field you can change, but it must be passed to identify the card.

default_cardboolean

Is this card the default card? Default is false.

document_numberstring

Cardholder government document number. This can be from any document that identifies the cardholder such as a Tax ID, State ID, or driver's license.

issuer_cardboolean

Is this the issuer's card? Default is false.

verifiedboolean

Is card verified? Default is false.

metadatastring

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.

Example request

{
  "card_name": "My Card",
  "card_profile": "0XFF00FF",
  "cvv": "123",
  "default_card": true,
  "document_number": "41440022209",
  "expiration_date": "1224",
  "issuer_card": true,
  "name": "Vacation card",
  "pan": "5448280000000007",
  "verified": true,
  "metadata": "{any_key: any_value}"
}

Response

Success

card_stored_uuidstring

API-generated card token from registration. This is NOT a field you can change, but it must be passed to identify the card.

Example response

{
  "card_stored_uuid": "uuid-a-1ffff"
}