# Create card validation
Create a new invoice validation for a given tokenized card. A random transacation amount between 1.00 and 5.00 (later chargebacked) is created for the cardholder to approve, which requires logging into an online banking account. The cardholder has up to 3 tries and 96 hours to input the correct amount. If the validation fails, the card is deleted from the wallet.
This endpoint generates a [Card on file validation result received](https://developers.pismo.io/events/docs/cardsonfile-verification-1) event. If the validation fails, it generates an [Card excluded](https://developers.pismo.io/events/docs/cardsonfile-exclusion-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": "Validation",
"description": "Cards on file validations"
}
],
"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"
},
"uuidPath": {
"name": "uuid",
"in": "path",
"schema": {
"type": "string"
},
"description": "Card UUID (token) to validate.",
"required": true
}
},
"schemas": {
"CardsOnFileErrorResponse": {
"properties": {
"error_code": {
"type": "string",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error message"
}
}
},
"ValidationExpiration": {
"type": "number",
"description": "When validation expires since creation in hours - 96 maximum. Default is 96.",
"minimum": 1,
"maximum": 96
},
"ValidationRemainingTries": {
"type": "number",
"description": "Maximum card validation tries - 3 tries maximum. Default is 3.",
"minimum": 1,
"maximum": 3
},
"ValidationRequestModel": {
"properties": {
"type": {
"$ref": "#/components/schemas/ValidationType"
},
"expiration_hours": {
"$ref": "#/components/schemas/ValidationExpiration"
},
"remaining_tries": {
"$ref": "#/components/schemas/ValidationRemainingTries"
}
},
"example": {
"type": "INVOICE",
"expiration_hours": 96,
"remaining_tries": 3
}
},
"ValidationResponseModel": {
"allOf": [
{
"$ref": "#/components/schemas/ValidationRequestModel"
},
{
"type": "object",
"properties": {
"uuid": {
"type": "string",
"description": "Unique validation ID"
},
"type": {
"type": "string",
"description": "Validation type, currently, only `INVOICE`."
},
"status": {
"type": "string",
"enum": [
"IN_PROGRESS",
"SUCCESS",
"FAILED"
],
"description": "Validation status enum - `IN_PROGRESS`, `SUCCESS`, or `FAILED`"
},
"expiration_hours": {
"type": "number",
"description": "Validation expiration since creation in hours. Maximum is 96",
"minimum": 1,
"maximum": 96
},
"remaining_tries": {
"type": "number",
"description": "Maximum card validation tries. Maximum is 3.",
"minimum": 1,
"maximum": 3
},
"inclusion_date": {
"type": "string",
"description": "Validation creation date in ISO 8601 format, i.e., 2019-09-04T19:09:53.881Z"
},
"expiration_date": {
"type": "string",
"description": "Date validation expires if not validated yet in ISO 8601 format, i.e., 2019-09-08T19:09:53.881Z"
},
"activation_date": {
"type": "string",
"description": "When validated date in ISO 8601 format, i.e., 2019-09-08T19:09:53.881Z"
},
"cancellation_date": {
"type": "string",
"description": "Validation cancelled date, by expiration or out of remaining tries, in ISO 8601 format, i.e., 2019-09-08T19:09:53.881Z"
},
"refunded_at": {
"type": "string",
"description": "When charge refunded in in ISO 8601 format, i.e., 2019-09-08T19:09:53.881Z"
},
"refund_id": {
"type": "string",
"description": "Refund ID"
}
}
}
],
"example": {
"uuid": "93ae5a79-cf47-11e9-814f-6c2b59562ec2",
"type": "INVOICE",
"status": "IN_PROGRESS",
"expiration_hours": 96,
"inclusion_date": "2019-09-04T19:09:53.881Z",
"expiration_date": "2019-09-08T19:09:53.881Z",
"activation_date": "2019-09-04T19:09:53.881Z",
"cancellation_date": "2192-09-08T19:09:53.881Z",
"remaining_tries": 3,
"refunded_at": null,
"refund_id": null
}
},
"ValidationType": {
"type": "string",
"enum": [
"INVOICE"
],
"description": "Validation type, currently only `INVOICE`."
}
},
"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/{uuid}/validations": {
"post": {
"summary": "Create card validation",
"description": "Create a new invoice validation for a given tokenized card. A random transacation amount between 1.00 and 5.00 (later chargebacked) is created for the cardholder to approve, which requires logging into an online banking account. The cardholder has up to 3 tries and 96 hours to input the correct amount. If the validation fails, the card is deleted from the wallet.
\n\nThis endpoint generates a [Card on file validation result received](https://developers.pismo.io/events/docs/cardsonfile-verification-1) event. If the validation fails, it generates an [Card excluded](https://developers.pismo.io/events/docs/cardsonfile-exclusion-1) event.\n\n**Note**: This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.\n",
"operationId": "create-a-new-validation-for-a-given-card",
"tags": [
"Validation"
],
"parameters": [
{
"$ref": "#/components/parameters/uuidPath"
},
{
"$ref": "#/components/parameters/authPath"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationRequestModel"
}
}
}
},
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidationResponseModel"
}
}
}
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"500": {
"$ref": "#/components/responses/500InternalServer"
}
}
}
}
}
}
```