Card Renewal & Replacement

Back
Next

Card Renewal & Replacement

This page explains how your system can renew or replace cards after issuance. The flow differs depending on whether the card is virtual or physical. Virtual renewal is a single renew request. Physical renewal is a two-step process that first orders the renewed card and then migrates the cardholder to it after receipt. Replacement can be used for either virtual or physical cards and can optionally be followed by Complete Card Replacement to transfer selected data from the old card to the new card.

Overview

Renewal is used when an existing card should continue with a refreshed lifecycle, typically around expiry handling or reissue needs. Replacement is used when a new card must be created, such as for lost, stolen, or damaged cards. For replacement activation, virtual cards activate simultaneously because they are issued instantly, while physical cards must be activated when received.

1. Renewal – Virtual Card

For a virtual card, renewal is a single API call.

How the flow works

  1. A cardholder requests virtual card renewal through your mobile or web application.

  2. Your system calls:
    POST /thr/thredd/cards/{publicToken}/renew

  3. Payblr returns:
    204 No Content

  4. Your systems confirm that the renewal request completed successfully.

Notes

A successful virtual renewal returns no response body. This flow is intended for renewing a virtual card outside the normal autorenewal cycle.

2. Renewal – Physical Card

For a physical card, renewal is a two-step process.

How the flow works

  1. A cardholder requests physical card renewal through your mobile or web application.

  2. Your systems call:
    POST /thr/thredd/cards/{publicToken}/renew
    with:
    {"renewStep":"renew"}

  3. Payblr returns: 204 No Content. This orders the renewed physical card.

  4. After the cardholder receives the renewed card, your systems call:
    POST /thr/thredd/cards/{publicToken}/renew
    with:
    {"renewStep":"migrate"}

  5. Payblr returns:
    204 No Content

  6. Your system then activates the renewed card using the card status endpoint. A successful status update returns response fields including status, cardStatusCode, updated, updatedBy, and description.

Notes

The physical renewal process is a two-step flow that in the end requires card to be activated through the card status endpoint.

3. Replacement – Virtual or Physical Card

Replacement creates a new card for the cardholder and can be used when a card is lost, stolen, damaged, or otherwise needs to be reissued. The Replace Card endpoint also supports transfer options such as balance, limit accumulators, child cards, and expiry handling. On success, the response includes new card details such as publicToken, customerReference, embossName, maskedPan, startDate, and expiryDate.

How the flow works

  1. A cardholder requests card replacement through your mobile or web application.

  2. Your system calls:
    POST /thr/thredd/cards/{publicToken}/replace

  3. Payblr returns: 200 OK. The response also includes the new card details.

  4. Your system confirms the replacement request to the cardholder.

Activation behavior

For virtual replacement cards, activation happens simultaneously because the card is issued instantly. For physical replacement cards, activation must happen when the customer receives the card, using the card status endpoint.

Recommended implementation note

If the original card is reported lost or stolen, it is recommended to first update the old card to status 41 so it can no longer be used. Also, when setting a card to lost, the validityDate field should be removed from the request body.

3.1 Complete Card Replacement

After a successful replacement, your system can optionally call Complete Card Replacement to transfer selected data from the old card to the new card. Request fields include: moveBalance, moveLimitAccumulators, moveChildCards, moveExpiryDate, expiryDate, freetext1, and freetext2.

How the flow works

  1. After a successful replace call, your system calls:
    PUT /thr/thredd/cards/{PublicToken}/complete-replacement

  2. The request can specify what should move to the new card, such as balance, limits, linked child cards, or expiry handling.

  3. Payblr returns: 204 No Content

  4. Your system can then continue the journey for the replacement card, including activation using the Update Card Status endpoint when required.

Notes

Complete Card Replacement is a follow-up step, not the initial replacement step. The endpoint is designed for transferring selected data to the replacement card after the replacement has already been created.