Card Issuing & Management
Card Renewal & Replacement
This page explains how your system can renew or replace cards after issuance. Renewal is not automatically triggered by Payblr when a card approaches expiration. Your system is responsible for monitoring expiration dates, determining renewal eligibility, and initiating renewal or replacement based on your business rules.
Overview
Card renewal and replacement flows are used after a card has already been issued. Renewal is typically based on expiration monitoring, while replacement may be based on cardholder request, operational need, or business rules.
Your system should determine when a card needs to be renewed or replaced, submit the applicable request to Payblr, and store the returned card reference information for future card lifecycle operations.
At a glance
Virtual renewal
A virtual card renewal is completed with a single renew request.
Physical renewal
A physical card renewal uses a two-step process: renew and then migrate.
Replacement
Replacement creates a new card for the cardholder when a card is lost, stolen, damaged, or needs to be reissued.
Complete replacement
An optional follow-up step can transfer selected data from the old card to the new replacement card.
Expiration & renewal responsibility
Cards are issued with an expiration date. When a card approaches its expiration date, the card is not automatically renewed by Payblr.
Your system is responsible for monitoring card expiration dates and determining when a card should be renewed. This decision should be based on your business rules, operational policies, cardholder eligibility, and cardholder-facing experience.
- Monitor upcoming card expiration dates.
- Define the renewal window before expiration.
- Determine whether the cardholder or card account is eligible for renewal.
- Initiate the renewal process when the card qualifies for renewal.
- Update the cardholder-facing experience, such as renewal prompts, renewal status, or confirmation messaging.
Renewal vs. replacement
Renewal
Use renewal when an existing card should continue with a refreshed lifecycle, typically around expiry handling or reissue needs.
Replacement
Use replacement when a new card must be created, such as for lost, stolen, damaged, or otherwise reissued cards.
Recommended flow
Use the following flow when renewing or replacing cards after issuance.
Monitor expiration or replacement need
Your system monitors card expiration dates or receives a replacement request through the client experience.
Determine eligibility
Your system determines whether the card is eligible for renewal or replacement based on business rules.
Renew Card or Replace Card
Your system submits Renew Card or Replace Card through the applicable Payblr API.
Confirm new card reference
Your system processes the response and stores the returned card reference for future operations.
Card Renewal & Replacement Sequence Diagram
Virtual renewal, physical renewal, and replacement sequence
User
Cardholder
System
Client Application
Platform
Payblr Program Manager API
1. Request virtual card renewal
Cardholder requests virtual card renewal through the mobile or web app.
2. Renew Card
Endpoint
Renew CardMethod
POST /program-manager/thr/cards/{publicToken}/renewClient application submits Renew Card for the virtual card. No request body is required.
3. 204 No Content
Endpoint
Renew CardPayblr returns 204 No Content when the virtual renewal completes successfully.
4. Receive renewal confirmation
Client application confirms the virtual card renewal result to the cardholder.
5. Request physical card renewal
Cardholder requests physical card renewal through the mobile or web app.
6. Renew Card
Endpoint
Renew CardMethod
POST /program-manager/thr/cards/{publicToken}/renewBody
{"renewStep":"renew"}Client application orders the renewed physical card with renewStep set to renew.
7. 204 No Content
Endpoint
Renew CardPayblr returns 204 No Content when the renewed physical card order is accepted.
8. Receive renewal confirmation
Client application confirms that the physical renewal order was accepted.
9. Confirm renewed card received
Cardholder confirms the renewed physical card was received through the mobile or web app.
10. Renew Card
Endpoint
Renew CardMethod
POST /program-manager/thr/cards/{publicToken}/renewBody
{"renewStep":"migrate"}Client application migrates to the renewed card with renewStep set to migrate.
11. 204 No Content
Endpoint
Renew CardPayblr returns 204 No Content when the migrate step completes successfully.
12. Activate renewed card
Cardholder activates the renewed card through the mobile or web app.
13. Update Card Status
Endpoint
Update Card StatusMethod
PUT /program-manager/thr/cards/{publicToken}/statusClient application activates the renewed card through Update Card Status.
14. 204 No Content
Endpoint
Update Card StatusPayblr returns 204 No Content when the card status update completes successfully.
15. Receive card status confirmation
Client application confirms the activated card status to the cardholder.
16. Request card replacement
Cardholder requests card replacement through the mobile or web app.
17. Replace Card
Endpoint
Replace CardMethod
POST /program-manager/thr/cards/{publicToken}/replaceClient application submits Replace Card for a virtual or physical reissue.
18. 200 OK
Endpoint
Replace CardPayblr returns 200 OK with the new card details, including the new publicToken.
19. Complete Card Replacement
Endpoint
Complete Card ReplacementMethod
PUT /program-manager/thr/cards/{newPublicToken}/complete-replacementOptional follow-up step that transfers selected data from the original card to the replacement card.
20. 204 No Content
Endpoint
Complete Card ReplacementPayblr returns 204 No Content when the complete replacement step succeeds.
21. Receive confirmation
Client application confirms the replacement result to the cardholder.
Virtual card renewal
Cardholder requests renewal
The cardholder requests virtual card renewal through your mobile or web application.
Send renew request
POST /program-manager/thr/cards/{publicToken}/renewReceive response
Payblr returns 204 No Content when the renewal request completes successfully.
Confirm renewal
Your system confirms that the renewal request completed successfully.
Physical card renewal
Cardholder requests renewal
The cardholder requests physical card renewal through your mobile or web application.
Order renewed physical card
POST /program-manager/thr/cards/{publicToken}/renew{"renewStep":"renew"}Renew request accepted
Payblr returns 204 No Content. This orders the renewed physical card.
Migrate after receipt
After the cardholder receives the renewed card, your system calls the renew endpoint again.
POST /program-manager/thr/cards/{publicToken}/renew{"renewStep":"migrate"}Migration accepted
Payblr returns 204 No Content when the migration step completes successfully.
Activate renewed card
Your system activates the renewed card using the Card Status Management endpoint when required.
Card replacement
Cardholder requests replacement
The cardholder requests card replacement through your mobile or web application.
Send replacement request
POST /program-manager/thr/cards/{publicToken}/replaceReceive new card details
Payblr returns 200 OK with the new card details, including the new publicToken.
Confirm replacement
Your system confirms the replacement request to the cardholder.
Complete card replacement
Follow-up step
Complete Card Replacement is optional and is used after the replacement card has already been created.
Endpoint
PUT /program-manager/thr/cards/{publicToken}/complete-replacementTransfer options
The request can specify whether to move balance, limit accumulators, child cards, expiry date, or other supported replacement data.
Successful response
Payblr returns 204 No Content when the complete replacement step succeeds.
API details
| API step | Method | Endpoint | Purpose |
|---|---|---|---|
| Renew card | POST | /program-manager/thr/cards/{publicToken}/renew | Renews a virtual card or starts the physical renewal process. |
| Replace card | POST | /program-manager/thr/cards/{publicToken}/replace | Creates a replacement card and returns the new card details. |
| Complete card replacement | PUT | /program-manager/thr/cards/{publicToken}/complete-replacement | Transfers selected data from the original card to the replacement card after replacement has been created. |
| Update card status | PUT | /program-manager/thr/cards/{publicToken}/status | Used to activate renewed or replacement cards when activation is required. |
Response summary
| Flow | Expected response | Notes |
|---|---|---|
| Virtual renewal | 204 No Content | Successful virtual renewal returns no response body. |
| Physical renewal — renew step | 204 No Content | Orders the renewed physical card. |
| Physical renewal — migrate step | 204 No Content | Migrates the cardholder to the renewed physical card after receipt. |
| Replacement | 200 OK | Returns new card details such as publicToken, customerReference, maskedPan, and expiry information. |
| Complete replacement | 204 No Content | Confirms that the selected replacement transfer options were processed successfully. |
Implementation notes
Before implementing renewal or replacement, define the business rules that determine when a card is eligible and which flow should be triggered.
- Payblr does not automatically renew cards when they approach expiration.
- Your system owns the renewal policy, renewal timing, eligibility rules, and cardholder-facing renewal experience.
- Virtual renewal is a single request and does not require a request body.
- Physical renewal is a two-step process: first renew, then migrate after the cardholder receives the renewed card.
- Physical renewal ultimately requires the card to be activated using the card status endpoint.
- Replacement creates a new card and can be used for lost, stolen, damaged, or otherwise reissued cards.
- 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.
- If the original card is reported lost or stolen, update the old card to status 41 before completing the replacement journey.
- When setting a card to lost, remove the validityDate field from the request body.
- Complete Card Replacement is a follow-up step, not the initial replacement step.
Monitor expiration dates
Renewal eligibility must be determined by your system. Payblr does not automatically start the renewal process when a card approaches expiration.
Keep card references linked
Link previous and new card references correctly so your team can support cardholder lifecycle operations and troubleshooting.
Next steps
After implementing renewal and replacement, continue with authorizations or other integration guides needed for your program.