API Explorer
Client Login

Create card v2

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

  • 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

Version 2 create card api support idempotency;

  • If previous api request was success and client send same api_unique_identifier, then same previous response will be returned

  • If previous api request was failed and client send same api_unique_identifier, then new card create will be processed with incoming api parameters

Body Params

-- This web service creates a card. -- It will retrieve back pan, cvv, expiry, public token, card image . -- An account number is mandatory while creating a card. -- All cards are created under a parent account. -- One child account is assigned to one card. -- A card can be three types: 1 ==> physical, 2 ==> virtual

string
required
length between 1 and 40

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

int32
required
1 to 2
  • 1 = Physical card
  • 2 = Virtual card
int32
required
≥ 1

Unique identifier for the client which Paymentology will provide at outset

int32
required
≥ 1

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.)

int32
required
1 to 5

How to deliver image back to client. Example :

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

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

PositionField
1pan
2cvv
3expiry
4token
5emboss_name

EG : 00111 (Hide pan and cvv but show expiry token, 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.

int32
required
≤ 32767

Status network :

  • 1000 : Fully operational DE39=00
  • 1001 : Refer to issuer DE39=01
  • 1004 : Capture card DE39=04
  • 1005 : Decline all txns DE39=05
  • 1007 : Decline all txns (Visa: DE39=12) (MC: DE39=14)
  • 1008 : Honour with ID DE39=08
  • 1041 : Lost card - capture DE39=41
  • 1043 : Stolen card - capture DE39=43
  • 1054 : Expired card - report DE39=54
  • 1140 : Lost Card - NO Capture
  • 1143 : Stolen card - NO Capture
  • 1154 : Expire card - don't inform
  • 1062 : Restricted card
string
required
length between 5 and 5

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

PositionField
1pan
2cvv (This can be overrided from client level setting to show or hide cvv)
3expiry
4token
5emboss_name

EG : 00111 (Hide pan and cvv but show expiry token, 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

int32

Existing Customer Id.Following parameter are not required when we use existing customer_id

  • ch_title
  • ch_fname
  • ch_sname
  • ch_addr1
  • ch_addr2
  • ch_pcode
  • ch_city
  • ch_country
  • ch_email
  • ch_mobile
  • ch_region
  • ch_dob
int32
≤ 32767

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

string
length between 0 and 30

Name that appears in front of the card.

string
length between 0 and 32

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 :

TOK_DESCRIPTIONBIT_POSITION
Send card bal in De54 in next auth3
Send pin unblock to card4
Sets card to decline all tranasaction except ecommerce5
Set card to decline all Contactless transaction6
Sets card to decline all Ecommerce9
Sets card to decline all ATM10
Sets card to deline Bal enquiry over auth11
Sets card to decline cash back txns12
Sets card to decline Auth credit pur/refund (DE3_1=20)14
Sets card to decline credit payment (DE3_1=28)19
Sets card to decline non base currency txn20
Sets card to decline all account enq (de61_7=8)21
sets card to decline card not present txns22
sets card to decline Cardholder not present txns23
sets card to decline failover to mag at emv capable atm24
sets card to decline mag at atm25
Alow if fallback chp->mag at chp capable pos DE22_1=8026
Allow if de22_1=02 & De48_88 =Y27
Sets card to approve if AVS match fails28
Set card to decline Recurring transaction29
string
enum
length between 0 and 100

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

Allowed:
string
enum
length between 0 and 60

Product reference

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

Allowed:
string

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

int64

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

int64

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

string
enum
length between 0 and 50

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

Allowed:
string
enum
length between 0 and 50

account external reference.

Allowed:
string
enum
length between 0 and 100

Description for the account holder.

Allowed:
string
length between 0 and 3

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

string
length between 0 and 3

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

string
enum
length between 0 and 10

card Holder Title.

Allowed:
string
length between 0 and 50

card Holder First Name.

string
length between 0 and 50

card Holder Surname.

string
length between 0 and 100

card Holder Address1.

string
length between 0 and 100

card Holder Address2.

string
enum
length between 0 and 15

card Holder Postal Code.

Allowed:
string
enum
length between 0 and 50

card Holder City.

Allowed:
string
enum
length between 0 and 50

card Holder Country.

Allowed:
string
length between 0 and 60

card Holder Email.

string
length between 0 and 20

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

string
length between 0 and 60

card Holder Language Region.

string
length between 0 and 50

Card holder/customer reference

string

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

string
enum
length between 0 and 10

delivery Title.

Allowed:
string
length between 0 and 50

delivery First Name.

string
length between 0 and 50

delivery Surname.

string
length between 0 and 100

delivery Address1.

string
length between 0 and 100

delivery Address2.

string
enum
length between 0 and 15

delivery postal code.

Allowed:
string
enum
length between 0 and 50

delivery City.

Allowed:
string
enum
length between 0 and 50

delivery Country.

Allowed:
string
length between 0 and 60

delivery Email.

string
length between 0 and 20

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

string
enum
length between 0 and 10

delivery Pass Code.

Allowed:
int32

delivery method for card :

  • 0 – Standard mail
  • 1 – Registered mail
  • 2 – Direct delivery (courier) RFU
int64

delivery account Number.

string
length between 0 and 50

delivery Language.

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
≤ 1

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

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

string
enum
length between 0 and 10

Purchaser Title.

Allowed:
string
length between 0 and 50

Purchaser First Name.

string
length between 0 and 50

Purchaser Sur Name.

string
length between 0 and 100

Purchaser Address1.

string
length between 0 and 100

Purchaser Address2.

string
enum
length between 0 and 15

Purchaser Postal Code.

Allowed:
string
length between 0 and 50

Purchaser City.

string
enum
length between 0 and 50

Purchaser Country.

Allowed:
string
length between 0 and 60

Purchaser Email.

string
length between 0 and 20

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

int64

Purchaser account Numbe.r

string
enum
length between 0 and 10

Purchaser Pass Code.

Allowed:
string
length between 0 and 2

Language to be used in ATM

  • 01 ==> Chinese
  • 02 ==> English
  • 03 ==> Portugese
  • 04 ==> Spanish

string

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

int32
≤ 32767

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.

int32
≤ 32767

Identifies insert 2 to be included with carrier in envelope

string
enum
length between 0 and 3

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

Allowed:
int32
≤ 32767

Identifies envelope type

string
enum
length between 0 and 20

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

Allowed:
string
enum
length between 0 and 20

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

Allowed:
string
enum
length between 0 and 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.

Allowed:
string
length between 0 and 35

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

string
enum
length between 0 and 50

Track 3, Mag stripe.

Allowed:
string
length between 0 and 50

Future field 1 RFU.

string
enum
length between 0 and 50

Future field 2 RFU.

Allowed:
string

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.

string
length between 0 and 50

Instruction for the card.

string
length between 1 and 1

Authorization Type :

  • 0==>Internal
  • 1==>External
  • 2==> Notification
accounts
array of objects

Multi accounts that will be created during card create under parent account or child account and linked with the created token. one card might be mapped to X of accounts and the default account is linked to the card. Default account and default currency are set to 1.

accounts
string

Branch Name from where the account is created

int64

Fee that is applied as the service charge

int32

Id that represent the guarantee type for the given client

string

text that describe the guarantee type

number

Guarantee Amount that is applied for the given account

string
length between 0 and 50

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

string
length between 5 and 5

Configuration for sensitive data

PositionFieldDescription
1RFU Reserved for future
2CVV set 0 - to send CVV value 000 in card file set 1 - to send actual CVV value in card file
3RFU Reserved for future
4RFU Reserved for future
5Emboss Name 0 : Lower case, 1 : Upper case

Eg : 01001 Means show cvv and save emboss name as uppercase. If nothing is sent on parameter, default value will be 11111.

string
boolean

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

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.

string
string

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.

Responses

404

Webservices does not exist

500

Internal Server error

Updated 5 months ago

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

Updated 5 months ago