Renew a card

Last updated: October 9, 2024

Renewing a card means creating a new card based on the configuration of a previous card.

You request to renew a physical or virtual card via the API. The renewed card has new, unique credentials, including:
- Primary account number (PAN)
- Security code (CVV)
- Expiry date, based on the lifetime inherited from the original card product configuration
  You can edit the expiry date, if needed.
For physical cards, the renewed card is delivered to the same address as the original card by default. Alternatively, you can specify a new delivery address in your API request.
When the cardholder receives the renewed card, it must be activated using one of the following methods:
- By the cardholder at a point of sale (PoS)
- By you via the API
Once activated:
- The wallet token is transferred from the original card to the renewed card.
- The renewed card is enrolled with the same 3DS authentication method as the original card.
- The velocity controls and control profiles on the original card are applied to the renewed card.
The cardholder can start using the renewed card. They can also continue using the original card until it expires since all card controls and control profiles are linked across both cards.

Note

You must renew an active card before it expires. You cannot renew a card that is inactive or suspended.

To renew a card, call the Renew card endpoint, providing the cardId and optionally:

A display name for the card
Shipping instructions for physical cards
Your reference for the card
Any relevant metadata

post

https://api.checkout.com/issuing/cards/{cardId}/renew


1{
2  "display_name": "HANNAH BRET",
3  "shipping_instructions": {
4    "shipping_recipient": "Hannah Bret",
5    "shipping_address": {
6      "address_line1": "123 High St.",
7      "address_line2": "Flat 456",
8      "city": "London",
9      "state": "London",
10      "zip": "SW1A 1AA",
11      "country": "GB"
12    },
13    "additional_comment": "string"
14  },
15  "reference": "X-123456-N11",
16  "metadata": {
17    "udf1": "metadata1",
18    "udf2": "metadata2",
19    "udf3": "metadata3",
20    "udf4": "metadata4",
21    "udf5": "metadata5"
22  }
23}


1{
2  "display_name": "HANNAH BRET",
3  "reference": "X-123456-N11",
4  "metadata": {
5    "udf1": "metadata1",
6    "udf2": "metadata2",
7    "udf3": "metadata3",
8    "udf4": "metadata4",
9    "udf5": "metadata5"
10  }
11}

The response returns the full card details and credentials, and possible next actions.


1{
2  "parent_card_id": "crd_fa6psq242dcd6fdn5gifcq1491",
3  "cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
4  "status": "inactive",
5  "type": "virtual",
6  "id": "crd_zdihd7452165pk5lgywaa52147",
7  "client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
8  "entity_id": "ent_fa6psq242dcd6fdn5gifcq1491",
9  "last_four": 1234,
10  "expiry_year": 2025,
11  "expiry_month": 5,
12  "display_name": "HANNAH BRET",
13  "reference": "X-123456-N11",
14  "created_date": "2021-09-09T19:41:39Z",
15  "billing_currency": "USD",
16  "issuing_country": "US",
17  "_links": {
18    "self": {
19      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
20      "actions": [
21        "GET"
22      ],
23      "types": [
24        "application/json"
25      ]
26    },
27    "credentials": {
28      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials",
29      "actions": [
30        "GET"
31      ],
32      "types": [
33        "application/json"
34      ]
35    },
36    "activate": {
37      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/activate",
38      "actions": [
39        "POST"
40      ],
41      "types": [
42        "application/json"
43      ]
44    },
45    "controls": {
46      "href": "https://api.checkout.com/issuing/controls?target_id=crd_fa6psq42dcdd6fdn5gifcq1491",
47      "actions": [
48        "GET"
49      ],
50      "types": [
51        "application/json"
52      ]
53    }
54  }
55}

To activate a renewed card, call the Activate card endpoint, providing the cardId.

post

https://api.checkout.com/issuing/cards/{cardId}/activate

The response returns the cardId and possible next actions.


1{
2  "_links": {
3    "self": {
4      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
5      "actions": [
6        "GET"
7      ],
8      "types": [
9        "application/json"
10      ]
11    },
12    "revoke": {
13      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke",
14      "actions": [
15        "POST"
16      ],
17      "types": [
18        "application/json"
19      ]
20    },
21    "suspend": {
22      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/suspend",
23      "actions": [
24        "POST"
25      ],
26      "types": [
27        "application/json"
28      ]
29    }
30  }
31}

A renewed card's expiry date is based on the lifetime inherited from the card product configuration.

To edit the expiry date, call the Update card details endpoint, providing:

The cardId
The expiry month and year

patch

https://api.checkout.com/issuing/cards/{cardId}


1{
2  "expiry_month": 5,
3  "expiry_year": 2030
4}

The response returns the cardId and the timestamp for the update.


1{
2  "last_modified_date": "2021-09-09T19:41:39Z",
3  "_links": {
4    "self": {
5      "href": "https://api.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491",
6      "actions": [
7        "GET"
8      ],
9      "types": [
10        "application/json"
11      ]
12    }
13  }
14}

Renew a card

How it works

Note

Renew a card

Request example

Response example

Activate a renewed card

Response example

Edit card expiry date

Request example

Response example