---
title: "Card Renew/Replace"
method: POST
path: "/pws/v2/pws_card_renewal/"
tags: ["Card V2"]
---

# Card Renew/Replace

`POST /pws/v2/pws_card_renewal/`

This web service creates a new card and maintains a reference to the old one when one of the following actions is required :

1.  Replacement (new pan + new token + new expiry generated).
2.  Renew (old pan + old token + new expiry generated)

A reason for the replacement is also required and recorded against the renewal action.

## Request body

- CardRenewV2Model
  - `api_call_unique_identifier` string, required — Unique number that must be passed at each API request. Identifier to make each API request unique
  - `card_action` integer, required — <p>card action :</p><ul><li class="docBullet">1==&gt;Replacement (new pan + new token + new expiry generated)</li><li class="docBullet">2==&gt; Renew (old pan + old token + new expiry generated)</li></ul>
  - `client_id` integer, required — Unique identifier for the client which Paymentology will provide at outset
  - `image_delivery` integer, required — <p>How to deliver image back to client. Example :</p><ul><li class="docBullet">1==&gt; Image in plain base64, encrypted pan, cvv, token, expiry, and emboss_name).</li><li class="docBullet">2 ==&gt; Image in byte encrypted, encrypted pan, cvv, token, expiry, and emboss_name.</li><li class="docBullet">3 ==&gt; Data details JSON (encrypted pan, cvv, token, expiry, and emboss_name but no image.</li><li class="docBullet">4 ==&gt; Image in byte encrypted, masked pan back, cvv, token, expiry, and emboss_name.</li></ul>
  - `image_fields` string, required — <p>Show or hide pan, cvv, expiry, token, and emboss_name in response image. 1 means show and 0 means hide</p><table ><tbody><tr><th ><strong>Position</strong></th><th ><strong>Field</strong></th></tr><tr><td >1</td><td >pan</td></tr><tr><td >2</td><td >cvv</td></tr><tr><td >3</td><td>expiry</td></tr><tr><td >4</td><td>emboss_name</td></tr><tr><td >5</td><td>token</td></tr></tbody></table><p>EG: 00111 (Hide pan and cvv but show expiry, token, and emboss_name).</p>
  - `image_name` string, required — Image template name for the card to be generated. This field is case sensitive. card image has to be populated as configured in PayControl.
  - `token` integer, required — Public token for the card
  - `xml_fields` string, required — <p>Show or hide pan, cvv, expiry, token, and emboss_name in response json. 1 means show and 0 means hide</p><table ><tbody><tr><th ><strong>Position</strong></th><th ><strong>Field</strong></th></tr><tr><td >1</td><td >pan</td></tr><tr><td >2</td><td >cvv</td></tr><tr><td >3</td><td>expiry</td></tr><tr><td >4</td><td>token</td></tr><tr><td >5</td><td>emboss_name</td></tr></tbody></table><p>EG: 00111 (Hide pan and cvv but show expiry, token, and emboss_name).</p>
  - `user_id` string — User Id of the Customer who triggered the API request.
  - `remarks` string — Remarks for API request
  - `reason` string — Reason for renewal or replacment
  - `fulfil1` string — Future field 1RFU
  - `fulfil2` string — Future field 2RFU
  - `customerId` integer
  - `customerRef` string
  - `entryReason` string
  - `status_nwk` integer — <p>Status network :&nbsp;<br />Allowed values for renewal</p><ul><li class="docBullet">1000 : Fully operational DE39=00</li><li class="docBullet">1001 : Refer to issuer DE39=01</li><li class="docBullet">1004 : Capture card DE39=04</li><li class="docBullet">1008 : Honour with ID DE39=08</li></ul><p>Disallowed values for renewal&nbsp;<br />If a card is void i.e status_nwk = 1199 or status_nwk = 1009 then card can not be replaced/renewed.<br /> <br />We set card status_nwk into below values through pws_set_card_status web service and only process for card renewal.</p><ul><li class="docBullet">1005 : Decline all txns DE39=05</li><li class="docBullet">1006 : Inactive - pin blocked DE39=75</li><li class="docBullet">1007 : Decline all txns (Visa: DE39=12) (MC: DE39=14)</li><li class="docBullet">1041 : Lost card - capture DE39= 41</li><li class="docBullet">1043 : Stolen card - capture DE39=43</li><li class="docBullet">1054 : Expired card - report DE39=54</li><li class="docBullet">1154 : Expire card - don't inform</li><li class="docBullet">1062 : Restricted card</li></ul>
  - `tok_flags` string — <p>Flags for token to assign various tasks to the card. 0 ==>Flag inactive | 1==> Flag Active . Descriptions for each tok flag bits are given below : </p><table><thead><tr></td><td><strong>TOK_DESCRIPTION</strong></td><td><strong>BIT_POSITION</strong></td></tr></thead><tbody><tr><td title ="After every transaction, send card balance to the scheme, to allow for balance to be displayed, i.e. for ATM transactions">Send card bal in De54 in next auth</td><td>3</td></tr><tr><td title ="Should the maximum number of pin retries be exceded, then enable pin unblocking on chip card. Send to issuer to unblock">Send pin unblock to card</td><td>4</td></tr><tr><td title ="Only allow ecommerce transactions (including MDES and VTS transactions)">Set card to decline all tranasaction except ecommerce</td><td>5</td></tr><tr><td title ="Set card to decline all Contactless transaction">Set card to decline all Contactless transaction</td><td>6</td></tr><tr><td title ="Decline all ecommerce transactions (including MDES and VTS transactions)">Set card to decline all Ecommerce</td><td>9</td></tr><tr><td title ="Decline all ATM Cash withdrawal transactions">Set card to decline all ATM</td><td>10</td></tr><tr><td title ="Do not allow any balance enquiry transactions">Set card to decline Bal enquiry over auth</td><td>11</td></tr><tr><td title ="In the case of POS transactions, the cash disbursement of a portion of the transaction amount is not allowed. The merchant cannot give cash to cardholder as part of the transaction.">Set card to decline cash back txns</td><td>12</td></tr><tr><td title ="No transactions are allowed that will credit the card balance, including refunds to the card.">Set card to decline Auth credit pur/refund (DE3_1=20)</td><td>14</td></tr><tr><td title ="No payments allowed, only POS and ecommerce transactions and. i.e. MC MoneySend, credit card installments, etc">Set card to decline credit payment (DE3_1=28)</td><td>19</td></tr><tr><td title ="Only transactions in the base currency are allowed, decline any transaction in a non-base currency">Set card to decline non base currency txn</td><td>20</td></tr><tr><td title ="No account verification requests should be allowed">Set card to decline all account enq (de61_7=8)</td><td>21</td></tr><tr><td title ="Only approve transactions where the card is present. If card not present, decline transaction">Set card to decline card not present txns</td><td>22</td></tr><tr><td title ="card Where the card information is provided but neither the cardholder or the card are physically present (i.e. mail-order) decline the transaction. ">Set card to decline Cardholder not present txns</td><td>23</td></tr><tr><td title ="CATM Fallback - where a chip-card is used at chip-capable ATM, do not allow fallback to magnetic strip">Set card to decline failover to mag at emv capable atm</td><td>24</td></tr><tr><td title ="ATM Fallback - where a chip-card is used at an ATM (chip-capable or not) do not allow fallback to magnetic stripe">Set card to decline mag at atm</td><td>25</td></tr><tr><td title ="POS Fallback - where a chip-card is used at chip-capable POS, allow fallback to to magnetic strip">Alow if fallback chp->mag at chp capable pos DE22_1=80</td><td>26</td></tr><tr><td title ="POS Fallback - when the magnetic strip is used for a transaction, only allow the transaction of the entire track can be read, i.e. only PAN sent then decline transaction">Allow if de22_1=02 & De48_88 =Y</td><td>27</td></tr><tr><td title ="Set card to approve if AVS match fails">Set card to approve if AVS match fails</td><td>28</td></tr><tr><td title ="Do not allow subscription transactions, decline recurring transactions">Set card to decline Recurring transaction</td><td>29</td></tr></tbody></table>
  - `crd_prdct_id` integer — <p>Card product id.</p><p>1. If no card product id sent, then default value set at card is taken.</p><p>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.</p>
  - `exp_date` string — <p>Expiry date during renewal/replacement. Accepted format yyyy-mm-dd hh:mm:ss<br /><br />If client send expiry in request, same is assigned during replacement/renewal.</p><p>If expiry date is not send by client, automatic expiry date is computed from product level. This applies to both renewal and replacement.</p><p>Note : There could be a scenario where weak cvv is computed during renewal/replacement. Example 111, 222</p><p>1. Replacement(new pan, new token, new expiry)</p><ul><li>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.</li></ul><p>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.</p><ul><li>If client send expiry in request and weak cvv is computed, then below response will be sent to client.<br /><span style="color: #333399;"><strong>weakCvv (1028, Weak cvv computed. Change expiry and resend request again)</strong></span><br /><br /></li><li>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</li></ul>
  - `3ds_lang` string — ISO 639-1 two-letter language code.
  - `3ds_challenge_methods` Challenge3DS[]
    - `ids` string[] — list of challenge methods
  - `3ds_challenge_profile` string — Unique identifier for the challenge profile. 3ds_challenge_methods will be ignored if this value is not null.
  - `card_type` integer — <ul><li class="docBullet">1 = Physical card</li><li class="docBullet">2 = Virtual card</li></ul>
  - `emboss_name` string — Emboss name.
  - `ch_ref` string — Customer reference
  - `del_title` string — delivery Title.
  - `del_fname` string — delivery First Name.
  - `del_sname` string — delivery Last Name.
  - `del_addr1` string — Delivery Address 1
  - `del_addr2` string — Delivery Address 2
  - `del_pcode` string — delivery Postal Code.
  - `del_city` string — delivery City.
  - `del_country` string — delivery Country.
  - `del_email` string, email — delivery Email.
  - `del_mobile` string — delivery Mobile. phone number format i.e 00 (contry code ) phone number or + (country code) phone number.
  - `del_pass_code` string — delivery Pass Code.
  - `del_method` integer — <p>delivery method for card :</p><ul><li class="docBullet">0 &ndash; Standard mail</li><li class="docBullet">1 &ndash; Registered mail</li><li class="docBullet">2 &ndash; Direct delivery (courier) RFU</li></ul>
  - `del_account` integer — delivery account Number.
  - `del_region` string — delivery Holder Region.
  - `pur_title` string — Purchaser Title.
  - `pur_fname` string — Purchaser First Name.
  - `pur_sname` string — Purchaser Last Name.
  - `pur_addr1` string — Purchaser Address 1.
  - `pur_addr2` string — Purchaser Address 2.
  - `pur_pcode` string — Purchaser Postal Code.
  - `pur_city` string — Purchaser City.
  - `pur_country` string — Purchaser Country.
  - `pur_email` string, email — Purchaser Email.
  - `pur_mobile` string — Purchaser Mobile,phone number format i.e 00 (contry code ) phone number or + (country code) phone number.
  - `pur_account` integer — Purchaser account Number
  - `pur_pass_code` string — Purchaser pass code (can be stored against card for customer authentication [i.e. activation stage], or Paymentology can generate)
  - `pur_region` string — Purchaser region.
  - `pur_cust_type` integer — <p>Purchaser customer type. This will determine the single delivery of a card to specific address</p><ul><li>0 =&gt; Card will be delivered to card holder address</li><li>1 =&gt; Card will be delivered to purchaser address</li></ul>
  - `bulk_delv_add_code` integer — <p>Bulk delivery address code.<br />It can be any value set by bank themselves.&nbsp;</p><p>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.<br />So if a card has bulk_delv_add_code = 10505, then this code is used to identify the delivery address inside &lt;BULK_DEL&gt; tag in perso file xml.</p><p>&nbsp;</p><p>Example :&nbsp;<br />If a client creates a batch of 5 cards and need to deliver to a single address.<br />Then bank can agree a value for <em><strong>bulk_delv_add_code</strong></em> other than 0 and put same delivery address for all cards. This will deliver cards to single address in bulk inside &lt;BULK_DEL&gt; tag in perso file xml.</p><p>&nbsp;</p><p>Note: If client need to send 5 cards to <em><strong>AddressX</strong></em> and 6 cards to <em><strong>AddressY</strong></em>, then client need to set different <em><strong>bulk_delv_add_code</strong></em> for two batch of cards.<br />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.</p><p><br />If client sets <em><strong>bulk_delv_add_code</strong></em> same for 5 cards but different delivery address for each card, then all cards will be delivered to delivery address of first created card.</p><p><br />If a client creates a card and need to deliver to a specific single address.<br />Then client can input either card holder address/details or purchaser address/ details based on <em><strong>pur_cust_type</strong></em> field. At this point client can put <em><strong>bulk_delv_add_code</strong></em> = 0 or empty/null so that it determines the card is for single delivery and address/details are populated inside &lt;RECORD&gt;==&gt;&lt;CH_ADDR&gt; tag in perso file xml</p><p><em><strong>pur_cust_type</strong></em></p><ul><li>0 =&gt; Card will be delivered to card holder address</li><li>1 =&gt; Card will be delivered to purchaser address</li></ul>
  - `del_code` integer — delivery Code, carriers with same del_code, will be grouped to be send to a specified delivery address.
  - `card_manuf_id` integer — card manufacturer id (If not passed then will take default manuf id will be taken from manufacturer table)
  - `carrier_type` string — Allows client to stipulate carrier type (card packaging type choice - for shipment to customer). Possible
  - `carrier_insrt1` integer — Identifies insert 1 to be included with Carrier in Envelope
  - `carrier_insrt2` integer — Identifies insert 2 to be included with Carrier in Envelope
  - `carrier_lang` string — Language to be used in carrier notes and labels(iso 3166-1, character three digits).
  - `envelope_ref` integer — Identifies envelope type
  - `ext_line1` string — Extra card text line 1, allows additional line for subjective requirements i.e. extra text in the card
  - `ext_line2` string — Extra card text line 2, allows additional line for subjective requirements i.e. extra text in the card
  - `custom_1` string — 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.
  - `emboss_line4` string — Emboss line 4, front of card additional text i.e. private token
  - `track_3` string — Track 3, Mag stripe
  - `product_ref` string — product identifier, i.e. physical card design reference used by the card printer.
  - `client_card_ref` string — Unique client reference relating to order, card or customer where present should always be quoted in correspondence
  - `inherit_rules` integer — <p>Inherit existing card rules. Based on value provide, it will either inherit existing rules or skip.&nbsp;</p><ul><li>0 ==&gt; Inherit</li><li>1 ==&gt; Donot inherit</li></ul><p>Default value is 0 i.e. always inherit</p>
  - `update_digital_token` boolean — Transfer digital tokens to new card. Digital token states will not be updated.

## Response `200`

Successful Response

- CardRenewV2ResponseModel
  - `header` Header
    - `error_desc` string, required — Error Description
    - `error_id` integer, required — Error Id
  - `body` CardRenewV2ResponseModelBody — Response body
    - `cvv` string — Card security code
    - `image_base64` string — Image data in base64 form
    - `epan` string — Encrypted pan number
    - `emboss_name` string — Name that appears in card
    - `expiry` string — Expiry in MM/YY format
    - `token` integer — Public token for card created
    - `cu_id` integer — Customer id
    - `cu_ref` string — Card holder customer reference
    - `is_3ds_enrolled` boolean — Flag that indicate the card is enrolled to 3DS
    - `3ds_enrollment_failure_reason` string — The reason for 3DS failure enrollment. Some examples are card_already_enrolled, no_such_card_range, not_authorized, resource_not_found

## Other responses

- `404` — Webservices does not exist
- `500` — Internal Server error

---

[API](https://skmtc.net/paymentology/apis/payapi-docs.md) · [All operations](https://skmtc.net/paymentology/apis/payapi-docs/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/paymentology/payapi-docs/revisions/a675891b0365/schema)