Sign in

v1

latestOpenAPI 3.0.02026-07-242035712.0 MB
Card

Create Card

This web service is used to create a card(prepaid,debit,credit). To create a card an account needs to be created first as a card has a one to one relationship with an account.

  • Cards can be created as either physical or virtual cards with a variety of images that have been predefined and loaded per client. When calling the create card the option to return pan, cvv, expiry, public token, card image can be used to allow for the display of the card image with all details post card creation.
  • It is essential that the correct product ID is provided.
  • At the time of card creation, you can select the status of the card, typically set to Decline All Txns DE39=05 until the card holder activates the card. card holder details are provided at the time of card creation to populate the card holder details and to provide these as part of the card personalization process (physical card only).
  • At creation the card can be loaded with funds in accordance with the specific product settings.
  • Auto-enrollment to 3DS is made available by enabling feature on Product configuration. Contact Paymentology to enable this feature.
  • If 3DS enrollment fails, you will need to manually call Enroll Card to 3DS API.
  • These inputs are used for creating cards for sub clients/customers under a generic client. Sub clients/customers do not have products or bins of their own and will inherit from parent client, post card creation.
  • The characteristics (tok_flag) of the card can be set at the card create stage and this determines how the card will behave once created, activated, and used.

Note For Clients using FSS(3DS provider) adhere to FSS requirements. 

  • Cardholder name (ch_fname and ch_sname) - String minimum 2 and maximum 45 characters combined first and last name - only letters are acceptable 

  • Mobile phone number(ch_mobilel) - only numbers without space (symbols are not acceptable) - must contain between 5 and 15 characters

post/pws/pws_create_card/

Request body

api_call_unique_identifierstring required

Unique number that must be passed at each API request. Identifier to make each API request unique

card_typeinteger required
<ul><li class="docBullet">1 = Physical card</li><li class="docBullet">2 = Virtual card</li></ul>
client_idinteger required

Unique identifier for the client which Paymentology will provide at outset

crd_prdct_idinteger required

card product id. (Need to input correct product id for your card so it will inherit full required properties and be fully linked with business.)

image_deliveryinteger 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,emboss_name).</li> <li class="docBullet">2 ==&gt; Image in byte encrypted ,encrypted pan, cvv,token,expiry,emboss_name.</li> <li class="docBullet">3 ==&gt; Data details JSON (encrypted pan,cvv,token,expiry,emboss_name but no image.</li> <li class="docBullet">4 ==&gt; Image in byte encrypted , masked pan back, cvv,token,expiry,emboss_name.</li> </ul>
image_fieldsstring required
<p>Show or hide pan,cvv,expiry,token,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>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, emboss_name).</p>
image_namestring 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.

status_nwkinteger required
<p>Status network :</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">1005 : Decline all txns DE39=05</li> <li class="docBullet">1007 : Decline all txns (Visa: DE39=12) (MC: DE39=14)</li> <li class="docBullet">1008 : Honour with ID DE39=08</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">1140 : Lost Card - NO Capture</li> <li class="docBullet">1143 : Stolen card - NO Capture</li> <li class="docBullet">1154 : Expire card - don't inform</li> <li class="docBullet">1062 : Restricted card</li> </ul>
xml_fieldsstring required
<p>Show or hide pan,cvv,expiry,token,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 (This can be overrided from client level setting to show or hide 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, emboss_name).</p>
user_idstring

User Id of the Customer who triggered the API request.

remarksstring

Remarks for API request

cu_idinteger
<p> Existing Customer Id.Following parameter are not required when we use existing customer_id</p><ul><li>ch_title</li><li>ch_fname</li><li>ch_sname</li><li>ch_addr1</li><li>ch_addr2</li><li>ch_pcode</li><li>ch_city</li><li>ch_country</li><li>ch_email</li><li>ch_mobile</li><li>ch_region</li><li>ch_dob</li></ul>
card_manuf_idinteger

card manufacturer id (If not passed then will take default manu id will be taken from manufacturer table).

emboss_namestring

Name that appears in front of the card.

tok_flagsstring
<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)">Sets 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)">Sets card to decline all Ecommerce</td><td>9</td></tr> <tr><td title ="Decline all ATM Cash withdrawal transactions">Sets card to decline all ATM</td><td>10</td></tr> <tr><td title ="Do not allow any balance enquiry transactions">Sets card to deline 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.">Sets 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.">Sets 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">Sets 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">Sets card to decline non base currency txn</td><td>20</td></tr> <tr><td title ="No account verification requests should be allowed">Sets 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">sets 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. ">sets 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">sets 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">sets 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 ="Sets card to approve if AVS match fails">Sets 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>
client_card_ref'range[-infinity, 100]'

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

product_ref'range[-infinity, 60]'

Product reference

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

exp_datestring

Expiry Date, accepted format yyyy-mm-dd hh:mm:ss.

ac_parent_idinteger

Parent account number. If provided system will automatically create a new account linked to the card.

ac_idinteger

Existing account number. New card will be linked to this account. If using existing account, do not send ac_parent_id.

ac_name'range[-infinity, 50]'

account name. Required if ac_parent_id provided. Optional if ac_id provided.

ac_ext_ref'range[-infinity, 50]'

account external reference.

ac_desc'range[-infinity, 100]'

Description for the account holder.

ac_set_ccystring

Settlement currency code. (Three digit ISO-4217 standard currency code . i.e. : 048 → BHD, 060 → BMD, 036 → AUD)

ac_bill_ccystring

Billing currency. (Three digit ISO-4217 standard currency code . i.e. : 048 → BHD, 060 → BMD, 036 → AUD)

ch_title'range[-infinity, 10]'

card Holder Title.

ch_fnamestring

card Holder First Name.

ch_snamestring

card Holder Surname.

ch_addr1string

card Holder Address1.

ch_addr2string

card Holder Address2.

ch_pcode'range[-infinity, 15]'

card Holder Postal Code.

ch_city'range[-infinity, 50]'

card Holder City.

ch_country'range[-infinity, 50]'

card Holder Country.

ch_emailstring email

card Holder Email.

ch_mobilestring

card Holder Mobile Number. phone number format i.e 00 (country code) phone number or + (country code) phone number.

ch_regionstring

card Holder Language Region.

ch_refstring

Card holder/customer reference

ch_dobstring

card Holder Date of Birth, accepted format yyyy-mm-dd.

del_title'range[-infinity, 10]'

delivery Title.

del_fnamestring

delivery First Name.

del_snamestring

delivery Surname.

del_addr1string

delivery Address1.

del_addr2string

delivery Address2.

del_pcode'range[-infinity, 15]'

delivery postal code.

del_city'range[-infinity, 50]'

delivery City.

del_country'range[-infinity, 50]'

delivery Country.

del_emailstring email

delivery Email.

del_mobilestring

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

del_pass_code'range[-infinity, 10]'

delivery Pass Code.

del_methodinteger
<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_accountinteger

delivery account Number.

del_regionstring

delivery Language.

bulk_delv_add_codeinteger
<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>
pur_cust_typeinteger
<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>
del_codeinteger

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

pur_title'range[-infinity, 10]'

Purchaser Title.

pur_fnamestring

Purchaser First Name.

pur_snamestring

Purchaser Sur Name.

pur_addr1string

Purchaser Address1.

pur_addr2string

Purchaser Address2.

pur_pcode'range[-infinity, 15]'

Purchaser Postal Code.

pur_citystring

Purchaser City.

pur_country'range[-infinity, 50]'

Purchaser Country.

pur_emailstring email

Purchaser Email.

pur_mobilestring

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

pur_accountinteger

Purchaser account Numbe.r

pur_pass_code'range[-infinity, 10]'

Purchaser Pass Code.

atm_langstring

Language to be used in ATM <ul><li class="docBullet">01 ==> Chinese</li><li class="docBullet">02 ==> English</li><li class="docBullet">03 ==> Portugese</li><li class="docBullet">04 ==> Spanish</li></ul>

carrier_typestring

Allows client to stipulate carrier type (card packaging type choice - for shipment to customer) possible.

carrier_insrt1integer

Identifies insert 1 to be included with carrier in envelope. Inserts are agreed with the card manufacturer. Please consult paymentology or the card manufacturer for details on your defined inserts.

carrier_insrt2integer

Identifies insert 2 to be included with carrier in envelope

carrier_lang'range[-infinity, 3]'

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

envelope_refinteger

Identifies envelope type

ext_line1'range[-infinity, 20]'

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

ext_line2'range[-infinity, 20]'

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

custom_1'range[-infinity, 255]'

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_line4string

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

track_3'range[-infinity, 50]'

Track 3, Mag stripe.

fulfil1string

Future field 1 RFU.

fulfil2'range[-infinity, 50]'

Future field 2 RFU.

group_idstring

Associates group id with the account created or existing account during card create. Use valid groups id. If invalid group id passed in string, associate will be skipped for specific group id.

crd_instrstring

Instruction for the card.

auth_typestring
<p>Authorization Type :</p> <ul> <li class="docBullet">0==&gt;Internal</li> <li class="docBullet">1==&gt;External</li> <li class="docBullet">2==&gt; Notification</li> </ul>
branch_namestring

Branch Name from where the account is created

fee_idinteger

Fee that is applied as the service charge

guarantee_idinteger

Id that represent the guarantee type for the given client

guarantee_notestring

text that describe the guarantee type

guarantee_amountnumber

Guarantee Amount that is applied for the given account

chip_langstring

2-digit ISO (639.2) language code .i.e EN,ES

perso_fieldsstring
<p> Configuration for sensitive data </p> <table> <tbody> <tr> <th><strong>Position</strong></th> <th><strong>Field</strong></th> <th><strong>Description</strong></th> </tr> <tr> <td>1</td> <td>RFU</td> <td>Reserved for future</td> </tr> <tr> <td>2</td> <td>CVV</td> <td>set 0 - to send CVV value 000 in card file set 1 - to send actual CVV value in card file </td> </tr> <tr> <td>3</td> <td>RFU</td> <td>Reserved for future</td> </tr> <tr> <td>4</td> <td>RFU</td> <td>Reserved for future</td> </tr> <tr> <td>5</td> <td>Emboss Name</td> <td>0 : Lower case, 1 : Upper case</td> </tr> </tbody> </table> <p> Eg : 01001 Means show cvv and save emboss name as uppercase. If nothing is sent on parameter, default value will be 11111.</p>
3DSTokenAndCardEnrollmentStatusstring
multiAccountCardboolean

Used to determine if the card is multi-account during idempotency

3ds_langstring

ISO 639-1 two-letter language code.

3ds_challenge_profilestring

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

token_group_idstring
product_configuration_idstring

Product configuration ID (PCID) or Card art reference ID to be used for future tokenization linked to this card. Applicable to Meawallet and MADA implementations.

Example request

{
  "api_call_unique_identifier": "438574845790657485",
  "card_type": 2,
  "client_id": 760131,
  "crd_prdct_id": 67,
  "image_delivery": 1,
  "image_fields": "11111",
  "image_name": "paymentology",
  "status_nwk": 1000,
  "xml_fields": "11111",
  "card_manuf_id": 12,
  "emboss_name": "Akshay Patel",
  "tok_flags": "00000000000000000000000000000000",
  "client_card_ref": "client choice",
  "exp_date": "2025-01-01 00:00:00",
  "ac_parent_id": 542283189,
  "ac_name": "Akshay Patel",
  "ac_desc": "New account Desc",
  "ac_set_ccy": "826",
  "ac_bill_ccy": "826",
  "ch_title": "Mr",
  "ch_fname": "Akshay",
  "ch_sname": "Patel",
  "ch_addr1": "Canada",
  "ch_addr2": "London",
  "ch_pcode": "A123X",
  "ch_city": "London",
  "ch_country": "UK",
  "ch_email": "akshay@paymentology.com",
  "ch_mobile": "00792736252",
  "ch_region": "ENG",
  "ch_ref": "customer ref",
  "ch_dob": "1998-01-02",
  "del_title": "Mr",
  "del_fname": "Akshay",
  "del_sname": "Patel",
  "del_addr1": "London",
  "del_addr2": "Nadipur",
  "del_city": "Pokhara",
  "del_country": "Nepal",
  "del_email": "akshay@paymentology.com",
  "del_mobile": "+9779846545555",
  "del_method": 1,
  "del_region": "ENG",
  "pur_cust_type": 1,
  "pur_title": "Mr",
  "pur_fname": "Akshay",
  "pur_sname": "Patel",
  "pur_addr1": "London",
  "pur_addr2": "London",
  "pur_pcode": "00977",
  "pur_city": "London",
  "pur_country": "London",
  "pur_email": "patel@paymentology.com",
  "pur_mobile": "+9779845655522",
  "atm_lang": "01",
  "carrier_type": "1",
  "carrier_insrt1": 1,
  "carrier_insrt2": 1,
  "carrier_lang": "ENG",
  "envelope_ref": 1,
  "group_id": "55,56",
  "auth_type": "0",
  "accounts": [
    {
      "ac_bill_ccy": "048",
      "ac_name": "Akshay Patel",
      "ac_desc": "New account Desc",
      "ac_ext_ref": "0",
      "ac_set_ccy": "826"
    }
  ],
  "chip_lang": "826",
  "perso_fields": "11111",
  "3ds_lang": "en",
  "3ds_challenge_profile": "950c886e-8eba-4465-8443-d22f90d269f8",
  "product_configuration_id": "ANYGOLD1"
}

Response

Successful Response

Example response

{
  "header": {
    "error_desc": "success"
  },
  "body": {
    "cvv": "***",
    "image_base64": "ZSBzaG9ydC=",
    "epan": "***********",
    "emboss_name": "JOHN DOVE",
    "expiry": "03/21",
    "token": 788193393,
    "ac_id": 788193393,
    "last_four_digit": "0082",
    "mpan": "5445*****434**4354",
    "bill_blk_amt": 100.1,
    "bill_act_amt": 100.1,
    "bill_pnd_amt": 100.1,
    "load_ccy": "826",
    "is_3ds_enrolled": true,
    "3ds_enrollment_failure_reason": "no_such_card_range",
    "cu_id": 863051688
  }
}