API Explorer
Client Login

Card Renewal

post
https://uat.banking.live:55555/ppws/api/pws/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.

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.

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.

This endpoint does not provide idempotent retries. After a timeout, HTTP 500, or a lost response, do not automatically submit another renewal using either the same identifier or a new one. Check the card details and status to reconcile the original request. If the outcome is still uncertain, contact Paymentology support with the original identifier before resubmitting. Do not switch to V2 to repeat an operation whose outcome is still unknown.

If a request is rejected for invalid input, correct the input and submit a new request with a new identifier. For future integrations, use Card Renewal V2 for idempotent retries. For same-product physical renewal activation, follow Set Card Status V2; use the existing token and a new identifier for activation.

Body Params
string
required
length between 1 and 40

The identifier for this request. This endpoint does not provide idempotent retries. Do not automatically resend a request after a timeout or lost response, with either the same identifier or a new one. Reconcile the original outcome before making another renewal request. Use Card Renewal V2 when you need idempotent retries.

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.

int32

The network status to assign as part of renewal or replacement. 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, Banking.Live applies this status immediately to the current card and stores the same status for the pending renewal. You cannot specify separate statuses for them in this request.

Allowed values:

  • 1000 — Fully operational.
  • 1001 — Refer to issuer.
  • 1004 — Capture card.
  • 1005 — Decline all transactions.
  • 1007 — Decline all transactions.
  • 1008 — Honor with ID.

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

Banking.Live 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.

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
0 to 1

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

  • 0 ==> Inherit
  • 1 ==> Donot inheri

Default value is 0 i.e. always inherit

Responses

404

Webservices does not exist

500

Internal Server error

Updated 15 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 15 days ago

Did this page help you?