Convert a Virtual Card to a Physical Card

Outcome

Use this guide to convert an existing virtual card into a physical card through PayAPI.

The conversion uses the existing Paymentology public card token. It is not a new-card issuance flow: do not create a new customer, account, or card immediately before conversion. The converted card then enters the configured manufacturing and fulfilment process.

Who this is for

Audience	Responsibility
Backend Engineer	Identifies the existing virtual card, submits the conversion request, persists the result, and implements idempotency and reconciliation.
Product Manager	Confirms physical-conversion eligibility, cardholder experience, activation policy, and replacement/renewal boundaries.
Operations and Fulfilment Team	Confirms manufacturer, card artwork, personalisation, carrier, delivery, file-schedule, and support arrangements.

Overview

Prerequisites

Before converting a card, the following program-level configuration is enabled in cooperation with Paymentology:

Prerequisite	Description
Client and API access	A valid `client_id` and permission to call the conversion endpoint. The configuration is done during the onboarding in cooperation the Paymentology Implementation team.
Existing virtual card	A virtual card already issued to the client, identified by its public card `token`.
Existing customer and account	The virtual card’s customer and account should already exist and be linked to the card. Do not create duplicates for conversion.
Physical conversion entitlement	The program and target environment must support virtual-to-physical conversion.
Physical fulfilment configuration	Manufacturer, card artwork, personalisation, carrier, envelope, inserts, delivery, and manufacturer-file arrangements must be agreed.
Conversion status policy	An agreed policy for the card’s status and transaction behaviour before, during, and after physical fulfilment.

The conversion request does not accept crd_prdct_id. Do not assume it can select a different card product during conversion; confirm the configured eligibility in the target environment.

Recommended conversion flow

Identify the virtual card

Retrieve the existing public card token from the virtual-card issuance response or your card-management record.

The public token identifies the card to be converted. It is not the PAN and is not a digital-wallet token.

Before conversion, validate that:

The card belongs to the intended customer and program.
The card is eligible for conversion.
The physical-card manufacturer and fulfilment design are ready.
The client has no unresolved conversion attempt for the same card.

Do not create a second customer, account, or card as a workaround for conversion.

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.

Convert the virtual card to physical

API Reference: Card Conversion V2

Required inputs:

Field	Value / purpose
`client_id`	Your program client ID
`api_call_unique_identifier`	Idempotency identifier for this conversion attempt
`token`	The existing virtual card’s public token
`image_name`	Send a configured image name and validate the target-environment outcome. The Java model applies a maximum length validation but does not independently reject an empty value.

Conditionally mandatory inputs:

The API model marks the following fields optional. They become mandatory when required by the selected manufacturer, delivery method, physical-card design, or operational policy.

Condition	Field	Value / purpose
The program uses a non-default manufacturer	`card_manuf_id`	Selects the configured manufacturer.
The physical-card design requires a printer reference	`product_ref`	Identifies the physical-card design used by the printer.
The card must have an embossed name	`emboss_name`	Supplies the name used for the physical-card design.
Delivery requires an explicit recipient and address	Relevant `del_*` fields, `del_method`, `del_region`, and optionally `del_code`	Identifies the delivery recipient, address, contact details, and delivery method.
A purchaser receives the card on behalf of the cardholder	`pur_cust_type: 1` and the relevant `pur_*` fields	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.
Multiple cards share one delivery address	`bulk_delv_add_code` and consistent delivery information	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.
Packaging is selected per card	`carrier_type`, `carrier_insrt1`, `carrier_insrt2`, `carrier_lang`, `envelope_ref`	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. The fields tell the physical-card fulfilment process which configured packaging components to use. Their allowed values are program - and manufacturer-specific.
Additional personalisation	`ext_line1`, `ext_line2`, `custom_1`, `emboss_line4`	These optional fields, `ext_line1`, `ext_line2`, `custom_1`, `emboss_line4`, carry additional physical-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 program requires a specific expiry or fulfilment instruction	`exp_date`, `crd_instr`, `fulfil1`, `fulfil2`	Supplies program-specific physical-card or fulfilment data.

The API response returns the converted card’s identifiers, including the supplied public token and associated account ID. Treat PAN, CVV, card image, and response data as sensitive.

Reconcile the result and confirm manufacturing processing

Store the response and associate it with your conversion business reference and api_call_unique_identifier.

Confirm that:

The response public token is the expected original card public token.
The linked account ID is the expected account.
The card enters the agreed manufacturer and fulfilment process.
The generated manufacturer file contains the expected personalisation, packaging, and delivery details.

The API response does not prove that the card was physically manufactured, dispatched, or delivered.

No customer or account creation in this journey

Virtual-to-physical conversion is not an account-onboarding flow.

Record	Required before conversion?	Created by conversion?
Customer	Yes; already associated with the virtual card	No new customer is created by the API layer
Account	Yes; already linked to the virtual card	No new account is created by the API layer
Virtual card	Yes; identified by the public `token`	Converted rather than replaced by a newly issued card
Card product	Already configured	Not selected or created by this endpoint
Delivery and purchaser data	Optional, depending on fulfilment design	The procedures return delivery/purchaser IDs; exact create-versus-update behaviour must be confirmed in UAT
Manufacturer-file output	Required operational outcome	Validate with the configured manufacturer
Digital-wallet token	Not required	Not created by this journey

Set card status after conversion

The conversion request does not accept status_nwk and does not call Set Card Status.

If the program requires a status change after delivery or cardholder verification, call Set Card Status separately.

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 request
`status_nwk`	Target status, for example `1000` for fully operational More information about the card statuses is available at Card status.
`token`	The converted card’s public token

Conversion does not prove activation, blocking, or continued transaction usability. Confirm the card’s status and run the agreed controlled authorisation test before relying on the physical card.

What is changed by conversion

Record	Changed by conversion?
Existing card	Yes; the existing virtual card is converted to physical-card form.
Public card token	No new public token is created; the supplied public token is returned.
Customer	No new customer is created.
Account	No new account is created; the associated account ID is returned.
Delivery and purchaser records	Procedure behaviour is environment-dependent; validate the resulting IDs and records in UAT.
Manufacturer output	Expected operational outcome; validate the actual file, personalisation, and delivery process.
Card status	Card is deactivated, once the physical card is received, it needs to be re-activated.
Digital-wallet token	Not created or proven to be updated by this journey.

Important considerations

This is a conversion, not physical-card issuance, replacement, or renewal.
Do not issue a second physical card through Create Card when the intended outcome is conversion of the existing virtual card.
The conversion endpoint uses the existing public card token; do not confuse it with PAN or a wallet/network token.
The conversion endpoint is idempotent. Persist api_call_unique_identifier, business reference, request payload fingerprint, and response before retrying.
A timeout does not prove that conversion failed. Reconcile the original request before retrying.
Do not retry a conversion using a new business request or identifier without confirming whether manufacturing records were already created.
The conversion endpoint does not prove the card’s resulting status, transaction continuity, or delivery outcome. Validate these separately.
Treat PAN, CVV, card images, personalisation data, delivery addresses, and contact details as sensitive data.

Testing

Test case	Expected result
Happy path: eligible virtual card	Conversion succeeds and returns the existing public card `token` and linked account ID.
Customer and account continuity	The intended customer and account remain associated with the converted card.
Manufacturer routing	The converted card enters the expected UAT manufacturer-file or fulfilment process.
Physical personalisation	The agreed card artwork, embossing, custom fields, carrier, inserts, envelope, and language appear correctly in manufacturer test output.
Delivery and purchaser data	The agreed recipient, address, and delivery-grouping data are correct.
Invalid public token or unauthorised client	The request fails clearly and no unintended fulfilment record is created.
Duplicate submission	Repeating the same conversion request with the same idempotency identifier does not create an unintended second conversion outcome.
Timeout and reconciliation	The client can determine whether the original conversion succeeded before retrying.
Status validation	Card status is checked before and after conversion; any change follows the agreed status policy.
Controlled authorisation	The agreed test proves actual transaction behaviour after conversion; do not infer it from the conversion response.
Sensitive-data handling	PAN, CVV, images, personalisation, address, and contact details are absent from unsafe logs, monitoring traces, analytics, and support tickets.

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.

For an uncertain or retryable conversion attempt, resend the identical payload with the same api_call_unique_identifier. Do not create a new identifier until you have reconciled whether conversion, delivery-record creation, or manufacturer processing has already started.

Retry automatically

Error ID	Error description	Automatic retry?	Required retry behaviour
No response	No PayAPI response received	Yes	Retry the same payload and identifier after backoff. Do not alter the delivery, purchaser, manufacturer, or personalisation inputs.
`1066`	`Original request still processing. Please try again later.`	Yes, after waiting	Do not send a parallel conversion request. Wait, then resend the unchanged request with the same identifier.
`987`	`We are temporarily unable to handle the request. Please try again later.`	Yes	Use bounded retry with the same payload and identifier. Reconcile after retry exhaustion.
`988`	`Error executing Request. Contact Paymentology for support`	Yes	Use bounded retry with the same payload and identifier. Escalate repeated failures.
`989`	`Error executing Request. Contact Paymentology for support`	Yes	Perform a controlled retry with the same payload and identifier. Reconcile repeated failures.
`1034`	`Failed to create card,please contact the paymentology support`	Yes, controlled	This generic failure is allow-listed for V2 reprocessing. Retry the identical conversion request once, then investigate and escalate if it persists.

Do not retry automatically

Error ID	Error description	Automatic retry?	Required action
`995`	`model Validation Failed`	No	Correct missing or invalid request fields. The public token is mandatory and must be a positive number; delivery, purchaser, carrier, and personalisation fields must meet their defined formats and lengths.
`990`	`The client_id is invalid! Please provide a valid client id`	No	Correct the client ID or target-environment configuration.
`993`	`api_call_unique_identifier already been used!`	No	Reconcile the original conversion. Create a new identifier only for a genuinely new conversion attempt.
`994`	`The token is invalid !`	No	Correct the existing public card token and confirm it belongs to the client. Do not substitute a PAN, account ID, or wallet token.
`996`	`Permission denied ! The client does not have access to this web service. Contact Paymentology`	No	Correct endpoint entitlement or client access in the target environment.
`997`	Description varies; for example, `Token Details Not Found.` or `Config not available for token`	No	Correct the missing card, product, account, configuration, or relationship identified by `error_desc`.
`1012`	`The manufacturer id is not available in repository`	No	Correct the configured or supplied `card_manuf_id`.
`1013`	`The manufacturer id is not associated with the client id`	No	Select a manufacturer enabled for the client.
`1016`	`Customer stack is empty !`	No	Correct the relevant downstream card or customer configuration. This error is covered by conversion tests and is not in the conversion endpoint’s retry allow-list.
`1017`	`card image data is not configured`	No	Correct the image configuration or `image_name` before reattempting conversion.
`1021`	`Inserting delivery details failed during physical card create`	No automatic retry	Verify `del_*` inputs, delivery method, carrier configuration, and agreed physical-personalisation design. Reconcile before submitting another request.
`1022`	`Inserting purchaser details failed during physical card create`	No automatic retry	Verify `pur_*` inputs and `pur_cust_type`. Reconcile before submitting another request.
`1025`	`The card is physical. Use virtual card for card conversion`	No	The source card is already physical and cannot be converted again. Retrieve the card form and stop the conversion flow.
`1028`	`Weak cvv computed. Change expiry and resend request again`	No	Change the expiry input as instructed, then submit a new conversion request.
`1035`	`Failed to create card image ,please contact the paymentology support`	No automatic retry	Verify image and product configuration, then escalate persistent failures.
`1036`	`Failed to encrypt card file`	No automatic retry	Reconcile card form and manufacturer-file state, then escalate to Paymentology Support.
`1038`	`Failed to upload into Sftp folder`	No automatic retry	Reconcile whether conversion and manufacturer output occurred. Treat this as a fulfilment-processing incident and escalate.

Related APIs

Convert virtual to physical: Card Conversion V2
Set card status: Set Card Status V2
Create virtual card: Create card V2
Create physical card: Create card V2