Objects

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

Cards APIs	Response Object
Create Cards Set PIN Activate Card Block Card Unblock Card Cancel Card Get Card by ID Get All Cards	`card`
Generate PIN Token	`generate_pin_token`
Set PIN	`card_pin_set`
Set Preferences	`card_preference`
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.

Parameter	Type	Description
id	`string`	Unique identifier of the card in the ZWITCH database. Example: `car_R3vZeT6beATdmgD58m1Rcvavf`
object	`string`	API object that is returned. Possible value: `card`
type	`string`	The type of card created. Possible value: `physical`
account_id	`string`	Unique identifier of the account for which the card is issued. For example: `sa_jdQxHOm32n6FXMISltehEKs0m`
kit_id	`string`	Unique identifier of the card kit issued to the customer. For example: `4744857655`
last_4	`string`	Last 4 digits of the card. For example: `1234`
status	`string`	Card 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_category	`string`	Card category. Possible value: `debit`
name_on_card	`string`	Name printed on the card. Maximum 18 characters. Example: `Anil Reddy` Supported characters: `A-Z` `a-z` `0-9` `.` `/` `\` `-` `_` `,` `(` `)`
mobile_number	`string`	Mobile number linked to the account for which the card was issued. Example: `9876543210`
is_sandbox	`string`	The mode in which the API was triggered. Possible values: `true`: API was triggered in sandbox mode. `false`: API was triggered in live mode.
shipping_address	`object`	Object that contains the shipping address linked to the account for which the card was issued. Learn more about the shipping_address child object.
created_at	`integer`	Unix timestamp when the create card request was received by ZWITCH. Example: `1640179951`
is_pin_set	`boolean`	Possible 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.

Parameter	Type	Description
type	`string`	Shipping address type. Possible value: `communication`
address	`string`	Address where the card will be shipped. Example: `221B Baker Street`
landmark	`string`	Landmark for the address where the card will be shipped. Example: `Next to Wollaton Hall`
city	`string`	City where the card will be shipped. Example: `Bangalore`
state_code	`string`	State code where the card will be shipped. Example: `KA`
postal_code	`string`	Postal 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.

Parameter	Type	Description
id	`string`	Unique identifier of the PIN token generated. Example: `pt_db7ca20c268045f6bcdb27af064c19c4`
object	`string`	API object that is returned. Possible value: `generate_pin_token`
public_key	`string`	Public 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_id	`string`	Unique identifier of the card for which PIN token is generated. Example: `car_R3vZeT6beATdmgD58m1Rcvavf`
is_sandbox	`boolean`	The mode in which the API was triggered. Possible values: `true`: API was triggered in sandbox mode. `false`: API was triggered in live mode.
created_at	`integer`	Unix timestamp when the generate PIN token request was received by ZWITCH. Example: `1640179951`
expires_at	`integer`	Unix 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.

Parameter	Type	Description
id	`string`	Unique identifier of the Set PIN API request. Example: `pin_u4krGvTlacwmSltz1v1oJDUQ0`
object	`string`	API object that is returned. Possible value: `card_pin_set`
status	`string`	Status of the Set PIN request. Possible value: `success`
pin_token_id	`string`	Unique 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.

Parameter	Type	Description
id	`string`	Unique identifier of the card preference in the ZWITCH database. Example: `crpf_77656756565rt6rftyf6`
object	`string`	API object that is returned. Possible value: `card_preference`
card_id	`string`	Unique identifier of the card for which PIN token is generated. Example: `car_R3vZeT6beATdmgD58m1Rcvavf`
type	`string`	Card type. Possible value: `physical`
account_id	`string`	Unique identifier of the account for which the card was issued. For example: `sa_aeO72rc0pWy9bubqWEhNRD7SJ`
kit_id	`string`	Unique identifier of the card kit issued to the customer. For example: `3221782859`
status	`string`	Card 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_4	`string`	Last 4 digits of the card. For example: `1410`
preferences	`object`	Various preferences available for the card. Possible child objects: `transaction_modes`: Learn more about the preferences.transaction_modes child object. `limit_config`: Learn more about the preferences.limit_config child object.
created_at	`string`	Unix timestamp when the set preferences request was received by ZWITCH. Example: `1640179951`
is_sandbox	`string`	The 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.

Parameter	Type	Description
contactless	`boolean`	Possible values: `true`: Contactless payments are enabled for the card. `false`: Contactless payments are disabled for the card.
atm	`boolean`	Possible values: `true`: ATM withdrawals are enabled for the card. `false`: ATM withdrawals are disabled for the card.
pos	`boolean`	Possible values: `true`: POS payments are enabled for the card. `false`: POS payments are disabled for the card.
ecom	`boolean`	Possible values: `true`: ECOM payments are enabled for the card. `false`: ECOM payments are disabled for the card.
international	`boolean`	Possible 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.

Parameter	Type	Description
txn_type	`string`	Transaction type for which you want to set transaction limit. Possible values: `atm` `ecom` `pos`
max_amount	`integer`	Maximum transaction limit for the selected transaction mode. Example: `100000`

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.

Parameter	Type	Description
id	`string`	Unique identifier of the transaction in the ZWITCH database. Example: `cartxn_iEFCp60cvTegyUYvaTk7WjTSk`
card_id	`string`	Unique identifier of the card in the ZWITCH database. Example: `car_bp4LmepQSuPo74qRroJzJBcgn`
card_category	`string`	The card category used for the transaction. Possible values: `debit` `credit` `prepaid`
object	`string`	API object returned. Possible value: `card_transactions`
account_id	`string`	Unique identifier of the account for which the card is issued. For example: `cra_QNSFkjBa1xcm2CkqjoD37uLGL`
transaction_type	`string`	Type of transaction. Possible values: `debit` `credit` `reversal`
status	`string`	The transaction statuses. Possible values: `pending` `success` `failed` `reversed`
transaction_details	`object`	Object that contains details of the transaction. Learn more about the transaction_details child object.
failure_details	`object`	Object that contains reason why the transaction failed. Learn more about the failure_details child object.
reversal_details	`object`	Object that contains details of the reversal transaction. Learn more about the reversal_details child object.
mobile_number	`string`	Mobile number linked to the account for which the card was issued. Example: `9876543210`
created_at	`integer`	Unix timestamp when the transaction was received by ZWITCH. Example: `1640179951`
updated_at	`integer`	Unix timestamp when the status of the transaction changed. Example: `1640179951`
is_sandbox	`boolean`	The 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.

Parameter	Type	Description
merchant_name	`string`	Merchant's name where the card was used. Example: `Anil Reddy Enterprises`
amount	`integer`	Amount debited. Example: `1000`
rrn	`string`	Unique identifier of the transaction in the bank database. Example: `123456789012`
mode	`string`	The type of transaction that was done. Possible values: `credit` `debit` `balance_enquiry`
channel	`string`	The 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.

Parameter	Type	Description
reason	`string`	Reason the transaction failed. Example: `Invalid OTP`
message	`string`	Details 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.

Parameter	Type	Description
original_transaction_id	`string`	Unique identifier of the original transaction that is being reversed. Example: `cartxn_iEFCp60cvTegyUYvaTk7WjTSk`
amount	`integer`	Amount reversed. Example: `1000`