Appearance

Renewal ​

Renewing a Card consists of issuing a new card before the original one expires. This new card has the same attributes as their previous one.

Card Renewal is tied to your Card Program and the kind of product issued. Issuing services can be adjusted to optimize the costs and adapt the renewal experience (e.g., packaging).

Toolbox icon

Feature activation – Renewal is not activated by default

Please contact your Treezor Account Manager if you're interested in this feature.

Renewed card specificities ​

When a card is renewed, some attributes remain identical to the original one while others have new values. This ensures continuity of services (e.g., X-Pay and 3DS enrollments) and a smoother experience (identical PIN code) for cardholders.

Inherited attributes ​

  • Card design
  • Limits and restrictions
  • Card authentication methods (OOB, SMS OTP)
  • X-Pay enrollments
  • PIN code
  • cardTag
  • Type of card (i.e., Virtual or Physical)

New attributes ​

  • cardId
  • PAN
  • expiryDate
  • publicToken
  • cvv
  • The outstanding spending limits, which are reset (i.e., if €90/100 were spent on the previous Card, €100 will still be usable on the renewed one)
Info icon

Information – Virtual Converted Cards are automatically produced

Renewing a virtual converted card results in a new virtual converted card. You don't need to go through the conversion process again.

Warning icon

Caution – PIN not automatically changed on both cards during Renewal

If the PIN code of the card being renewed changes during the renewal procedure, then the PIN code must also be changed manually for the renewed Card.

Renewal process ​

The renewal process follows these steps:

  1. The card renewal process is triggered (manually or automatically)
  2. The card.renew webhook is sent
  3. The cardholder receives the new card (inactive)
  4. The cardholder activates the new card
  5. The original card status is set to EXPIRED
Info icon

Information – Expiry alert and renewal are uncorrelated

While the card.expiryAlert webhook is convenient to anticipate the card expiration, please note there is no correlation with the renewal process.

Automatic renewal ​

The automatic card renewal process is triggered at the beginning of each month. A request for renewal is sent to the card processor to renew all cards meeting the following conditions:

  • Expire within the current month – expiryDate in the current month minus 1 day.
  • Are active – isLive attribute is set to 1.
  • Are unlocked – cardStatus value is UNLOCK.
  • Are renewable – Attached to a product code with the automatic renewal attribute, or the renewal type set to automatic (“renewalType”: “A”).

Won’t be renewed cards which:

  • renewalType value is N.
  • Have already been renewed (i.e.,renewalDate value is other than null).

Manual renewal ​

In case you need to renew a card before its expiration month, you can trigger the card renewal manually. This is only possible for active cards that haven't been renewed yet, and whose status is UNLOCK.

Use the following request with the cardId as a path parameter to renew a card manually.

Endpoint: /v1/cards/{cardId}/renew

bash
curl -X PUT '{baseUrl}/v1/cards/{cardId}/renew' \
	--header 'Authorization: Bearer {accessToken}'

If successful, the card.renew event is sent, and the Card object is returned:

json
{
    "cards": [
        {
            "cardId": 241709,
            "userId": 8290083,
            "walletId": 2464676,
            "walletCardtransactionId": 2473310,
            "mccRestrictionGroupId": 95447,
            "merchantRestrictionGroupId": 45599,
            "countryRestrictionGroupId": 165327,
            "publicToken": "107277882",
            "cardTag": "",
            "statusCode": "UNLOCK",
            "isLive": 0,
            "pinTryExceeds": 0,
            "maskedPan": "519872******4839",
            "embossedName": "ALEX OAK",
            "expiryDate": "2026-10-31",
            "CVV": "260",
            "startDate": "2023-10-23",
            "endDate": "0000-00-00",
            "countryCode": "FR",
            "currencyCode": "EUR",
            "lang": null,
            "deliveryTitle": "M",
            "deliveryLastname": "OAK",
            "deliveryFirstname": "ALEX",
            "deliveryAddress1": "15 EDGEWOOD ROAD",
            "deliveryAddress2": "",
            "deliveryAddress3": "",
            "deliveryCity": "ROSEWOOD",
            "deliveryPostcode": "12365",
            "deliveryCountry": "FR",
            "mobileSent": "+33633333333",
            "limitsGroup": "TRZ-VL-001",
            "permsGroup": "TRZ-CU-011",
            "cardDesign": "13664",
            "virtualConverted": 0,
            "physical": 0,
            "optionAtm": 0,
            "optionForeign": 0,
            "optionOnline": 1,
            "optionNfc": 1,
            "limitAtmYear": 0,
            "limitAtmMonth": 0,
            "limitAtmWeek": 0,
            "limitAtmDay": 1,
            "limitAtmAll": 1,
            "limitPaymentYear": 0,
            "limitPaymentMonth": 0,
            "limitPaymentWeek": 0,
            "limitPaymentDay": 25,
            "limitPaymentAll": 25,
            "paymentDailyLimit": 0.0,
            "totalAtmYear": null,
            "totalAtmMonth": null,
            "totalAtmWeek": null,
            "totalAtmDay": null,
            "totalAtmAll": null,
            "totalPaymentYear": null,
            "totalPaymentMonth": null,
            "totalPaymentWeek": null,
            "totalPaymentDay": null,
            "totalPaymentAll": null,
            "createdBy": 945198,
            "createdDate": "2023-10-31 10:37:04",
            "modifiedBy": 0,
            "modifiedDate": "0000-00-00 00:00:00",
            "renewalType": null,
            "renewalDate": "2024-04-01",
            "originalCardId": null,
            "totalRows": null,
            "designCode": null,
            "cardLanguages": "",
            "eventName": "Master Wallet",
            "eventAlias": "master-wallet-6537b83040735",
            "restrictionGroupLimits": null,
            "cancellationNumber": "",
            "metadata": null,
            "renewalDate": null,
            "renewalType": null,
            "originalCardId": null,
            "logoId": "",
            "logoBackId": "",
            "packageId": "",
            "customizeInfo": "",
            "letterCustomizedInfo": "",
            "freeCustomizedInfo": "",
            "deliveryMethod": null,
            "pinMailer": null,
            "batchDeliveryId": null,
            "sendToParent": 0
        }
    ]
}

Endpoint: /cards/{cardId}/renew

bash
curl -X PUT '{pciBaseUrl}/cards/{cardId}/renew' \
	--header 'Authorization: Bearer {accessToken}' \
    --header 'Content-Type: application/json' \
	-d '{payload}'

Here is an example of {payload}:

json
{
    "userId": "100642533",
    "pinRenewOption": 1     // To keep the previous PIN code
}

If successful, the card.renew event is sent, and the Card object is returned:

json
{
    "cards": [
        {
            "cardId": 241709,
            "userId": 8290083,
            "walletId": 2464676,
            "walletCardtransactionId": 2473310,
            "mccRestrictionGroupId": 95447,
            "merchantRestrictionGroupId": 45599,
            "countryRestrictionGroupId": 165327,
            "publicToken": "107277882",
            "cardTag": "",
            "statusCode": "UNLOCK",
            "isLive": 0,
            "pinTryExceeds": 0,
            "maskedPan": "519872******4839",
            "embossedName": "ALEX OAK",
            "expiryDate": "2026-10-31",
            "CVV": "260",
            "startDate": "2023-10-23",
            "endDate": "0000-00-00",
            "countryCode": "FR",
            "currencyCode": "EUR",
            "lang": null,
            "deliveryTitle": "M",
            "deliveryLastname": "OAK",
            "deliveryFirstname": "ALEX",
            "deliveryAddress1": "15 EDGEWOOD ROAD",
            "deliveryAddress2": "",
            "deliveryAddress3": "",
            "deliveryCity": "ROSEWOOD",
            "deliveryPostcode": "12365",
            "deliveryCountry": "FR",
            "mobileSent": "+33633333333",
            "limitsGroup": "TRZ-VL-001",
            "permsGroup": "TRZ-CU-011",
            "cardDesign": "13664",
            "virtualConverted": 0,
            "physical": 0,
            "optionAtm": 0,
            "optionForeign": 0,
            "optionOnline": 1,
            "optionNfc": 1,
            "limitAtmYear": 0,
            "limitAtmMonth": 0,
            "limitAtmWeek": 0,
            "limitAtmDay": 1,
            "limitAtmAll": 1,
            "limitPaymentYear": 0,
            "limitPaymentMonth": 0,
            "limitPaymentWeek": 0,
            "limitPaymentDay": 25,
            "limitPaymentAll": 25,
            "paymentDailyLimit": 0.0,
            "totalAtmYear": null,
            "totalAtmMonth": null,
            "totalAtmWeek": null,
            "totalAtmDay": null,
            "totalAtmAll": null,
            "totalPaymentYear": null,
            "totalPaymentMonth": null,
            "totalPaymentWeek": null,
            "totalPaymentDay": null,
            "totalPaymentAll": null,
            "createdBy": 945198,
            "createdDate": "2023-10-31 10:37:04",
            "modifiedBy": 0,
            "modifiedDate": "0000-00-00 00:00:00",
            "renewalType": null,
            "renewalDate": "2024-04-01",
            "originalCardId": null,
            "totalRows": null,
            "designCode": null,
            "cardLanguages": "",
            "eventName": "Master Wallet",
            "eventAlias": "master-wallet-6537b83040735",
            "restrictionGroupLimits": null,
            "cancellationNumber": "",
            "metadata": null,
            "renewalDate": null,
            "renewalType": null,
            "originalCardId": null,
            "logoId": "",
            "logoBackId": "",
            "packageId": "",
            "customizeInfo": "",
            "letterCustomizedInfo": "",
            "freeCustomizedInfo": "",
            "deliveryMethod": null,
            "pinMailer": null,
            "batchDeliveryId": null,
            "sendToParent": 0
        }
    ]
}

Renewal failed responses ​

The following HTTP 400 errors may occur when failing to renew a Card.

errorCodeerrorMessage
34000The card must be already activated.
34001The request is refused because the card has expired.
34003The card must not be stolen or lost or destroyed.

Activation of a renewed card ​

As a security measure, the new card is issued in an inactive state to ensure that a Card is not usable before the cardholder receives it.

Once received, the card can be activated, and the previous card status will be automatically set as EXPIRED. Expired cards can no longer be used, and this status is permanent.

Renewal Type (renewalType) ​

When creating a Card, the card renewal type (automatic or not) is defined by your Card Program. If renewalType is set to null and the product is auto-renewing, the card will be renewed.

The renewal type allows you to:

  • Set automatic renewal on a card-by-card basis if this is not set at product level.
  • Exclude a card from automatic renewal (for a user who closes their account, for example).

A dedicated endpoint allows you to update the renewal type as needed: /v1/cards/{cardId}/renewalDetails.

Note icon

Note – Can’t update renewalType for cards expiring within the month

You may use the /v1/cards/{cardId}/renew request to renew the card manually.

Parameters ​

AttributeTypeDescription
renewalTypestringDefine how the Card is to be renewed. Values can be the following:
  • A – Automatic renewal.
  • N – Non-automatic renewal.

Use the following request with the cardId as a path parameter to update the card renewal type.

bash
curl -X PUT '{baseUrl}/v1/cards/{cardId}/renewalDetails' \
	--header 'Authorization: Bearer {accessToken}' \
	--header 'Content-Type: application/json' \
	-d '{payload}'

There is an example of {payload}:

json
{
    "renewalType": "A"
}

Returns the Card Renewal Details object if successful:

json
{
    "cardRenewalDetails": {
        "renewalType": "A"
    }
}

Endpoints ​

EndpointScope
/v1/cards/{cardId}/renewalDetails 
Retrieve the card renewal options.		admin, legal, read_write
/v1/cards/{cardId}/renewalDetails
Update the card renewal options.		admin, legal, read_write
/v1/cards/{cardId}/renew
Renew a Card manually.		admin, legal, read_write