Replace a Card

Outcome

Use this guide to replace an existing card through PayAPI while preserving the cardholder’s established customer and account context.

A replacement creates a successor card with:

A new PAN
A new public card token
A new expiry date

The source card remains the input to the lifecycle operation. After a successful response, use the returned successor token for all future card operations.

Who this is for

Audience	Responsibility
Backend Engineer	Orchestrates the lifecycle API, persists the successor public card token, and implements idempotency and reconciliation.
Product Manager	Defines eligible reasons, product choice, initial status, wallet policy, and cardholder experience.
Operations and Fulfilment Team	Confirms physical-card personalization, delivery, activation, and support procedures.

Overview

Prerequisites

Before reissuing any cards, the following program-level configuration is enabled in cooperation with Paymentology:

Prerequisite	Description
Client and API access	Valid `client_id` and entitlement to use the Card Lifecycle V2 API. The configuration is done during the onboarding in cooperation the Paymentology Implementation team.
Eligible source card	Existing public card `token` belonging to the client. Do not void the source card with `status_nwk: 1199` before this operation.
Existing customer	Customer record associated with the source card.
Existing account relationship	Source card’s account mapping. A new account is not normally required.
Target card product	Existing, eligible `crd_prdct_id`. This can be the current product or an approved alternative product.
Fulfilment configuration	Required for a physical successor: manufacturer, artwork, personalization, carrier, and delivery design.
Wallet-token policy	A documented decision on how existing digital wallet tokens should be handled.

Recommended flow

Confirm the source-card context

Retrieve and validate the source card’s public token, customer, linked account, product, current status, and any linked wallet tokens.

For a lost or stolen card, decide whether linked wallet tokens should remain usable before changing card status.

Select the successor behaviour

Decision	Required outcome
`card_action`	`1`
PAN	New
Public card `token`	New
Expiry	New
Product	Existing or approved target product
Initial status	Commonly `1005` when a physical card must remain unusable until delivery

Call Card Renewal

API Reference: Card Renewal V2

Key inputs:

Field	Value / purpose
`client_id`	Your program client ID
`api_call_unique_identifier`	Durable idempotency identifier for this business attempt
`token`	Public token of the source card
`card_action`	`1`
`reason`	Business reason recorded against the action
`crd_prdct_id`	Existing target card product
`status_nwk`	The successor card’s network-facing status, commonly`1005`until delivery. It determines how the card’s public token is treated during authorization. More information about the card statuses is available at Card status.
`tok_flags`	An optional 32-character binary string that controls card transaction behaviour Each character represents one flag position: `0` = flag inactive `1` = flag active Example: E-commerce-only card. Position 5 is set to `1`: `"tok_flags":"00001000000000000000000000000000"` More information about token flags is available at Token flags.
`exp_date`	When provided in the request, the expiry is assigned during replacement. When not provided in the request, automatic expiry date is computed from the Product during replacement.
`image_name`, `image_fields`, `image_delivery`, `xml_fields`	Card-image and sensitive-response controls
`update_digital_token`	Controls whether existing digital-wallet tokens linked to the card should be included in the card lifecycle operation. It does not create a new Apple Pay, Google Pay, VTS, or MDES token. It only applies to existing wallet tokens, and automatic processing is available only when the client uses Paymentology’s tokenization services.
`client_card_ref`	Recommended client-side business and reconciliation reference

Persist the successor public card token returned by the API. Do not continue using the source public card token for later card-management operations.

Physical personalisation and delivery

Use the Create Card request’s physical-card fields only where they are agreed for the program and supported by the selected manufacturer.

Area	Examples of relevant fields
Cardholder details i.e. the person whose name is associated with the card.	Use the `ch_` fields to describe the person who will hold and use the card. If you provide an existing `cu_id`, the Create Card contract states that the cardholder fields are not required. Use this pattern when the customer has already been created through Create Customer and you want one durable customer record to be reused across cards and accounts. If you do not provide `cu_id`, provide the cardholder details required by your program. Do not send conflicting `cu_id` and `ch_` data without agreeing which source is authoritative.
Delivery recipient and address	Use the `del_*` fields to state where and how the physical card should be delivered. These fields describe delivery logistics, not the identity of the cardholder. Use them when the delivery recipient or address differs from the cardholder, or when the manufacturer and courier process requires explicit delivery information.
Purchaser delivery	A purchaser is the person or organisation arranging the card, rather than necessarily the person who will use it. This is relevant when a company, parent, guardian, or other authorised third party requests delivery for a cardholder. `pur_cust_type` selects the address source for an individual delivery: `0` - Deliver to the cardholder address. `1` - Deliver to the purchaser address. When `pur_cust_type` is `1`, provide a complete and internally consistent `pur_*` identity and address set. When it is `0`, ensure the cardholder details are sufficient for the agreed delivery design.
Carrier and packaging	A carrier is the physical packaging that holds the card when it is sent to the recipient. It can include printed information, terms, welcome material, activation instructions, or other inserts. These fields, `carrier_type`, `carrier_insrt1`, `carrier_insrt2`, `carrier_lang`, `envelope_ref`, tell the physical-card fulfilment process which configured packaging components to use. Their allowed values are program- and manufacturer-specific.
Delivery grouping	Use `bulk_delv_add_code` when several physical cards should be delivered together to the same destination - for example, a batch of employee cards delivered to one company office. Paymentology uses this value to group delivery information in the physical-card personalisation file under the `BULK_DEL` section.
Additional personalisation	These optional fields, `ext_line1`, `ext_line2`, `custom_1`, `emboss_line4`, carry additional card personalisation data to the manufacturer file: extra text lines, custom vendor data such as QR-code content, and a fourth front-of-card emboss line. Some reserved values can automatically insert the card’s public token. Confirm the final printed placement and supported content with the configured card manufacturer.

The API creates the physical-card definition. The card is then included in the configured embossing or manufacturer-file process. File generation and dispatch frequency must be confirmed during onboarding; they are not proof of card delivery.

Wallet-token handling

A public card token is not a digital-wallet token. update_digital_token concerns existing network wallet tokens linked to the card.

Use case	Recommended approach
Existing wallet tokens should receive the new PAN	Set `update_digital_token: true`.
Lost or stolen card; wallet should stop working	Use Set Card Status V2 and apply the agreed wallet-status handling.
Physical card should be blocked while wallet remains usable	Set the physical card status according to policy and validate wallet behavior in UAT.
No wallet tokens exist	Do not treat this operation as wallet provisioning. Wallet provisioning is a separate journey.

Current implementation distinguishes replacement as a PAN-replacement update. More at: LCM

Activate a successor issued in a blocked state

After physical delivery and the program’s activation checks, use Set Card Status V2.

API reference: Set Card Status V2

Field	Value / purpose
`client_id`	Your program client ID.
`api_call_unique_identifier`	Idempotency identifier for the status-change attempt.
`token`	Successor card’s new public token.
`status_nwk`	Pass `1000` to activate the card. More information about the card statuses is available at Card status.
`action`	`1` for the normal status-change path.

For wallet-token status propagation, include update_digital_token: true only when the wallet tokens should follow the card status.

What is created or changed

Record	Replacement
Customer	Reused. Delivery or purchaser details may be updated where supplied.
Account and card-account relationship	Reused for the successor card; validate in UAT.
Card	New successor card.
PAN	New.
Public card token	New.
Expiry	New.
Card product	Reused or changed to an approved target product.
Digital wallet token	May receive a lifecycle update when enabled; no new wallet token is provisioned.

Important considerations

Use V2 and treat the request as idempotent.
Do not run concurrent attempts for the same source card.
A timeout does not prove failure. Reconcile the original request before retrying.
Do not set the source card to 1199before calling the lifecycle API.
Persist the returned successor public token before initiating follow-on status or wallet actions.
Treat PAN, CVV, card image, delivery information, and wallet-token data as sensitive.
Validate downstream product eligibility, fulfillment, and wallet behavior in the target environment before production rollout.

Testing

Test case	Expected result
Happy path	A successor card is created with a new PAN, public card token, and expiry.
Physical successor issued blocked	The successor is unusable until activation.
Existing account relationship	The successor has the expected account relationship.
Alternative approved product	The successor uses the configured target product and expected controls.
Wallet lifecycle update enabled	Existing wallet tokens receive the agreed PAN-change lifecycle treatment.
Wallet lifecycle update disabled	Wallet-token behavior follows the agreed policy and is verified in UAT.
Duplicate submission	The same idempotency identifier does not create an unintended second successor.
Timeout and retry	The client reconciles the original attempt before retrying.
Fulfillment	Manufacturer-file output, delivery data, and activation readiness match the agreed design.

Errors, retries, and request correction

Use header.error_id and header.error_desc as the primary outcome signal. Do not decide whether to retry from the HTTP status alone.

A replacement retains the existing public card token and updates the card expiry. For an uncertain or retryable replacement attempt, resend the identical payload with the same api_call_unique_identifier. Do not create a new identifier until you have reconciled whether the original renewal already completed.

Retry automatically

Error ID	Error description	Automatic retry?	Required retry behaviour
No response / timeout	No API response was received.	Yes, after reconciliation	First check whether the request completed using the original identifier. If its outcome cannot be established, retry the identical request with the same identifier. Do not submit a second request with a new identifier.
1066	Original request still processing. Please try again later.	Yes	Wait using bounded backoff, then resend the identical request with the same identifier. Do not run parallel retries.
987	We are temporarily unable to handle the request. Please try again later.	Yes	Retry the identical request using bounded backoff. Escalate if the retry limit is reached.
988	Error executing Request. Contact Paymentology for support.	Controlled	Retry once only with the same payload and identifier. If it recurs, stop and raise a support case with the request identifier and timestamp.
989	Error executing Request. Contact Paymentology for support.	Controlled	Retry once only with the same payload and identifier. If it recurs, stop and raise a support case with the request identifier and timestamp.
1035	Failed to create card image, please contact Paymentology for support.	Controlled	Retry once with the same payload and identifier. If it recurs, investigate the card-image and product configuration before retrying again.

Do not retry automatically

Error ID	Error description	Automatic retry?	Required correction
990	The client_id is invalid. Please provide a valid client id.	No	Correct the client credentials or client identifier.
993	api_call_unique_identifier already been used.	No	Reconcile the earlier request using that identifier. Do not reuse it for a different replacement request.
994	The token is invalid.	No	Correct the source card public token. Confirm that it identifies the card being replaced.
995	model Validation Failed.	No	Correct the request. Typical causes include invalid `status_nwk` or `3ds_lang` values.
996	Permission denied. The client does not have access to this web service. Contact Paymentology.	No	Correct access entitlement and credentials. The service can process a corrected re-submission, but permission failures must not be scheduled as automatic retries.
997	Description varies; for example, Token Details Not Found or Account Mapping list Not Found.	No	Correct the source-card reference or its account mapping before resubmitting.
1012	The manufacturer id is not available in repository.	No	Use a valid manufacturer configuration.
1013	The manufacturer id is not associated with the client id.	No	Correct the manufacturer-to-client configuration.
1014	The product id is not available in repository.	No	Correct the card product configuration.
1015	Source-card lifecycle eligibility failure.	No	Correct the source card’s lifecycle eligibility and state, then submit a new, deliberate request. Do not repeatedly retry an unchanged request.
1019	The card has been deactivated already.	No	Reconcile the source card’s current state and select the appropriate lifecycle action.
1021	Inserting delivery details failed during physical card create.	No	Correct delivery details or fulfilment configuration. Check whether any downstream fulfilment record was created before resubmitting.
1022	Inserting purchaser details failed during physical card create.	No	Correct purchaser details or fulfilment configuration. Check for partial downstream processing before resubmitting.
1028	Weak CVV computed. Change expiry and resend request again.	No	Change the applicable expiry value, then submit a new request.
1036	Failed to encrypt card file.	No	Escalate to Paymentology support. Do not repeatedly retry until the underlying issue is confirmed resolved.
1038	Failed to upload into SFTP folder.	No	Check fulfilment-file and SFTP configuration, then reconcile whether a file was produced before resubmitting.

Related APIs:

Set card status: Set Card Status V2
PAN Update in Wallet: Pan Update
Tokenization Lifecycle Management: LCM