Objects

Overview of various objects returned for the different Cards APIs.

The table below lists the response objects received for the different Cards APIs.

Cards APIsResponse Object
  • Create Cards
  • Set PIN
  • Activate Card
  • Block Card
  • Unblock Card
  • Cancel Card
  • Get Card by ID
  • Get All Cards
card
Generate PIN Tokengenerate_pin_token
Set PINcard_pin_set
Set Preferencescard_preference
Get Unmasked Card Detailscard_details
  • Get All Transactions
  • Get Card Transaction by ID
card_transactions

Card Object

Shown below is a sample card object.

{
  "id": "car_EQ3wjIduPdCY4mpSD5YZXxQe0",
  "object": "card",
  "type": "physical",
  "account_id": "sa_eKBQOVPWFkpuR4Jx1vQbrSe81",
  "kit_id": "8835962444",
  "last_4": "6115",
  "status": "issued",
  "card_category": "debit",
  "name_on_card": "Anil Reddy",
  "mobile_number": "9000001363",
  "is_sandbox": true,
  "created_at": 1662027016,
  "shipping_address": {
    "type": "communication",
    "address": "221B Baker Street, Marylebone Rd,",
    "landmark": "Next to Wollaton Hall",
    "city": "Bangalore",
    "state_code": "KA",
    "postal_code": "560005"
  },
  "name_on_card": "Anil Reddy",
  "card_category": "debit",
  "is_pin_set": false
}

The table below lists the various parameters returned as part of the card object.

ParameterTypeDescription
idstringUnique identifier of the card in the ZWITCH database.

Example: car_R3vZeT6beATdmgD58m1Rcvavf
objectstringAPI object that is returned.

Possible value: card
typestringThe type of card created.

Possible value: physical
account_idstringUnique identifier of the account for which the card is issued.

For example: sa_jdQxHOm32n6FXMISltehEKs0m
kit_idstringUnique identifier of the card kit issued to the customer.

For example: 4744857655
last_4stringLast 4 digits of the card.

For example: 1234
statusstringCard status.

Possible values:
  • issued: Card has been successfully created and shipped to the customer.
  • active: Card has been successfully activated and can be used for transactions.
  • blocked: Card has been blocked and cannot be used for transactions. Unblock the card to use it for transactions.
  • canceled: Card has been canceled. This is a terminal state of a card. Once canceled, a card cannot be re-activated.
card_categorystringCard category.

Possible value: debit
name_on_cardstringName printed on the card.

Maximum 18 characters.

Example: Anil Reddy

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • .
  • /
  • \
  • -
  • _
  • ,
  • (
  • )
  • '
mobile_numberstringMobile number linked to the account for which the card was issued.

Example: 9876543210
is_sandboxstringThe mode in which the API was triggered.

Possible values:
  • true: API was triggered in sandbox mode.
  • false: API was triggered in live mode.
shipping_addressobjectObject that contains the shipping address linked to the account for which the card was issued.

Learn more about the shipping_address child object.
created_atinteger Unix timestamp when the create card request was received by ZWITCH.

Example: 1640179951
is_pin_setbooleanPossible values:
  • true: Card pin is successfully set.
  • false: Card pin is not set.

[Child Object] Shipping Address

Shown below is a sample shipping_address object. This object is part of the card object.

ParameterTypeDescription
typestringShipping address type.

Possible value: communication
addressstringAddress where the card will be shipped.

Example: 221B Baker Street
landmarkstringLandmark for the address where the card will be shipped.

Example: Next to Wollaton Hall
citystringCity where the card will be shipped.

Example: Bangalore
state_codestringState code where the card will be shipped.

Example: KA
postal_codestringPostal code where the address will be shipped.

Example: 560005

Generate PIN Token Object

Shown below is a sample generate_pin_token object.

{
  "id": "pt_db7ca20c268045f6bcdb27af064c19c4",
  "object": "generate_pin_token",
  "public_key": "hbv87educbe7889w09i-0qwid90qwfh8wehbfc79we9l",
  "card_id": "car_srVIESGzQ4PUCel1xNJg004gb",
  "is_sandbox": true,
  "created_at": 728728291,
  "expires_at": 1641883972
}

The table below lists the various parameters returned as part of the generate_pin_token object.

ParameterTypeDescription
idstringUnique identifier of the PIN token generated.

Example: pt_db7ca20c268045f6bcdb27af064c19c4
objectstringAPI object that is returned.

Possible value: generate_pin_token
public_keystringPublic key for the generated PIN token.

Example: hbv87educbe7889w09i-0qwid90qwfh8wehbfc79we9l

This is used to encrypt the PIN entered by the customer in the Set PIN API.
card_idstringUnique identifier of the card for which PIN token is generated.

Example: car_R3vZeT6beATdmgD58m1Rcvavf
is_sandboxbooleanThe mode in which the API was triggered.

Possible values:
  • true: API was triggered in sandbox mode.
  • false: API was triggered in live mode.
created_atintegerUnix timestamp when the generate PIN token request was received by ZWITCH.

Example: 1640179951
expires_atintegerUnix timestamp when the PIN token expires.

Example: 1640179951

Card PIN Set Object

Shown below is a sample card_pin_set object.

{
  "id": "pin_u4krGvTlacwmSltz1v1oJDUQ0",
  "object": "card_pin_set",
  "status": "success",
  "pin_token_id": "pt_llJoOBRanTP0491OfWt45cWEv"
}

The table below lists the various parameters returned as part of the card_pin_set object.

ParameterTypeDescription
idstringUnique identifier of the Set PIN API request.

Example: pin_u4krGvTlacwmSltz1v1oJDUQ0
objectstringAPI object that is returned.

Possible value: card_pin_set
statusstringStatus of the Set PIN request.

Possible value: success
pin_token_idstringUnique identifier of the PIN token generated in the Generate PIN Token API.

Example: pt_db7ca20c268045f6bcdb27af064c19c4

Card Preferences Object

Shown below is a sample card_preference object.

{
  "id": "crdpf_77656756565rt6rftyf6",
  "object": "card_preference",
  "card_id": "car_srVIESGzQ4PUCel1xNJg004gb",
  "type": "physical",
  "account_id": "sa_aeO72rc0pWy9bubqWEhNRD7SJ",
  "kit_id": "3221782859",
  "status": "active",
  "last_4": "1410",
  "preferences": {
    "transaction_modes": {
      "contactless": false,
      "atm": true,
      "pos": true,
      "ecom": true,
      "international": false
    },
    "limit_config": [
      {
        "txn_type": "atm",
        "max_amount": 1000
      },
      {
        "txn_type": "ecom",
        "max_amount": 1000
      },
      {
        "txn_type": "pos",
        "max_amount": 1000
      }
    ]
  },
  "created_at": 1646638384,
  "is_sandbox": true
}

The table below lists the various parameters returned as part of the card_preference object.

ParameterTypeDescription
idstringUnique identifier of the card preference in the ZWITCH database.

Example: crpf_77656756565rt6rftyf6
objectstringAPI object that is returned.

Possible value: card_preference
card_idstringUnique identifier of the card for which PIN token is generated.

Example: car_R3vZeT6beATdmgD58m1Rcvavf
typestringCard type.

Possible value: physical
account_idstringUnique identifier of the account for which the card was issued.

For example: sa_aeO72rc0pWy9bubqWEhNRD7SJ
kit_idstringUnique identifier of the card kit issued to the customer.

For example: 3221782859
statusstringCard status.

Possible values:
  • issued: Card has been successfully created and shipped to the customer.
  • active: Card has been successfully activated and can be used for transactions.
  • blocked: Card has been blocked and cannot be used for transactions. Unblock the card to use it for transactions.
  • canceled: Card has been canceled. This is a terminal state of a card. Once canceled, a card cannot be re-activated.
last_4stringLast 4 digits of the card.

For example: 1410
preferencesobjectVarious preferences available for the card.

Possible child objects:
created_atstringUnix timestamp when the set preferences request was received by ZWITCH.

Example: 1640179951
is_sandboxstringThe mode in which the API was triggered.

Possible values:
  • true: API was triggered in sandbox mode.
  • false: API was triggered in live mode.

[Child Object] Preferences.Transaction Modes

The table below lists the various parameters available in the preferences.transaction_modes object.

ParameterTypeDescription
contactlessbooleanPossible values:
  • true: Contactless payments are enabled for the card.
  • false: Contactless payments are disabled for the card.
atmbooleanPossible values:
  • true: ATM withdrawals are enabled for the card.
  • false: ATM withdrawals are disabled for the card.
posbooleanPossible values:
  • true: POS payments are enabled for the card.
  • false: POS payments are disabled for the card.
ecombooleanPossible values:
  • true: ECOM payments are enabled for the card.
  • false: ECOM payments are disabled for the card.
internationalbooleanPossible values:
  • true: International payments are enabled for the card.
  • false: International payments are disabled for the card.

[Child Object] Preferences.Limit Config

The table below lists the various parameters available in the preferences.limit_config object.

ParameterTypeDescription
txn_typestringTransaction type for which you want to set transaction limit.

Possible values:
  • atm
  • ecom
  • pos
max_amountintegerMaximum transaction limit for the selected transaction mode.

Example: 100000

Card Details Object

Shown below is a sample card_details object.

{
  "id": "car_aDmvF0TUQvsy4kHIjc5jZ01q4",
  "object": "card_details",
  "type": "physical",
  "account_id": "sa_eKBQOVPWFkpuR4Jx1vQbrSe81",
  "kit_id": "5363315288",
  "last_4": "7207",
  "status": "active",
  "is_sandbox": true,
  "card_number": "4918240000001920",
  "expiry_date": "11/2025",
  "card_category": "debit",
  "name_on_card": "Anil Reddy",
  "cvv": "161",
  "is_pin_set": false
  "created_at": 1659447962
}

The table below lists the various parameters returned as part of the card_details object.

ParameterTypeDescription
idstringUnique identifier of the card in the ZWITCH database.

Example: car_R3vZeT6beATdmgD58m1Rcvavf
objectstringAPI object that is returned.

Possible value: card_details
typestringThe type of card created.

Possible value: physical
account_idstringUnique identifier of the account for which the card is issued.

For example: cra_aeO72rc0pWy9bubqWEhNRD7SJ
kit_idstringUnique identifier of the card kit issued to the customer.

For example: 3221782859
last_4stringLast 4 digits of the card.

For example: 1234
statusstringCard status.

Possible values:
  • issued: Card has been successfully created and shipped to the customer.
  • active: Card has been successfully activated and can be used for transactions.
  • blocked: Card has been blocked and cannot be used for transactions. Unblock the card to use it for transactions.
  • canceled: Card has been canceled. This is a terminal state of a card. Once canceled, a card cannot be re-activated.
is_sandboxbooleanThe mode in which the API was triggered.

Possible values:
  • true: API was triggered in sandbox mode.
  • false: API was triggered in live mode.
card_numberstringUnmasked card number.

Example: 1234567890123456
expiry_datestringUnmasked expiry month and year for the card.

Example: 12/2030
card_categorystringCard category.

Possible value: debit
name_on_cardstringName printed on the card.

Example: Anil Reddy
cvvstringUnmasked card CVV.

Example: 000
is_pin_setbooleanPossible values:
  • true: Card pin is successfully set.
  • false: Card pin is not set.
created_atinteger Unix timestamp when the create card request was received by ZWITCH.

Example: 1640179951

Card Transactions Object

Shown below is a sample card_transactions object.

{
"id": "cartxn_iEFCp60cvTegyUYvaTk7WjTSk",
"card_id": "car_bp4LmepQSuPo74qRroJzJBcgn",
"card_category": "credit",
"object": "card_transactions",
"account_id": "cra_QNSFkjBa1xcm2CkqjoD37uLGL",
"transaction_type": "reversal",
"status": "pending",
"transaction_details": {
"merchant_name": "ISAC Happay/Sydney/NSW/AUS",
"amount": 111,
"rrn": "202209141008",
"mode": "credit",
"channel": "pos"
},
"failure_details": {},
"reversal_details": {
"original_transaction_id": "cartxn_Q6ix76g3NnnZjh0sqZ5aNmLY3",
"amount": 111
},
"mobile_number": "8210374301",
"created_at": 1663150767,
"updated_at": 1663150767,
"is_sandbox": false
}

The table below lists the various parameters returned as part of the card_transactions object.

ParameterTypeDescription
idstringUnique identifier of the transaction in the ZWITCH database.

Example: cartxn_iEFCp60cvTegyUYvaTk7WjTSk
card_idstringUnique identifier of the card in the ZWITCH database.

Example: car_bp4LmepQSuPo74qRroJzJBcgn
card_categorystringThe card category used for the transaction.

Possible values:
  • debit
  • credit
  • prepaid
objectstringAPI object returned.

Possible value: card_transactions
account_idstringUnique identifier of the account for which the card is issued.

For example: cra_QNSFkjBa1xcm2CkqjoD37uLGL
transaction_typestringType of transaction.

Possible values:
  • debit
  • credit
  • reversal
statusstringThe transaction statuses.

Possible values:
  • pending
  • success
  • failed
  • reversed
transaction_detailsobjectObject that contains details of the transaction.

Learn more about the transaction_details child object.
failure_detailsobjectObject that contains reason why the transaction failed.

Learn more about the failure_details child object.
reversal_detailsobjectObject that contains details of the reversal transaction.

Learn more about the reversal_details child object.
mobile_numberstringMobile number linked to the account for which the card was issued.

Example: 9876543210
created_atintegerUnix timestamp when the transaction was received by ZWITCH.

Example: 1640179951
updated_atintegerUnix timestamp when the status of the transaction changed.

Example: 1640179951
is_sandboxbooleanThe mode in which the API was triggered.

Possible values:
  • true: API was triggered in sandbox mode.
  • false: API was triggered in live mode.

Transaction Details Child Object

The table below contains details of the transaction_details child object.

ParameterTypeDescription
merchant_namestringMerchant's name where the card was used.

Example: Anil Reddy Enterprises
amountintegerAmount debited.

Example: 1000
rrnstringUnique identifier of the transaction in the bank database.

Example: 123456789012
modestringThe type of transaction that was done.

Possible values:
  • credit
  • debit
  • balance_enquiry
channelstringThe channel used to carry out the transaction.

Possible values:
  • pos
  • ecom
  • atm
  • contactless

Failure Details Child Object

The table below contains details of the failure_details child object.

ParameterTypeDescription
reasonstringReason the transaction failed.

Example: Invalid OTP
messagestringDetails why the transaction failed.

Example: You have entered an incorrect OTP. You have 2 attempts remaining

Reversal Details Child Object

The table below contains details of the reversal_details child object.

ParameterTypeDescription
original_transaction_idstringUnique identifier of the original transaction that is being reversed.

Example: cartxn_iEFCp60cvTegyUYvaTk7WjTSk
amountintegerAmount reversed.

Example: 1000