Product Docs
Community

Manage Debit Cards

Learn how to manage cards using ZWITCH APIs.

Suggest Edits

Listed below are the various actions available to manage cards.

  • Set Card Preference: Enable and disable transaction modes.

  • Reset Card PIN: Allow the cardholder to reset their debit card PIN in case they forgot their PIN or want to change it for security reasons.

  • Block and Unblock Card: Allow the cardholder to block and unblock their debit card as per their needs. A debit card can be blocked in case it is lost or stolen.

  • Cancel Card: Cancel a debit card. This is a terminal state. Once canceled, the debit card cannot be reactivated.

Set Card Preferences

The Set Card Preference API allows the cardholder to enable or disable the supported transactions mode for their debit card. Currently, cards issued via ZWITCH support the below transaction modes.

  • contactless: Use the debit card for transactions at contactless payment terminals.
  • atm: Use the debit card for transactions at ATMs.
  • pos: Use the debit card for transactions at merchant POS terminals.
  • ecom: Use the debit card for transactions on eCommerce websites.

Use the below endpoint to set card preferences.

POST: https://api.zwitch.io/v1/cards/{card_id}/preferences

Below is a sample request and response for the Set Card Preference API.

{
  "transaction_modes": {
    "contactless": true,
    "atm": true,
    "pos": true,
    "ecom": true,
    "international": true
  },
  "limit_config": [
    {
      "txn_type": "atm",
      "max_amount": 1000
    },
    {
      "txn_type": "ecom",
      "max_amount": 1000
    },
    {
      "txn_type": "pos",
      "max_amount": 1000
    }
  ]
}

{
  "id": "crdpf_x4liTDMSgodG0KPfP50NNTTEY",
  "object": "card_preference",
  "card_id": "car_srVIESGzQ4PUCel1xNJg004gb",
  "type": "physical",
  "account_id": "cra_aeO72rc0pWy9bubqWEhNRD7SJ",
  "kit_id": "00000000001",
  "status": "active",
  "last_4": "0000",
  "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
}

Refer to our API guide for more details about the Set Card Preference API.

Reset Card PIN

A card's PIN might need to be reset in case it is lost or forgotten or for security reasons.

A debit card's PIN can be reset in 3 steps.

542

Reset Card PIN Workflow

Follow the below steps to rest a debit card's PIN.

  1. Generate PIN Token

  2. Generate Encrypted PIN

  3. Set PIN

📘

Note

The reset PIN process can be canceled at any step. If the process is canceled, the card reverts to the previously set PIN.

1. Generate PIN Token

The first step to setting a PIN for a card is to generate a PIN token. The Generate PIN Token API response contains 2 important parameters, public_key and id. These parameters are used to generate the encrypted PIN and set the PIN respectively.

Use the below endpoint to generate a PIN token.

POST: https://api.zwitch.io/v1/cards/{card_id}/generate-pin-token

Below is a sample response for the Generate PIN Token API.

{
  "id": "pt_db7ca20c268045f6bcdb27af064c19c4",
  "object": "generate_pin_token",
  "public_key": "hbv87educbe7889w09i-0qwid90qwfh8wehbfc79we9l",
  "card_id": "car_srVIESGzQ4PUCel1xNJg004gb",
  "type": "physical",
  "account_id": "sa_aeO72rc0pWy9bubqWEhNRD7SJ",
  "kit_id": "00000000001",
  "card_status": "issued",
  "cancel_reason": null,
  "is_pin_set": false,
  "last_4": "0000",
  "is_sandbox": true,
  "expires_at": 1641883972,
  "created_at": 728728291
}

Refer to our API guide for more details about the Generate PIN Token API.

2. Generate Encrypted PIN

This step has to be done on your server.

After generating the PIN token, use the below values to generate the encrypted PIN.

  • SHA256 algorithm.
  • Values received against the public_key parameters in the Generate PIN Token API response.
  • PIN entered by the cardholder.

📘

Use only SHA256

Use only SHA256 to generate the encrypted PIN. Any other encryption method will lead to errors.

Use the below sample code to generate the encrypted PIN.

from Crypto.PublicKey import RSA
from Crypto.Cipher import PKCS1_OAEP
from Crypto.Hash import SHA256
import base64


def generate_encrypted_pin(public_key, pin):
  
  public_key = base64.b64decode(public_key)
  key = RSA.importKey(public_key)
  encryptor = PKCS1_OAEP.new(key, SHA256)
  
  encrypted_pin = encryptor.encrypt(pin.encode('utf-8'))
  
  return base64.b64encode(encrypted_pin)

encryptedPin = generate_encrypted_pin("public_key", "pin")
print(encryptedPin)

<?php
//composer require phpseclib/phpseclib:~2.0 -> Install composer first
require __DIR__ . '/vendor/autoload.php';

use phpseclib\Crypt\RSA;
use phpseclib\Crypt\AES;
use phpseclib\File\X509;


$public_key = new RSA();
$public_key->loadKey(base64_decode($your_pin_encryption_key));

$public_key->setEncryptionMode(RSA::ENCRYPTION_OAEP);
$public_key->setHash('sha256');
$public_key->setMGFHash('sha256');
$pin = 'your pin';

$encrypted = $public_key->encrypt($pin);

    
    $encrypted=base64_encode($encrypted);



//$encrypted is final result which you will pass in 'pin' paramater
?>

📘

[Python Only] Install PIP3 Crypto Library

Ensure you have the Python Crypto library installed on your system before using the above python script.

Use the below code snippet to install the Python Crypto library.

pip3 install crypto

3. Set PIN

After generating the encrypted PIN, use the Set PIN API to set the PIN for the card. This PIN is required to carry out transactions such as ATM and POS transactions.

Use the below endpoint to set the PIN for a card.

POST: https://api.zwitch.io/v1/cards/{card_id}/set-pin

Below is a sample request and response for the Set PIN API.

{
  "pin_token_id": "pt_db7ca20c268045f6bcdb27af064c19c4",
  "pin": "kad667igk2=ask-=b7ca20c268045f6bcdb27af064c19c4"
}

{
  "id": "car_R3vZeT6beATdmgD58m1Rcvavf",
  "object": "card",
  "type": "physical",
  "account_id": "sa_aeO72rc0pWy9bubqWEhNRD7SJ",
  "kit_id": "00000000001",
  "status": "issued",
  "cancel_reason": null,
  "is_pin_set": false,
  "last_4": "0000",
  "is_sandbox": true,
  "created_at": 1646305675
}

The table below lists the request parameters for the Set PIN API.

ParameterTypeDescription
pin_token_idstringPass the value received against the id parameter in the Generate PIN Token API response here.

Example: pt_db7ca20c268045f6bcdb27af064c19c4
pinstringPass the encrypted PIN generated in the previous here.

Example: kad667igk2=ask-=b7ca20c268045f6bcdb27af064c19c4

Refer to our API guide for more details about the Set PIN API.

Block and Unblock a Card

A card might need to be blocked in case it is lost or stolen. Upon recovery of the card, the card would need to be unblocked.

Block Card

Use the below endpoint to block a debit card.

POST: https://api.zwitch.io/v1/cards/{card_id}/block

Below is a sample response for the Block Card API.

{
  "id": "car_R3vZeT6beATdmgD58m1Rcvavf",
  "object": "card",
  "type": "physical",
  "account_id": "sa_aeO72rc0pWy9bubqWEhNRD7SJ",
  "kit_id": "00000000001",
  "status": "blocked",
  "cancel_reason": null,
  "is_pin_set": true,
  "last_4": "0000",
  "is_sandbox": true,
  "created_at": 1646305675
}

Refer to our API guide for more details about the Block Card API.

Unblock Card

Use the below endpoint to unblock a debit card.

POST: https://api.zwitch.io/v1/cards/{card_id}/unblock

Below is a sample response for the Unblock Card API.

{
  "id": "car_R3vZeT6beATdmgD58m1Rcvavf",
  "object": "card",
  "type": "physical",
  "account_id": "sa_aeO72rc0pWy9bubqWEhNRD7SJ",
  "kit_id": "00000000001",
  "status": "active",
  "cancel_reason": null,
  "is_pin_set": true,
  "last_4": "0000",
  "is_sandbox": true,
  "created_at": 1646305675
}

Refer to our API guide for more details about the Unblock Card API.

Cancel a Card

In case a debit card is damaged or is lost and never found, the card needs to be canceled before a new card is issued to the cardholder.

A canceled card cannot be reactivated. This is a terminal state.

Use the below endpoint to cancel a debit card.

POST: https://api.zwitch.io/v1/cards/{card_id}/cancel

Below is a sample request and response for the Cancel Card API.

{
  "cancel_reason": "lost"
}

{
  "id": "car_R3vZeT6beATdmgD58m1Rcvavf",
  "object": "card",
  "type": "physical",
  "account_id": "cra_aeO72rc0pWy9bubqWEhNRD7SJ",
  "kit_id": "00000000001",
  "status": "canceled",
  "cancel_reason": "lost/terminated/others/",
  "is_pin_set": true/false,
  "last_4": "0000",
  "expiry_month": "12", ///not for MVP
  "expiry_year": "2022", ///not for MVP
  "is_sandbox": true,
  "created_at": 1646305675,
  "updated_at": 1646305676 ///not for MVP
}

Refer to our API guide for more details about the Cancel Card API.

Updated over 1 year ago