Query Card

Returns the attributes for the requested Payment Card.

Optional Query Strings:

  • AVS (required to perform AVS)
  • Fees (required to check fees)

Use ?QueryParam1+QueryParam2 if you’re using multiple query strings

If you are an ISO (Independent Sales Organization), you will need to specify a SubClientID (see notes below).


URL:

https://FQDN/v1/clients/ClientIDISO/cards

https://FQDN/v1/clients/ClientIDISO/cards?AVS
https://FQDN/v1/clients/ClientIDISO/cards?Fees
https://FQDN/v1/clients/ClientIDISO/cards?AVS+Fees


Request:

JSON Name Value Required Default Description Conditional
account
object
Hide Object
CR Either Account or Card Account
accountID String
22 characters
R AccountID Account
securityCode String
3-4 digits
O CVV2 Account
AVS
card
object
Hide Object
CR Either Account or Card
Either Payment Card Not Encrypted:
  • accountNumber
  • expirationDate
  • securityCode
or Payment Card Encrypted:
  • keyID
  • data
or Card Token (Restricted Usage):
  • token
or Device (Restricted Usage):
  • id
  • blob
or MobilePay (Restricted Usage):
  • accountNumber
  • expirationDate
  • cryptogram
  • transactionID
  • eciIndicator
  • network
  • type
Card
Data Encrypted?
accountNumber String
13-19 digits
R n Payment Card Account Number Card
Not Encrypted
expirationDate String
YYYYMM Format
O n
RAVS
Expiration Date Card
Not Encrypted
AVS
securityCode String
3-4 digits
O n CVV2 Card
Not Encrypted
AVS
keyID String
22 characters
R e KeyID Card
Encrypted
data String R e Encrypted Card Data, see below
encoded in Base64 URL-Safe Character Set
Card
Encrypted
token String ® t Card Token (from SSO)
Restricted Usage
Card
Token
device
object
Hide Object
® d Card Data from P2PE Device
Restricted Usage
Card
Device
id String ® d Device Identifier Card
Device
blob Hex String ® d Blob in Hex Card
Device
mobilePay
object
Hide Object
® m Card Data from Mobile Payment
Restricted Usage
SA PC
Mobile Pay
accountNumber String
13-19 digits
R m Pseudo Payment Card Account Number SA PC
Mobile Pay
expirationDate String
YYYYMM Format
R m Expiration Date SA PC
Mobile Pay
cryptogram Base64 String
28 characters
R m Payment Data Cryptogram SA PC
Mobile Pay
transactionID Hex String
64 characters
R m Transaction Identifier in Hex SA PC
Mobile Pay
eciIndicator String
1 character
O m Usually only Visa cards SA PC
Mobile Pay
network String R m Card Network
(Visa, MasterCard, Amex, Discover, etc...)
SA PC
Mobile Pay
type String R m Card Type
(Debit, Credit, PrePaid, etc...)
SA PC
Mobile Pay
owner
object
Hide Object
C Card Holder AVS / Verify
name
object
Hide Object
C Name on Card Verify
first String R First Name Verify
middle String O Middle Name or Initial Verify
last String R Last Name Verify
suffix String O Suffix Verify
address
object
Hide Object
C Billing Address AVS
line1 String O Address Line 1, for AVS, see notes below AVS
line2 String O Address Line 2 AVS
city String O City AVS
state String
2-character code
O State Code AVS
zipcode String R Zip Code AVS
country String
3-digit code
O 840 ISO 3166-1 Country Code AVS
phone
object
Hide Object
C Phone Number (E.164 Numbering) Verify
countryCode String
1-3 digits
O 1 Country Calling Code Verify
number String
Min: 4 digits
Max: 12-14 digits
R Phone Number Verify
currency String
3-digits
O 840 ISO 4217 Currency Number Fees Check
amount String
Amount
C Amount of Transaction Fees Check
timeout Number
Between 15 and 50
O 39 Maximum time to wait for AVS and/or Verify Response AVS / Verify

Encrypted Card Data:

Field Required Description UnEncrypted Card Data Format
Card Number R 13-19 digit Card Number CardNumber | Expiration Date | Security Code

(no spaces, pipe symbol separated)
see samples
Expiration Date O
RAVS
Expiration date in YYYYMM Format
Security Code O 3 or 4 digit CVV2

Sample Requests

Pack your Request, the following Samples shown here are unpacked only for human readability:

Query Card:

{
  "card":
  {
    "accountNumber": "9999999999999999"
  }
}

-----
Query Card using Encrypted Data:
{
  "card":
  {
    "keyID": "TabaPay_KeyID_22-chars",
    "data": "Base64_Encoded_Encrypted_Data"
  }
}

-----
Query Card using AccountID:
{
  "account":
  {
    "accountID": "TabaPay_AccountID_22ch"
  }
}

-----
Query Card and Fees Check:
{
  "card":
  {
    "accountNumber": "9999999999999999"
  },
  "amount": "0.50"
}

-----
Unencrypted Card Data:
1111111111111111||

where

Card Number:     1111111111111111
Expiration Date: None
Security Code:   None

-----
1111111111111111|203001|

where

Card Number:     1111111111111111
Expiration Date: January 2030
Security Code:   None

-----
1111111111111111|203001|333

where

Card Number:     1111111111111111
Expiration Date: January 2030
Security Code:   333

-----
1111111111111111||333

where

Card Number:     1111111111111111
Expiration Date: None
Security Code:   333

Response:

Status Codes:

Status Code Description
200 OK The Payment Card's Attributes are returned.
207 Multi-Status One or more Failures occurred while processing the Request.

See Status Codes for other possible Status Codes that might be returned.


Response Data:

JSON Name Value Description Status Code Conditional
200 207 Other
SC Integer
3-digit code
HTTP Status Code O
EC String
1 or 8 characters
Internal Error Code O
EM String Error Message O
card object Card Attributes
bin String First 6 Digits of Card Number
last4 String Last 4 Digits of Card Number
nameFI String Issuer Name O O
pull object Debit Transaction
enabled Boolean
network String O O
type String Credit, Debit, PrePaid O O
regulated Boolean O O
currency String
3-digit code
ISO 4217 Currency Number O O
country String
3-digit code
ISO 3166-1 Country Code O O
push object Credit Transaction
enabled Boolean
network String O O
type String Credit, Debit, Prepaid O O
availability String Estimated Funds Availability O O
regulated Boolean O O
currency String
3-digit code
ISO 4217 Currency Number O O
country String
3-digit code
ISO 3166-1 Country Code O O
AVS object AVS Results C C AVS
avsID String
22-characters
AVS Transaction Identifier O AVS
networkRC String
2 or 3-character code
Network Response Code O AVS
networkID String Network Identification Code O AVS
authorizeID String ID O AVS
resultText String AVS Result Text O AVS
codeAVS String AVS Response Code O AVS
codeSecurityCode String Security Code Response Code O AVS
EC String
1 or 8 characters
Internal Error Code O AVS
fees object Fees Check C C Fees Check
pull object Debit Transaction O O Fees Check
interchange String
Amount
Interchange Fees Fees Check
network String
Amount
Network Fees Fees Check
tabapay String
Amount
TabaPay Fees Fees Check
push object Credit Transaction O O Fees Check
interchange String
Amount
Interchange Fees Fees Check
network String
Amount
Network Fees Fees Check
tabapay String
Amount
TabaPay Fees Fees Check

Sample Responses:

Query Card:
{
  "SC": 200,
  "EC": "0",
  "card":
  {
    "pull":
    {
      "enabled": true,
      "network": "Visa",
      "type": "Debit",
      "regulated": true,
      "currency": "840",
      "country": "840"
    },
    "push":
    {
      "enabled": true,
      "network": "Visa",
      "type": "Debit",
      "regulated": true,
      "currency": "840",
      "country": "840",
      "availability": "Immediate"
    }
  }
}

-----
Query Card (pull disabled):
{
  "SC": 200,
  "EC": "0",
  "card":
  {
    "pull":
    {
      "enabled": false
    },
    "push":
    {
      "enabled": true,
      "network": "Visa",
      "type": "Debit",
      "regulated": true,
      "currency": "840",
      "country": "840",
      "availability": "Immediate"
    }
  }
}

-----
Query Card (push disabled):
{
  "SC": 200,
  "EC": "0",
  "card":
  {
    "pull":
    {
      "enabled": true,
      "network": "Visa",
      "type": "Debit",
      "regulated": true,
      "currency": "840",
      "country": "840"
    },
    "push":
    {
      "enabled": false
    }
  }
}

-----
Query Card (disabled/unsupported):
{
  "SC": 200,
  "EC": "0",
  "card":
  {
    "pull":
    {
      "enabled": false
    },
    "push":
    {
      "enabled": false
    }
  }
}

Notes:

For Clients who are an ISO (Independent Sales Organization), to specify your ClientID and a SubClientID, use the underscore character ("_") to separate the two values: <ClientID>_<SubClientID> where:

  • ClientID is your unique 22-character string and
  • SubClientID is an assigned 4, 6 or 8-digit value.

There is an extra charge (fee) for using Query Card and there is also an additional charge (fee) for using AVS.


Creating an Account just to do a Query Card is not the valid way to use our API (it is an Anti-Pattern). As we try to show in the Sample Flows: Query Card should be done first before Creating an Account, this is the correct Pattern (or use of our API).

Creating unused and/or inactive Accounts will result in:

  • These Accounts incurring an extra charge (fee)
  • These Accounts being automatically deleted
    Excessive Anti-Pattern behavior will result in:
  • Your Requests failing
  • Your Client being locked

If using Account, only:

  • Card Account Number
  • Expiration Date (for AVS)
    are obtained from the Account for use.

For AVS:

  • Security Code
  • Owner Address
    are obtained from the request.

For AVS, Address Line 1 is optional, but you will get an AVS Code that says only Zip Code was matched (or not) and Address was not matched.


The Fees are only an estimation. The actual Fees will be shown on your daily settlement reports.