Skip to main content

Card Renewals

Weavr offers two possible options from a renewal perspective, when a card reaches expiry.

  • NO_RENEW - The card expires and can no longer be used
  • RENEW - The card will be renewed. The card number will remain the same but the CVV and expiry date will be updated.

The renewalType (RENEW, NO_RENEW) can be set when creating a new card via POST /multi/managed_cards, or can be updated for an existing card via PATCH multi/managed_cards/{id}. The renewal type of an individual card is also displayed in the portal, in the details panel when clicking on the card.

info

renewalType is an optional field, and if omitted, the card will be defaulted to NO_RENEW. Cards of state ACTIVE and BLOCKED can be set to RENEW and will maintain this state once they have been renewed.

Weavr will send Card Notifications to inform you of events related to upcoming renewal and expiry of cards, so that you can ensure that the desired action takes place upon renewal or expiry. These notifications will specify information including the current renewal setting for the card (RENEW, NO_RENEW), the renewal date (renewalTimestamp), and the expiry date of the card (expiryMmyy).

The webhook url is ${WEBHOOK_URL}/managed_cards/expiries/watch and there are three eventType :

CARD_ABOUT_TO_EXPIRE - Notification of an upcoming expiry date, and associated renewal date if RENEW has been set for the card

CARD_RENEWED - Notification that a card has been renewed

CARD_EXPIRED - Notification that a card has expired without being renewed

For a card set as RENEW, the renewal process (and most crucially the dates) will depend on whether the card is a virtual or physical card.

Virtual cards​

Virtual cards are renewed the day before expiry, since they do not need to be physically delivered.

Notifications​

  • 60 days before expiry - A ‘Card about to expire’ webhook is sent, informing you that the card expiry date is approaching
  • 30 days before expiry - A further CARD_ABOUT_TO_EXPIRE webhook is sent
  • 1 day before expiry
    • If card is set to RENEW - A CARD_RENEWED webhook is sent, containing the new expiry date and renewal date
    • If card is set to NO_RENEW - A final CARD_ABOUT_TO_EXPIRE webhook is sent
  • On expiry date - If card is set to NO_RENEW, a CARD_EXPIRED webhook is sent

After a card has been renewed, calling the GET /multi/managed_cards/{id} endpoint will return the expiry date and CVV of the renewed card.

Physical Cards​

tip

Physical cards will be delivered to the delivery address associated with the card (that was provided when the card was upgraded to physical). We recommend that the card holder's address is checked as the renewal date approaches. If a change in address is required, this can be updated via PATCH /multi/managed_cards/{id}.

Physical cards are renewed 30 days before the expiry date to allow time for delivery; and they require activation by your customer once they have arrived.

Your customer’s old card will continue to work even after a renewal has been triggered, and whilst the new card is in transit. If the GET /multi/managed_cards/{id} endpoint is called during this time, the details of the old card will be returned. The old card will continue to work up until the expiry date, or up until the new card is activated, whichever is sooner. A button will be required in your application for your customer to activate their card, triggering the POST /multi/managed_cards/{id}/physical/activate endpoint, and the new card will only start working once this is done. Once a card has been activated, calling GET /multi/managed_cards/{id} will return the CVV and expiry date of the new card.

Notifications​

  • 60 days before expiry - A CARD_ABOUT_TO_EXPIRE webhook is sent, informing you that the card expiry date is approaching
  • 30 days before expiry
    • If a card is set to RENEW - A CARD_RENEWED webhook is sent, containing the new expiry date and renewal date
    • If card is set to NO_RENEW - A further CARD_ABOUT_TO_EXPIRE webhook is sent
  • 1 day before expiry - If card is set to NO_RENEW, a final CARD_ABOUT_TO_EXPIRE webhook is sent
  • On expiry date - If card is set to NO_RENEW, a CARD_EXPIRED webhook is sent

A physical card can still be updated from NO_RENEW to RENEW after the renewal date has passed (but before the expiry date). The card will be renewed and the new card dispatched at the next opportunity, and a ‘Card renewed’ webhook will be sent. However, to ensure that the card arrives in time, and to avoid any period where the customer is without a card, we recommend this action be taken before the renewal date.

Sandbox and simulator​

In order to test this functionality, three endpoints are available via the simulator, and the sample requests are included in the postman collection that can be downloaded from the sandbox environment.

  • Card about to expire : Triggers a CARD_ABOUT_TO_EXPIRE webhook. Can be used on cards that have renewalType set to either RENEW or NO_RENEW.
  • Renew Card : Triggers a card to renew, including a CARD_RENEWED webhook. Can be used on cards that have renewalType set to RENEW. If a physical card is entered in the request, and you want to see the new expiry returned via GET /multi/managed_cards/{id}, you will need to call the POST /multi/managed_cards/{id}/physical/activate endpoint first
  • Expire Card: Triggers a card to expire and a CARD_EXPIRED webhook. Can be used on cards that have renewalType set to NO_RENEW.