# 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.
The card can be a Pismo-issued card or an external card. The card is added to the customer's digital wallet.
This endpoint generates a [Card on file created](https://developers.pismo.io/events/docs/cardsonfile-provision-1) event.
**Note**: This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Card issuing - Cards on file",
"version": "2.0.0",
"description": "Tokenize cards and manage digital wallets",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support"
},
"license": {
"name": "Copyright Pismo"
}
},
"servers": [
{
"url": "https://gw-pci.pismolabs.io",
"description": "Sandbox PCI API server for testing"
},
{
"url": "https://sandbox.pismolabs.io",
"description": "Sandbox API server for testing"
}
],
"tags": [
{
"name": "Cards on file",
"description": "Cards on file management"
}
],
"components": {
"parameters": {
"authPath": {
"name": "Authorization",
"in": "header",
"schema": {
"type": "string"
},
"required": true,
"description": "Account access token. An account token is embedded with an account ID. Tokens can expire quickly, which can result in an Unauthorized message.\n"
}
},
"schemas": {
"AcquirerID": {
"type": "string",
"description": "Acquirer ID.",
"maxLength": 50,
"example": "289900"
},
"CardExpirationDate": {
"type": "string",
"description": "Card expiration date (mmyy)",
"example": "1214"
},
"CardholderName": {
"type": "string",
"description": "Cardholder printed name. No limit.",
"example": "Mabel Syrup"
},
"CardName": {
"type": "string",
"description": "Card alias name. No limit.",
"example": "Vacation card"
},
"CardsOnFileCreate": {
"type": "object",
"required": [
"card_name",
"cvv",
"expiration_date",
"name",
"pan"
],
"properties": {
"card_name": {
"$ref": "#/components/schemas/CardName"
},
"cvv": {
"$ref": "#/components/schemas/CVV"
},
"expiration_date": {
"$ref": "#/components/schemas/CardExpirationDate"
},
"name": {
"$ref": "#/components/schemas/CardholderName"
},
"pan": {
"$ref": "#/components/schemas/Pan"
},
"acquirer": {
"$ref": "#/components/schemas/AcquirerID"
},
"card_profile": {
"$ref": "#/components/schemas/CardProfile"
},
"card_stored_uuid": {
"$ref": "#/components/schemas/CardStoredUuid"
},
"default_card": {
"$ref": "#/components/schemas/DefaultCard"
},
"document_number": {
"$ref": "#/components/schemas/DocumentNumber"
},
"issuer_card": {
"$ref": "#/components/schemas/IssuerCard"
},
"verified": {
"$ref": "#/components/schemas/Verified"
},
"metadata": {
"$ref": "#/components/schemas/Metadata"
}
},
"example": {
"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}"
}
},
"CardsOnFileErrorResponse": {
"properties": {
"error_code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
},
"CardsOnFileRegisterResponse": {
"properties": {
"card_stored_uuid": {
"$ref": "#/components/schemas/CardStoredUuid"
}
}
},
"CardStoredUuid": {
"type": "string",
"description": "API-generated card token from registration. This is NOT a field you can change, but it must be passed to identify the card.\n",
"example": "uuid-a-1ffff"
},
"CardProfile": {
"type": "string",
"description": "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.\n",
"example": "0XFFFFFF"
},
"CVV": {
"type": "string",
"description": "Card Verification Code (CVV) (the three numbers behind the card).",
"example": "564"
},
"DefaultCard": {
"type": "boolean",
"description": "Default card flag. Default is `false`.",
"example": true
},
"DocumentNumber": {
"type": "string",
"description": "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.\n",
"example": "7777888hh"
},
"IssuerCard": {
"type": "boolean",
"description": "Is this the issuer's card flag. Default is `false`.",
"example": false
},
"Metadata": {
"type": "string",
"description": "Any data object with key/value pairs. No limit on length.",
"example": "{ \"key\": \"value\"}"
},
"Pan": {
"type": "string",
"description": "Primary Account Number (PAN) to store",
"minLength": 12,
"maxLength": 19,
"example": "55689839363638393"
},
"Verified": {
"type": "boolean",
"description": "Is card verified flag. Default is `false`.",
"example": false
}
},
"responses": {
"400BadRequest": {
"description": "Bad Request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardsOnFileErrorResponse"
}
}
}
},
"500InternalServer": {
"description": "Internal server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardsOnFileErrorResponse"
}
}
}
}
}
},
"paths": {
"/cardsonfile/v2/cardsonfile/cards": {
"post": {
"summary": "Create card on file",
"description": "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.
\nThe card can be a Pismo-issued card or an external card. The card is added to the customer's digital wallet.
\n\nThis endpoint generates a [Card on file created](https://developers.pismo.io/events/docs/cardsonfile-provision-1) event.\n\n**Note**: This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.\n",
"operationId": "create-a-cardsonfile",
"deprecated": false,
"tags": [
"Cards on file"
],
"parameters": [
{
"in": "query",
"name": "skip_validation",
"schema": {
"type": "boolean"
},
"required": false,
"description": "Flag to skip acquirer and anti-fraud validation. Default is `false`."
},
{
"$ref": "#/components/parameters/authPath"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardsOnFileCreate"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CardsOnFileRegisterResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
}
}
}
}
}
```