# Renew card validity Renew a card's validity period in hours. Renewal can be done for `VIRTUAL` cards and activated `PLASTIC` cards that were created or reissued with the `validity_period_hours` field set to a defined value greater than zero. When a card reaches its `valid_until` date, the card's status is set to `INOPERATIVE`. When this happens, a [Card updated](https://developers.pismo.io/events/docs/cards-update-1) event is generated. For existing cards that never had `validity_period_hours` defined, you can do it through this endpoint. When the card is renewed: * A new `valid_until` date is calculated and a [Card updated](https://developers.pismo.io/events/docs/cards-update-1) event is generated with `operation type` = `CARD_VALIDITY_RENEWAL`. * If the card's status is `INOPERATIVE`, the status changes to `NORMAL`. * If the card's status is `NORMAL`, `REISSUED`, `BLOCKED`, `PENDING` or `WARNING`, the status remains the same. **Note:** This endpoint requires an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a **401 Unauthoried** error message. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Card issuing - Cards", "version": "1.4.6", "description": "Card endpoints API", "contact": { "name": "API Support", "url": "https://developers.pismo.io/support/" }, "license": { "name": "Copyright Pismo" } }, "servers": [ { "url": "https://sandbox.pismolabs.io", "description": "Sandbox API server for testing." }, { "url": "https://gw-pci.pismolabs.io", "description": "Sandbox PCI API server for testing" } ], "security": [ { "BearerAuth": [] } ], "tags": [ { "name": "Card validity", "description": "Endpoints to manage card validity period." } ], "components": { "parameters": { "cardId": { "in": "path", "name": "cardId", "schema": { "type": "string" }, "description": "Pismo card ID", "required": true } }, "schemas": { "CardID2": { "type": "integer", "description": "Pismo card ID", "example": 123456 }, "CardStatus": { "type": "string", "description": "Card status enum. Refer to the [Card lifecycle and statuses](https://developers.pismo.io/pismo-docs/docs/card-lifecycle-and-statuses) guide for more information and a complete list.\n", "example": "NORMAL" }, "ValidityPeriodHours": { "type": "integer", "description": "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`. \n\nThis field is used to calculate the datetime value for `valid_until`.\n\nFor `VIRTUAL` and `PLASTIC` cards. Setting this field for `TEMPORARY` or `RECURRING` cards returns a **400 Bad request** error. \n", "example": 240 }, "ValidUntil": { "type": "string", "description": "Card validation date in UTC time (format:yyyy-MM-ddThh:mm:ssZ). For `TEMPORARY` virtual cards, which have a limited time frame, typically 24 hours (default), or according to the program parameter for this, which is why the date/time here is more granular than `expiration_date`. \n\nFor more information, refer to [Configuring temporary cards](https://developers.pismo.io/pismo-docs/docs/cards-overview-1#configuring-temporary-cards).\n", "example": "2021-07-03T17:23:18Z" }, "CardsValidityRenewBody": { "type": "object", "description": "Card validity period object", "required": [ "validity_period_hours" ], "properties": { "validity_period_hours": { "$ref": "#/components/schemas/ValidityPeriodHours2" } } }, "CardsValidityRenewResponse": { "type": "object", "description": "Card validity period renewal response object.", "properties": { "id": { "$ref": "#/components/schemas/CardID2" }, "status": { "$ref": "#/components/schemas/CardStatus" }, "validity_period_hours": { "$ref": "#/components/schemas/ValidityPeriodHours" }, "valid_until": { "$ref": "#/components/schemas/ValidUntil" } } }, "ValidityPeriodHours2": { "type": "integer", "description": "Sets a card's validity period in hours. Cannot exceed the card's `expiration_date`.\n\nREQUIRED for a `PLASTIC` or `VIRUTUAL` card. \n", "minimum": 1, "example": 48 } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in an \"Unauthorized\" error.", "bearerFormat": "JWT" } }, "responses": { "401Unauthorized": { "description": "Access token is missing or invalid" }, "403Forbidden": { "description": "You don't have permission to access this resource" }, "500InternalServer": { "description": "Internal server error" } } }, "paths": { "/wallet/v2/cards/{cardId}/validity/renew": { "patch": { "summary": "Renew card validity", "description": "Renew a card's validity period in hours. \n\nRenewal can be done for `VIRTUAL` cards and activated `PLASTIC` cards that were created or reissued with the `validity_period_hours` field set to a defined value greater than zero.\n\nWhen a card reaches its `valid_until` date, the card's status is set to `INOPERATIVE`. When this happens, a [Card updated](https://developers.pismo.io/events/docs/cards-update-1) event is generated.\n\nFor existing cards that never had `validity_period_hours` defined, you can do it through this endpoint.\n\nWhen the card is renewed: \n\n * A new `valid_until` date is calculated and a [Card updated](https://developers.pismo.io/events/docs/cards-update-1) event is generated with `operation type` = `CARD_VALIDITY_RENEWAL`.\n\n * If the card's status is `INOPERATIVE`, the status changes to `NORMAL`.\n\n * If the card's status is `NORMAL`, `REISSUED`, `BLOCKED`, `PENDING` or `WARNING`, the status remains the same. \n\n**Note:** This endpoint requires an account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a **401 Unauthoried** error message. \n", "operationId": "patch-v2-card-validity-renew", "tags": [ "Card validity" ], "parameters": [ { "$ref": "#/components/parameters/cardId" } ], "requestBody": { "description": "Request body", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardsValidityRenewBody" } } } }, "responses": { "200": { "description": "Card validity period was renewed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardsValidityRenewResponse" } } } }, "401": { "$ref": "#/components/responses/401Unauthorized" }, "403": { "$ref": "#/components/responses/403Forbidden" }, "500": { "$ref": "#/components/responses/500InternalServer" } } } } } } ```