Card renewal and replacement

This guide describes how the card renewal and card replacement process works on Lume.

Let's start with the 2 options we have

• Replacement: (new pan + new token + new expiry generated)
• Renew: (old pan + old token + new expiry generated)

How this is translated in the Card renew/replace API endpoint, is by the card_action field

• "card_action": 1 : Replacement (new pan + new token + new expiry generated)
• "card_action": 2: Renew (old pan + old token + new expiry generated)

Renewing a physical card

This flow retains the PAN and token. Use card_action: 2, keep the same card product, and renew a physical card as a physical card. The existing expiry remains in use until renewal activation.

1. Call Card Renewal V2 with card_action: 2, card_type: 1, and status_nwk: 1000. Omitting status_nwk also applies 1000; it does not preserve the previous status. Omit tok_flags to retain the current flags, or supply the complete 32-character value to replace them. Reuse the existing delivery details or provide overrides as described in the endpoint's Delivery details for same-product physical renewal section. The current card remains subject to its existing expiry and other authorization checks.
2. After renewal succeeds and the cardholder receives the renewed card, call Set Card Status V2 with the same token, action: 2, and status_nwk: "1000". This applies the stored renewal expiry and status. The activation request must include a valid status_nwk for validation; its "1000" value does not override the saved renewal status.
3. If you need a different status after activation, send a separate Set Card Status V2 request with action: 1 and the desired status_nwk.

The renewal request applies one status to both the current card and the pending renewal. Activation applies the status stored during renewal, even if its request supplies a different value.

If renewal was submitted with status 1005

Renewal with status_nwk: 1005 blocks the current card and stores 1005 for the renewal. To restore the current card before activation, use Set Card Status V2 with action: 1 and status_nwk: "1000"; this does not apply the new expiry or change the stored renewal status.

When ready, activate with action: 2. Activation applies the new expiry and restores the saved status, 1005. After activation succeeds, send a separate action: 1 request with status_nwk: "1000" to make the renewed card operational. If activation has already succeeded and the card is still at 1005, only that separate status-change request is needed.

Use a new api_call_unique_identifier for each separate operation. When retrying the same V2 operation after a timeout, reuse its identifier and unchanged body. Follow the endpoint's Results and retries instructions before continuing; HTTP 200 alone is not confirmation of success.

Replacing a card

With card_action: 1, the response contains a new PAN, token, and expiry. The replacement request does not block the old card or change its network status. The old card remains subject to its existing status, expiry, and authorization checks.

If the old card must stop working, make a separate Set Card Status V2 request using the old token, action: 1, and status_nwk: "1005" (decline all transactions). Confirm that request succeeded. You can do this before replacement when immediate blocking is needed; do not use a void status before replacement, because void cards cannot be replaced.

To keep the replacement blocked until receipt, create it with status_nwk: 1005. After successful replacement and receipt, activate the replacement using the new token returned in body.token, action: 1, and status_nwk: "1000". This is a normal status change. Use a new identifier for each separate operation and follow each endpoint's retry instructions.

Renewal and replacement tips

• If you require the new card to be active only for e-commerce usage, then:
  1. "status_nwk": should be set to 1000 and;
  2. tok_flags uses 32 characters counted from the left, starting at position 1. For example, "00001000000000000000000000000000" enables only position 5, which declines transactions other than e-commerce. Preserve any other required flags when setting this value.
• You should not set old card status_nwk to 1199 IF you wish to renew/replace. If the old card has a status of 1199, no renewal or replacement can occur.
• When a card expires, Paymentology does not change the card status to expired. The card will be inactive due to its expiry which directly means that no authorisation or transaction will take place. Hence it is the client's responsibility to update the card status as you desire.