Introduction to APIs

API General Message Layout and Requirements

API Message Format

About the Response to the User

About Response Time

Back Office Web Access

Currency Amounts and Conversion Instructions

PIN Encryption

Alternatives to Using Card Number in the CardAPI

API User Credentials

CardHolder API’s

Change Card Status – Function 004

Change Card PIN – Function 005

Deposit to Card Number – Function 007

Message Response Lookup – Function 008

View Statement Details by Card Number – Function 010

Validate PIN – Function 012

Set Card PIN – Function 022

Get Card Status – Function 023

Get Card Account Balance – Function 024

Cardholder Fees – Function 030

Adjustment – Function 031

Card Linking – Function 032

Card Inquiry – Function 033

Cash Out – Function 034

Card to Card Transfer – Function 035

Update Cardholder – Function 036

PIN Reset – Function 037

PIN Request – Function PINRequest

View Statement Details by Account Number – Function 039

Unlock Bad PIN Tries – Function 040

Set Condition Check for Existing Cardholder – Function SetCondCheck

Manage MCC Blocks – Function MCCBlock

Set Cardholder Level Limit – Function CardLimit

Get Configurable Card Limits – Function GetCardLimits

OFAC Check – Function 056

View Statement Details by Card Number (V2) – Function 070

3DS Enrolment Control – Function THREEDS

3DS Whitelist Management – Function Manage3DSWhitelist

Card Risk Level API Calls

Update Card Risk Level – Function = UpdateRiskLevel

Get Card Risk Level – Function = GetRiskLevel

Instant Card Issue – Function = InstantCardIssue

Specialized Financial Transactions

Validate Cardholder Verification Data – Function ValidateCVV2

Get Dynamic CVV (CVV3) – Function GetCVV3

General Web APIs

Change Password – ChangePswd

Message Heart Beat – Function 025

Wallet API Functions

Create Wallet for Existing Cardholder – Function CreateCardholderWallet

Create Wallet Multi-Currency Card Purse – Function CreateCardPurse

Retrieve Card Purse Identification from Wallet – Function GetCardPurses

Multi-currency Card Purse to Purse Transfer – Function PurseFundsTransfer

Processing Codes


Transaction Processing Codes

Response Codes

Card/Account Type Definitions

API Error Codes


Instant Card Issue – Function = InstantCardIssue

InstantCardIssue will create, on demand, an AuthENGINAPI and associate any demographic data to that AuthENGINAPI. If a PIN is specified, that PIN will be used. If a PIN is not specified a random four – digit numeric PIN will be generated by the API. If a cardholderid is specified, it must be unique. It is recommended that the cardholderid be set to an asterisk ‘*’ so that the cardholderid will be automatically generated by the API.

The CUSR can be configured to check OFAC, Verify the SSN, Verify the DOB, and provide a fraud rating using GeoIP. These identity checks may be overridden.

A pseudo DDA number will be returned in the response. The value will appear with “DDAnumber.”

Inputs Description Required Data Type
FunctionID InstantCardIssue Y
cardholderid Client Cardholder ID – a unique value assigned by the client Y (1,32) varchar
firstname First Name Y (1,20) varchar
middlename Middle Name N (1,30) varchar
lastname Last Name Y (1,20) varchar
address1 Address 1 Y (1,240) varchar
address2 Address 2 N (1,240) varchar
address3 Address 3 N (1,240) varchar
address4 Address 4 N (1,240) varchar
city City Y (1,240) varchar
state State / Parrish / Province Y (1,60) varchar
countyname County (additional regional designation) N (1,80) varchar
zip Postal Code Y (5 – 15) varchar
country Cardholder Country Code – ISO3166 – 2- digit alpha Y (2) varchar alpha
secondaryaddress1 Secondary Address 1 N (1,240) varchar
secondaryaddress2 Secondary Address 2 N (1,240) varchar
secondaryaddress3 Secondary Address 3 N (1,240) varchar
secondaryaddress4 Secondary Address 4 N (1,240) varchar
city2 City N (1,240) varchar
state2 State / Parrish / Province N (1,60) varchar
countyname County (additional regional designation) N (1,80) varchar
zip2 Postal Code N (5 – 15) varchar
countrycode2 Cardholder Country Code – ISO3166 – 2-digit alpha N (2) varchar alpha
securityfield1 Security Field 1 – can include mother’s maiden name or license number N (1,22) varchar
securityfield2 Security Field 2 – N (1,22) varchar
securityfield3 Security Field 3 – N (1,22) varchar
securityfield4 Security Field 4 – N (1,22) varchar
udf1 User defined Field 1 – handles special requirement of client N (1,255) varchar
udf2 User defined field 2 N (1,255) varchar
udf3 User defined field 3 N (1,255) varchar
udf4 User defined field 4 N (1,255) varchar
udf5 User defined field 5 N (1,255) varchar
email Email *Email required if user’s API configuration settings include INSTANTISSUE_EMAIL_REQUIRED N* (1,255) varchar
phone Phone N (7 -32) varchar
phone2 Phone 2 *Phone2 (Mobile Phone) is required for programs which are enrolled for 3DS through DPG. N* (7 -32) varchar
Remote_Host Remote Host N (1,15) varchar
distributorcode Distributor code N (1,8) varchar
companyname Company Name N (240) varchar
deltype Delivery type. VC Virtual Card (not printed) N (2) varchar
expdate Expiration date. The use of this field is not recommended unless creating test cards. This value will be generated by the system to the program’s setup value when left blank. N (4) varchar
id_type Other ID Type Used when passing personal IDs other than SSN. May also be used in place of P18. Identify ID type using: SSN (Social Sec Number) ITIN (Individual Tax ID) ATIN (Adoption Tax ID) NATIONAL_ID PASSPORT DRIVERS_LIC Y varchar If a valid type is not provided associated data will be skipped.
id_number ID Number Y (1,80) varchar
id_issuer ID Issuer Y (1,80) varchar Identify the country or state that issued the ID
PIN PIN N (4) numeric
cardstyle Card Style Used by CardUSA to pass card style Y (2) varchar
BIN BIN and client code of issuer Y 6-9 numeric
OFACOverride OFAC override = Y N Y/N
GeoIPOverride GEO IP Override = Y Y Y/N
ddaacctnbr DDA Account Number – This value is a bank account number. This field may be used to override the system generated account number. Also utilized for ACH * N* (1,19) varchar
ddaroutenbr DDA Route Num ber (ABA) * N* (1,12) varchar
PINXFER Transfer PIN from an existing card to a new card. This value represents the card number or ALT_ID of the cardholder to pull the pin from. N (1,32) varchar
accttype Account type utilized in ACH* N* 10 = savings 20= checking
Language Acceptable inputs:
N varchar
3DS Security question:
SQ – Security Question
SA – Security Answer
*Please see 3DS note on formatting below
N varchar
Output Description
P1 Error code Y (1,255) varchar
P2 Error Text Y (1,255) varchar
CardholderID CardholderID Y (32) varchar
CardNumber CardNumber Y (16) numeric
PIN PIN Y (4) numeric or (12) varchar
AvailableBalance Available Balance Y (10) numeric
LedgerBalance Ledger Balance Y (10) numeric
Status Status Y (1) numeric
CVV2 CVV2 Y (3) numeric
expdate Expiration Date Y YYMM (4) numeric

Note: When User Configuration BLOCKED_COUNTRIES is present ‘country’ must match one of the country codes (ISO 3166) defined. If not, the request will fail.

For programs enrolling in Mastercard 3DS through DPG phone2 is a required field.

  • ADD parameter Phone2 and apply 00 to the beginning of the phone number.
    Example: &Phone2=04071234321NOTE: Response will tell you if automatic 3DS enrolment was successful. You should receive response &3DS=Y. If for some response received is &3DS=N, then you will need to manually run FUNC THREEDS to enroll the card for 3DS.

ACH processing: When all values are present and the card number starts with 2, micro-validation initiates. Not all InstantCardIssue will use ACH, so the fields aren’t always required.

3DS Question Formatting:
URL Safe Base64 Encoded Question:
What was the color of your first car?
3DS Answer Formatting:
All uppercased, SHA256 hashed, URL Safe Base64 Answer:
Example: InstantCardIssue Request*&firstname=Mike&middlename=%20&lastname=Smith&address1=1MainSt&address2=&city=Maitland&state=FL&zip=88677&country=US&securityfield1=xxx&securityfield2=xxx&udf1=&udf2=&
1. If a parameter is not required, it may be omitted from the api function call
2. Parameters ARE case sensitive and are treated as an invalid parameter.
3. If an “invalid” parameter is passed in, it will be ignored (deltype)
Example: InstantCardIssue Response

oy o=&AvailableBalance=0&LedgerBalance=0&Status=0&CVV2=888&expdate=1704&DDAnumber=02
1. Do not assume that because P1 <>0000 that a card was not created, you must parse for CardNumber
2. Template formats can be configured by program/binclient for CardholderID and DDA number.
(Both of these numbers represent alternate id values that can be used to replace cardnumber in subsequent api calls)