API Reference
  1. CARD LIFECYCLE
  2. Card issuance

Card Renewal V2

post
https://api.uat.paymentology.com/ppws/api/pws/v2/pws_card_renewal/

Renews or replaces a card. Use card_action=1 for a replacement with a new PAN, token, and expiry. Use card_action=2 with the same card product to renew with the existing PAN and token and a new expiry.

You can optionally provide a reason for renewal or replacement.

Recipes
💳
Renew a card
Open Recipe
💳
Replace a card
Open Recipe

Renew a physical card with the same PAN and token

This flow applies when you use card_action=2, keep the same card product, and renew a physical card as a physical card. The renewal retains the PAN and public token. Lume stores the new expiry for activation and keeps the current expiry until you activate the renewal.

The renewal request applies status_nwk immediately to the current card and stores the same status for the pending renewal. You cannot choose separate statuses for them in this request. Omitting status_nwk applies the default, 1000; it does not preserve the current status.

  1. To keep an otherwise usable card operational while renewal is pending, send status_nwk: 1000 or omit the field. Other authorization checks and the current expiry still apply.
  2. When the renewed physical card is ready to activate, call Set Card Status V2 with the same token, action: 2, and status_nwk: "1000". This applies the new expiry and the status stored during renewal. 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, make a separate Set Card Status V2 request with action: 1 and the desired status_nwk. Use a new api_call_unique_identifier for each separate operation.

If you renewed with status 1005

A renewal with status_nwk: 1005 blocks the current card and also stores 1005 for the pending renewal. Sending status_nwk: "1000" with action: 2 does not override that stored status when the renewal is activated.

For the recovery sequence, see Change status before or after renewal activation.

Replace 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 the retry instructions below.

Delivery details for same-product physical renewal

Before renewal, ensure the existing card has the correct manufacturer, delivery destination, and fulfillment settings for your card program. If they are already correct, omit delivery and fulfillment overrides. A successful API response confirms renewal processing; it does not confirm dispatch or delivery.

For this flow, omission retains the existing del_method, delivery name, address, contact details, card_manuf_id, carrier_type, carrier inserts and language, envelope reference, bulk delivery address code, and fulfillment text. To change them, supply the relevant fields. Omit unchanged fields rather than sending empty strings: empty strings can clear address and contact values. Empty delivery first or last names retain the existing name.

If the card has no delivery-address record, provide a nonempty del_addr1 or del_addr2 to create one, together with the recipient name and complete postal address needed by your configured delivery service. The API does not enforce a universal set of mandatory postal fields. Use your existing card-program fulfillment requirements for country, postal code, delivery method, manufacturer codes, and packaging; these are not interchangeable across manufacturers. The API does not create a delivery address when both address lines are omitted or empty.

The following request shape renews an existing physical card with its existing fulfillment details. Replace the placeholders with your own values; client_id and token are integers. Set image_name to your configured template name. This example requests JSON card details (image_delivery: 3), hides PAN and CVV in that response (xml_fields: "00111"), and includes the required image selection fields. Authentication is also required.

{
  "api_call_unique_identifier": "<new unique identifier>",
  "client_id": 123456,
  "token": 123456789,
  "image_delivery": 3,
  "image_fields": "00000",
  "image_name": "<configured template name>",
  "xml_fields": "00111",
  "card_action": 2,
  "card_type": 1,
  "status_nwk": 1000
}

Results and retries

Treat header.error_id: 0 as success. HTTP 200 alone does not confirm that the operation succeeded. If header.error_id is nonzero, stop the dependent call sequence and inspect header.error_desc before deciding whether to retry or correct the request.

After a timeout, HTTP 500, or a lost response, retry the same operation at the same endpoint with the same api_call_unique_identifier and unchanged request body. Keep the original request so that optional fields and values remain unchanged. Use delayed, bounded retries; do not start activation or another dependent operation until the previous operation has a confirmed successful result.

If the original renewal succeeded, a duplicate does not renew the card again. Lume uses the recorded renewal details to rebuild the response; it does not guarantee a byte-for-byte copy of the original response.

  • 1066: the original request is still processing. Wait and retry the unchanged request with the same identifier. Do not use a new identifier to bypass this response.
  • 993: the identifier has already been used with different request data. Restore the original body if you are retrying it. For a genuinely different operation, use a new identifier after resolving the original outcome.
  • If the recorded operation failed with 996, 987, 988, 989, 1015, 1035, or 1066, an identical retry is eligible for reprocessing. Retry with the same identifier and body after a delay; reprocessing does not guarantee success. The processing-pending rule above takes precedence for 1066.
  • Other recorded failures are returned again for an identical duplicate. Do not keep retrying them unchanged. Correct invalid input and use a new identifier for the corrected request only when the original outcome is resolved. If the error is unexplained or persists, stop and contact Paymentology support with the identifier.

After confirmed renewal success, activation is a separate operation and needs a new identifier. If a successful renewal response reports is_3ds_enrolled: false, handle the enrollment failure separately; do not repeat renewal with a new identifier solely to retry 3DS enrollment.

Body Params
string
required
length between 1 and 40

The identifier for this operation. Use a new value for each separate renewal, activation, or status change. To retry the same operation after a timeout or lost response, reuse its identifier and send the same request body to the same endpoint. Do not reuse an identifier with changed request data. See the page's retry instructions for duplicate and failed-request behavior.

int32
required
1 to 2

card action :

  • 1==>Replacement (new pan + new token + new expiry generated)
  • 2==> Renew (old pan + old token + new expiry generated)
int32
required
≥ 1

Unique identifier for the client which Paymentology will provide at outset

int32
required
1 to 4

How to deliver image back to client. Example :

  • 1==> Image in plain base64, encrypted pan, cvv, token, expiry, and emboss_name).
  • 2 ==> Image in byte encrypted, encrypted pan, cvv, token, expiry, and emboss_name.
  • 3 ==> Data details JSON (encrypted pan, cvv, token, expiry, and emboss_name but no image.
  • 4 ==> Image in byte encrypted, masked pan back, cvv, token, expiry, and emboss_name.
string
required
length between 5 and 5
^[0-1]{5}$

Show or hide pan, cvv, expiry, token, and emboss_name in response image. 1 means show and 0 means hide

  • 1 — pan
  • 2 — cvv
  • 3 — expiry
  • 4 — emboss_name
  • 5 — token

EG: 00111 (Hide pan and cvv but show expiry, token, and emboss_name).

string
required
length between 0 and 50

Image template name for the card to be generated. This field is case sensitive. card image has to be populated as configured in PayControl.

int64
required
≥ 1

Public token for the card

string
required
length between 5 and 5
^[0-1]{5}$

Show or hide pan, cvv, expiry, token, and emboss_name in response json. 1 means show and 0 means hide

  • 1 — pan
  • 2 — cvv
  • 3 — expiry
  • 4 — token
  • 5 — emboss_name

EG: 00111 (Hide pan and cvv but show expiry, token, and emboss_name).

string
length between 0 and 50

User Id of the Customer who triggered the API request.

string
length between 0 and 200

Remarks for API request

string
length between 0 and 255

The optional reason for renewal or replacement, up to 255 characters. If omitted, no reason is supplied with the request.

string
length between 0 and 50

Future field 1RFU

string
length between 0 and 50

Future field 2RFU

int32

Reserved metadata used to reconstruct a previously completed response. Omit this field from requests; it is not a client control for renewal or replacement. Omitting it does not change the operation.

string

Reserved metadata used to reconstruct a previously completed response. Omit this field from requests; it is not a client control for renewal or replacement. Omitting it does not change the operation.

string

Reserved metadata used to reconstruct a previously completed response. Omit this field from requests; it is not a client control for renewal or replacement. Omitting it does not change the operation.

int32

The network status to assign to the card. You do not need to call pws_set_card_status first to apply this value. For a physical-card renewal with card_action=2 and an unchanged card product, Lume applies this status immediately to the current card and stores the same status for the pending renewal. You cannot specify separate statuses for the current card and the pending renewal in this request.

Default: 1000. Omitting this field applies 1000; it does not preserve the current status. To keep an otherwise usable card operational while the renewal is pending, specify 1000 or omit this field. Specifying 1005 blocks the current card and stores 1005 for the renewal.

Allowed values:

  • 1000 — Fully operational.
  • 1001 — Refer to issuer.
  • 1004 — Capture card.
  • 1005 — Decline all transactions.
  • 1007 — Decline all transactions.
  • 1008 — Honor with ID.
  • 1041 — Lost card; capture card.
  • 1043 — Stolen card; capture card.
  • 1054 — Expired card; report expiry.

Values outside this list fail request validation.

Lume checks the existing card separately. Existing statuses 1005, 1006, 1007, 1041, 1043, 1054, 1154, and 1062 do not by themselves prevent renewal; other renewal checks still apply. You do not need to set one of these statuses before renewal. This list describes existing-card eligibility, not additional allowed values for this request.

An existing card with status 1009 or 1199 is void and cannot be renewed or replaced. Existing statuses 1010 (due payment block) and 1011 (KYC/AML hold) also prevent renewal or replacement. The requested status_nwk cannot override these restrictions.

When you activate the pending renewal with v2_pws_set_card_status and action=2, Lume applies the status stored during renewal instead of the status supplied in that activation request. To change it, make a separate status request with action=1 after activation.

DE39 is the payment network response-code field; the listed values explain the authorization response associated with each status.

string
^[0-1]{32}$

The card control flags, encoded as exactly 32 characters containing only 0 and 1. Positions are one-based, counted from left to right: position 1 is the leftmost character. 1 enables a flag; 0 disables it. Omit this field to retain the existing card's flags. A supplied value replaces all 32 flags; an all-zero value clears them.

For example, 00001000000000000000000000000000 sets only position 5 (decline transactions other than e-commerce). Other card status and authorization checks still apply. To retain other restrictions, preserve their positions in the supplied value.

  • 3 — Send card bal in De54 in next auth
  • 4 — Send pin unblock to card
  • 5 — Set card to decline all tranasaction except ecommerce
  • 6 — Set card to decline all Contactless transaction
  • 9 — Set card to decline all Ecommerce
  • 10 — Set card to decline all ATM
  • 11 — Set card to decline Bal enquiry over auth
  • 12 — Set card to decline cash back txns
  • 14 — Set card to decline Auth credit pur/refund (DE3_1=20)
  • 19 — Set card to decline credit payment (DE3_1=28)
  • 20 — Set card to decline non base currency txn
  • 21 — Set card to decline all account enq (de61_7=8)
  • 22 — Set card to decline card not present txns
  • 23 — Set card to decline Cardholder not present txns
  • 24 — Set card to decline failover to mag at emv capable atm
  • 25 — Set card to decline mag at atm
  • 26 — Alow if fallback chp->mag at chp capable pos DE22_1=80
  • 27 — Allow if de22_1=02 & De48_88 =Y
  • 28 — Set card to approve if AVS match fails
  • 29 — Set card to decline Recurring transaction

In the list, DE means a payment-message data element: DE54 carries balance information, DE3 identifies the transaction type, DE61 carries point-of-sale information, DE22 identifies the card-entry method, and DE48 carries additional transaction data. ATM means automated teller machine; POS means point of sale; AVS means address verification service. MDES and VTS are Mastercard and Visa digital token services. EMV refers to chip-card payment standards.

int32

Card product id.

1. If no card product id sent, then default value set at card is taken.

2. If card product id is sent different from one set during card create, it will act as replacement i.e. new pan, new token since bin range value will be different.

string
\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}:\d{2}

Expiry date during renewal/replacement. Accepted format yyyy-mm-dd hh:mm:ss

If client send expiry in request, same is assigned during replacement/renewal.

If expiry date is not send by client, automatic expiry date is computed from product level. This applies to both renewal and replacement.

Note : There could be a scenario where weak cvv is computed during renewal/replacement. Example 111, 222

1. Replacement(new pan, new token, new expiry)

  • If weak cvv is computed as per pan selected, system will internally discard this pan and look for new pan such that new cvv is computed.

2. Renewal (same pan, same token, new expiry). Since pan should not be changed during renewal, so we change expiry such that new cvv is computed.

  • If client send expiry in request and weak cvv is computed, then below response will be sent to client.
    weakCvv (1028, Weak cvv computed. Change expiry and resend request again)

  • If client do not send expiry in request, then automatic expiry is computed from product level. Now if a weak cvv is computed, then system will internally increase 1 month to automatic computed expiry and process request again
string

ISO 639-1 two-letter language code.

3ds_challenge_methods
array of objects
3ds_challenge_methods
string

Unique identifier for the challenge profile. 3ds_challenge_methods will be ignored if this value is not null.

int32
1 to 2
  • 1 = Physical card
  • 2 = Virtual card
string
length between 0 and 30

Emboss name.

string
length between 0 and 50

Customer reference

string
length between 0 and 10

delivery Title.

string
length between 0 and 50

delivery First Name.

string
length between 0 and 50

delivery Last Name.

string
length between 0 and 100

Delivery Address 1

string
length between 0 and 100

Delivery Address 2

string
length between 0 and 15

delivery Postal Code.

string
length between 0 and 50

delivery City.

string
length between 0 and 50

delivery Country.

string
length between 0 and 60

delivery Email.

string
length between 0 and 20

delivery Mobile. phone number format i.e 00 (contry code ) phone number or + (country code) phone number.

string

delivery Pass Code.

int32

delivery method for card :

  • 0 – Standard mail
  • 1 – Registered mail
  • 2 – Direct delivery (courier) (reserved for future use)

For same-product renewal, omission retains the existing delivery method.

int32

delivery account Number.

string
length between 0 and 50

delivery Holder Region.

string
length between 0 and 10

Purchaser Title.

string
length between 0 and 50

Purchaser First Name.

string
length between 0 and 50

Purchaser Last Name.

string
length between 0 and 100

Purchaser Address 1.

string
length between 0 and 100

Purchaser Address 2.

string
length between 0 and 15

Purchaser Postal Code.

string
length between 0 and 50

Purchaser City.

string
length between 0 and 50

Purchaser Country.

string
length between 0 and 60

Purchaser Email.

string
length between 0 and 20

Purchaser Mobile,phone number format i.e 00 (contry code ) phone number or + (country code) phone number.

int32

Purchaser account Number

string
length between 0 and 10

Purchaser pass code (can be stored against card for customer authentication [i.e. activation stage], or Paymentology can generate)

string
length between 0 and 50

Purchaser region.

int32

Purchaser customer type. This will determine the single delivery of a card to specific address

  • 0 => Card will be delivered to card holder address
  • 1 => Card will be delivered to purchaser address
int32

Bulk delivery address code.
It can be any value set by bank themselves. 

Bank can use any value to group the cards that will be delivered to a specific address. This value is the bulk_delv_add_code.
So if a card has bulk_delv_add_code = 10505, then this code is used to identify the delivery address inside <BULK_DEL> tag in perso file xml.

 

Example : 
If a client creates a batch of 5 cards and need to deliver to a single address.
Then bank can agree a value for bulk_delv_add_code other than 0 and put same delivery address for all cards. This will deliver cards to single address in bulk inside <BULK_DEL> tag in perso file xml.

 

Note: If client need to send 5 cards to AddressX and 6 cards to AddressY, then client need to set different bulk_delv_add_code for two batch of cards.
Like for 5 cards set bulk_delv_add_code = X and for 6 cards set bulk_delv_add_code = Y. This will distinguish separate bulk delivery address for different sets of cards.


If client sets bulk_delv_add_code same for 5 cards but different delivery address for each card, then all cards will be delivered to delivery address of first created card.


If a client creates a card and need to deliver to a specific single address.
Then client can input either card holder address/details or purchaser address/ details based on pur_cust_type field. At this point client can put bulk_delv_add_code = 0 or empty/null so that it determines the card is for single delivery and address/details are populated inside <RECORD>==><CH_ADDR> tag in perso file xml

pur_cust_type

  • 0 => Card will be delivered to card holder address
  • 1 => Card will be delivered to purchaser address
int32

delivery Code, carriers with same del_code, will be grouped to be send to a specified delivery address.

int32

The configured card manufacturer ID. If supplied as a positive ID, it must identify a manufacturer configured for your client. For same-product renewal, omit this field to retain the existing manufacturer. Do not send 0 to request retention.

string

The card packaging code used by your configured manufacturer. There is no API-wide list of values. Use the code specified by your card fulfillment configuration. For same-product renewal, omit this field to retain the existing code.

int32
≤ 32767

Identifies insert 1 to be included with Carrier in Envelope

int32
≤ 32767

Identifies insert 2 to be included with Carrier in Envelope

string
length between 0 and 3

Language to be used in carrier notes and labels(iso 3166-1, character three digits).

int32
≤ 32767

Identifies envelope type

string
length between 0 and 20

Extra card text line 1, allows additional line for subjective requirements i.e. extra text in the card

string
length between 0 and 20

Extra card text line 2, allows additional line for subjective requirements i.e. extra text in the card

string
length between 0 and 255

string [ 0 .. 255 ] characters
Customer special details, i.e. QR code If custom_1 ==> 1, then we will provide : MMYY+Public Token (MMYY ->the date of card creation ). If custom_1 value other than "1" , PT will include what ever client input in the same field in create.

string
length between 0 and 35

Emboss line 4, front of card additional text i.e. private token

string
length between 0 and 50

Track 3, Mag stripe

string
length between 0 and 60

product identifier, i.e. physical card design reference used by the card printer.

string
length between 0 and 100

Unique client reference relating to order, card or customer where present should always be quoted in correspondence

int32
0 to 1

Inherit existing card rules. Based on value provide, it will either inherit existing rules or skip. 

  • 0 ==> Inherit
  • 1 ==> Donot inherit

Default value is 0 i.e. always inherit

boolean

Transfer digital tokens to new card. Digital token states will not be updated.

Responses

404

Webservices does not exist

500

Internal Server error

Updated 18 days ago

Did this page help you?
Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 18 days ago

Did this page help you?