GuidesAPI ReferenceChangelog
Log In
Guides
Start typing to search…

Assign Physical Cards and Card Activation - via API

Assign Card - Request example

Assign Card API Doc

{
  "cardholder_id": "4438b25d-caa7-4dcf-a8e0-970f05a7bf31",
  "card_number": "4096360800121514",
  "card_currency": "SGD",
  "card_mode": "SINGLE"
}

Assign Card - Response example

{
    "card_order_id": "07ad04df-39dd-44a1-bbc5-15b2eff6f709",
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "card_status": "PENDING",
    "order_status": "PENDING",
    "create_time": "2025-07-27T21:00:05+08:00",
    "risk_controls": {}
}

  • After binding the card number to the cardholder, the system will trigger the following webhooks: card.activation.code and card.create.succeeded

  • Additionally, an email notification will be sent (configurable to be sent to either the cardholder's email or the institution's email, with the option to disable).

  • The activation code has no expiration date.

Webhook example: card.activation.code

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.activation.code",
  "event_id": "759e6599-d3cc-415e-94e7-dfdd5d3401d1",
  "source_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "data": {
    "activation_code": "81534005",
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "card_number": "40963608****1514"
  }
}

Webhook example: card.create.succeeded

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.create.succeeded",
  "event_id": "4acf7662-2e56-4102-ac5c-0c79c080990f",
  "source_id": "07ad04df-39dd-44a1-bbc5-15b2eff6f709",
  "data": {
    "card_available_balance": "0",
    "card_bin": "40963608",
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "card_number": "40963608****1514",
    "card_product_id": "b1963667-d688-414b-90df-467c30d3b4af",
    "card_scheme": "VISA",
    "card_status": "PENDING",
    "cardholder": {
      "cardholder_id": "4438b25d-caa7-4dcf-a8e0-970f05a7bf31",
      "cardholder_status": "SUCCESS",
      "create_time": "2025-05-27T13:54:11+08:00",
      "email": "[email protected]",
      "first_name": "marshalllll",
      "last_name": "hu"
    },
    "form_factor": "PHYSICAL",
    "metadata": {},
    "mode_type": "SINGLE",
    "risk_control": {
      "allow_3ds_transactions": "Y"
    },
    "spending_limits": [
      {
        "amount": "1280",
        "interval": "PER_TRANSACTION"
      }
    ]
  }
}

Email notification example:

  • Upon receiving the activation code, utilize the Activate Card API to activate the card and set the PIN.

  • The PIN must consist of exactly 6 digits.

Activate Card - Request example

{
  "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "activation_code": "81534005",
  "pin": "123456"
}

Webhook example: card.activation.status

  • Card Activation Status Webhook Doc

  • Upon successful card activation, a webhook notification for card.activation.status and an email confirmation will be sent (configurable to be sent to either the cardholder's email or the institution's email, with the option to disable).

{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.activation.status",
  "event_id": "bd0a312b-25a3-46aa-b553-6b360d3a6ba7",
  "source_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "data": {
    "activation_status": "Activated",
    "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
    "card_number": "40963608****1514"
  }
}

You can call the Reset Card PIN API to reset the card PIN.

  • Reset Card PIN API Doc

  • The result of the PIN change will be returned synchronously, and NO additional webhook notification will be sent.

{
  "card_id": "b2c1b725-d8f1-4fbb-88a1-41bf9ffc8ead",
  "pin": "654321"
}

Related:

Updated 3 days ago

What’s Next