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).

Feature activation – Renewal is not activate 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 a 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
• 3DS authentication methods (SMS OTP, OOB)
• 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)

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.

Caution – PIN not automatically changed on both cards during Renewal

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

Renewal process

The renewal process goes through the following 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

Tip – Get notified when a card is about to expire

The card.expiryAlert webhook helps you anticipate the card expiration.

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 the 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 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:

• cardStatus value is STOLEN, EXPIRED, LOST, DESTROYED.
• 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 prior to 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 other than STOLEN, EXPIRED, LOST, DESTROYED.

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

CURL

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
        }
    ]
}

Renewal failed responses

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

errorCode	errorMessage
34000	The card must be already activated.
34001	The request is refused because the card has expired.
34003	The 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:

• Enables you to set automatic renewal on a card-by-card basis if this is not set at product level.
• Allows you to 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 you need: /v1/cards/{cardId}/renewalDetails.

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

Attribute	Type	Description
renewalType	string	Define 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.

CURL

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

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