Zoqq Webhook API Documentation

Integrating the webhook service enables end users to receive notifications and updates regarding their account activity, transactions, security alerts, and other pertinent information. This integration ensures that users are promptly informed about important events related to their accounts.

🔄 Webhook Management

📥 Get All Webhooks

This returns a list of all webhooks associated with a program.

GET {{baseUrl}}/getallwebhooks

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

Content-Type string required

Must be application/json

🔍 Query Parameters

program_code string required

Shared Product ID by Zoqq

Response Example

{
  "data": [
    {
      "event_description": "Onboarding",
      "event_name": "account.submitted",
      "program_code": "program-code"
    },
    {
      "event_description": "Currency Conversion",
      "event_name": "conversion.cancelled",
      "program_code": "program-code"
    },
    {
      "event_description": "Currency Conversion",
      "event_name": "conversion.overdue",
      "program_code": "program-code"
    },
    {
      "event_description": "Currency Conversion",
      "event_name": "conversion.scheduled",
      "program_code": "program-code"
    },
    {
      "event_description": "Currency Conversion",
      "event_name": "conversion.settled",
      "program_code": "program-code"
    },
    {
      "event_description": "Virtual Account Creation",
      "event_name": "ga.new",
      "program_code": "program-code"
    },
    {
      "event_description": "Card Status",
      "event_name": "issuing.card.active",
      "program_code": "program-code"
    },
    {
      "event_description": "Card Status",
      "event_name": "issuing.card.blocked",
      "program_code": "program-code"
    },
    {
      "event_description": "Cardholder Status",
      "event_name": "issuing.cardholder.pending",
      "program_code": "program-code"
    },
    {
      "event_description": "Cardholder Status",
      "event_name": "issuing.cardholder.ready",
      "program_code": "program-code"
    },
    {
      "event_description": "Card Transction",
      "event_name": "issuing.transaction.succeeded",
      "program_code": "program-code"
    },
    {
      "event_description": "Payout Transfer",
      "event_name": "payout.transfer.funding.funded",
      "program_code": "program-code"
    },
    {
      "event_description": "Request For Information",
      "event_name": "rfi.action_required",
      "program_code": "program-code"
    }
  ],
  "status": "success"
}

Subscribe to a webhook for a specific event.

POST {{baseUrl}}/api/subscribe

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

Content-Type string required

Must be application/json

📦 Request Body Parameters

event_name string required

Name of the event to subscribe

subscription_type string required

Subscription type ( w for webhook or n for notification )

agent_code string required

Shared Agent Code

subagent_code string required

Shared Sub Agent Code

program_code string required

Shared Product ID by Zoqq

company_code string required

Shared Company Code

created_by string required

Name of creator

webhook_url string conditional

Target URL to send event payloads

sender_email string conditional

Email address of the sender initiating the request

x-api-key string conditional

Shared X-API key by Zoqq

⚠️ Important Note on `subscription_type`

🔔 When subscription_type: "w" (Webhook)

You must provide these fields in request body:

webhook_url
x-api-key

sender_email is not required in the request body.

📩 When subscription_type: "n" (Email Notification)

You do not need to provide these fields in request body:

webhook_url
x-api-key

Provide sender_email only if your email ID has been whitelisted by Zoqq Support. Until then, all email notifications will be sent from Zoqq’s default system email.

📬 Sending Emails from Your Own Email ID

If you want notification emails to be sent from your own email address instead of Zoqq’s generic email, you must contact Zoqq Customer Support to whitelist your email ID.

Request Body for subscription_type: "w"

{
  "event_name": "{{event_name}}",
  "subscription_type": "w",  
  "agent_code": "{{agent_code}}",
  "subagent_code": "{{sub_agent_code}}",
  "program_code": "{{Shared ProductID By Zoqq}}",
  "company_code": "{{company_code}}",
  "created_by": "Test",
  "webhook_url": "{{webhook_url}}",
  "x_api_key": "{{Shared X-API key By Zoqq}}"
}

Request Body for subscription_type: "n"

{
  "event_name": "{{event_name}}",
  "subscription_type": "n",  
  "agent_code": "{{agent_code}}",
  "subagent_code": "{{sub_agent_code}}",
  "program_code": "{{Shared ProductID By Zoqq}}",
  "company_code": "{{company_code}}",
  "created_by": "Test"
}

Response Example

{
  {
    "message": "Webhook successfully subscribed",
    "status": "SUCCESS"
  }
}

📥 Retrieve Subscribed Webhook Details

Retrieves the details of all subscribed webhooks for a specific program.

POST {{baseUrl}}/api/subscribedwebhook

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

Content-Type string required

Must be application/json

📦 Request Body Parameters

agent_code string required

Shared Agent Code

subagent_code string required

Shared Sub Agent Code

🔍 Query Parameters

program_code string required

Shared Product ID by Zoqq

Response Example

[
  {
    "agent_code": "agent-code",
    "company_code": "company-code",
    "created_by": "Pabitra",
    "created_time": "Thu, 07 Aug 2025 09:34:19 GMT",
    "event_name": "account.submitted",
    "program_code": "program-code",
    "sender_email": "notification@zoqq.com",
    "sl_no": 1,
    "subagent_code": "sub-agent-code",
    "subscription_type": "n",
    "updated_by": null,
    "updated_time": "Thu, 07 Aug 2025 09:34:19 GMT",
    "webhook_url": "test",
    "x_api_key": "TEST"
  },
  {
    "agent_code": "agent-code",
    "company_code": "company-code",
    "created_by": "Pabitra",
    "created_time": "Thu, 07 Aug 2025 09:34:19 GMT",
    "event_name": "conversion.cancelled",
    "program_code": "program-code",
    "sender_email": "notification@zoqq.com",
    "sl_no": 2,
    "subagent_code": "sub-agent-code",
    "subscription_type": "n",
    "updated_by": null,
    "updated_time": "Thu, 07 Aug 2025 09:34:19 GMT",
    "webhook_url": "test",
    "x_api_key": "TEST"
  }
]

♻️ Update Webhook

This API is used to update an existing webhook configuration. It allows you to modify the subscription type, webhook URL, x-api-key, and sender email through the request body.

PATCH {{baseUrl}}/api/subscribe

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

Content-Type string required

Must be application/json

📦 Request Body Parameters

event_name string required

Name of the event subscribed

subscription_type string required

Subscription type ( w for webhook or n for notification )

agent_code string required

Shared Agent Code

subagent_code string required

Shared Sub Agent Code

program_code string required

Shared Product ID by Zoqq

company_code string required

Shared Company Code

webhook_url string conditional

Target URL to send event payloads

sender_email string conditional

Email address of the sender initiating the request

x-api-key string conditional

Shared X-API key by Zoqq

updated_by string required

User updating the webhook

Request Example

{
  "event_name": "{{event_name}}",
  "subscription_type": "w",
  "agent_code": "{{agent_code}}",
  "subagent_code": "{{sub_agent_code}}",
  "program_code": "{{Shared ProductID By Zoqq}}",
  "company_code": "{{company_code}}",
  "webhook_url": "{{webhook_url}}",
  "x_api_key":"{{Shared X-API key By Zoqq}}",
  "updated_by":"Test Admin"
}

Response Example

{
  "message": "Successfully Updated the webhook",
  "status": "SUCCESS"
}

❌ Delete Webhook

Delete an existing webhook subscription.

DELETE {{baseUrl}}/api/subscribe

📩 Request Headers

x-api-key string required

Shared X-API key by Zoqq

Content-Type string required

Must be application/json

📦 Request Body Parameters

event_name string required

Name of the event subscribed

agent_code string required

Shared Agent Code

subagent_code string required

Shared Sub Agent Code

program_code string required

Shared Product ID by Zoqq

company_code string required

Shared Company Code

Request Example

{
  "event_name": "{{event_name}}",
  "agent_code": "{{agent_code}}",
  "subagent_code": "{{sub_agent_code}}",
  "program_code": "{{Shared ProductID By Zoqq}}",
  "company_code": "{{company_code}}"
}

Response Example

{
  "message": "Successfully Deleted the webhook",
  "status": "SUCCESS"
}

📨 Webhook Events

1. Account Status

Account Submitted

Triggered when an account application is first submitted for verification.

Description

Sent when a new account application is submitted and awaiting verification.

📦 Event Details

id string

Unique event identifier.

name string

Event name: account.submitted.

account_id string

Unique identifier of the related account.

data object

Additional event payload. Empty object for this event.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "evt_UVU43_95Onav3lShzYmSVw",
  "name": "account.submitted",
  "account_id": "acct_wUwt_u52MDCIvG8KqbC1YA",
  "data": {},
  "created_at": "2025-04-23T06:16:35+0000",
  "version": "2025-02-14"
}

Account Active

Triggered when an account becomes active after successful verification.

Description

Sent when an account has completed verification and is now active for transactions.

📦 Event Details

id string

Unique event identifier.

name string

Event name: account.active.

account_id string

Unique identifier of the activated account.

data object

Event payload containing account-related details.

account_details object

Details of the activated account.

business_details object

Business information associated with the account.

address object

Primary registered business address.

address_line1 string

Address line 1.

suburb string

Suburb or locality.

state string

State or region.

postcode string

Postal or ZIP code.

country_code string

Country code (2-letter ISO 3166-2).

address_english object

English representation of the business address.

country_code string

Country code (2-letter ISO 3166-2).

postcode string

Postal or ZIP code.

as_trustee boolean

Indicates whether the business operates as a trustee.

business_address object

Alternate business address details.

address_line1 string

Business address line 1.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "evt_iLMoFQxuM4iEc3XPwIqxmw",
  "name": "account.active",
  "account_id": "acct_wUwt_u52MDCIvG8KqbC1YA",
  "data": {
    "account_details": {
      "business_details": {
        "address": {
          "address_line1": "3837 Violette Knolls",
          "suburb": "Fadelton",
          "country_code": "US",
          "postcode": "58888",
          "state": "FL"
        },
        "address_english": {
          "country_code": "US",
          "postcode": "58888"
        },
        "as_trustee": false,
        "business_address": {
          "address_line1": "44583 Gislason Trail"
        }
      }
    }
  },
  "created_at": "2025-04-23T06:16:35+0000",
  "version": "2025-02-14"
}

Account Suspended

Triggered when account verification fails or is suspended.

Description

Sent when an account fails verification or is suspended for compliance reasons.

📦 Event Details

id string

Unique event identifier.

name string

Event name: account.suspended.

account_id string

Unique identifier of the suspended account.

data object

Event payload containing suspension and account details.

account_details object

Details of the suspended account.

business_details object

Business information associated with the account.

address object

Primary registered business address.

address_line1 string

Address line 1.

suburb string

Suburb or locality.

state string

State or region.

postcode string

Postal or ZIP code.

country_code string

Country code (2-letter ISO 3166-2).

business_name string

Registered legal name of the business.

tax_id object

Business tax identification details.

number string

Tax identification number.

type string

Type of tax identifier (e.g., EIN).

status string

Current account status. Value: SUSPENDED.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "evt_l_NMv9_MPDGZqP-5Z9vHlw",
  "name": "account.suspended",
  "account_id": "acct_wUwt_u52MDCIvG8KqbC1YA",
  "data": {
    "account_details": {
      "business_details": {
        "address": {
          "address_line1": "44583 Gislason Trail",
          "suburb": "New Tryciaburgh",
          "country_code": "US",
          "postcode": "58888",
          "state": "FL"
        },
        "business_name": "Bartell and Sons US",
        "tax_id": {
          "number": "123456789",
          "type": "EIN"
        }
      }
    },
    "status": "SUSPENDED"
  },
  "created_at": "2025-04-23T09:46:48+0000",
  "version": "2025-02-14"
}

Account Action Required

Triggered when additional information is needed to complete account verification.

Description

Sent when the verification process cannot be completed without additional action or documentation from the user.

📦 Event Details

id string

Unique event identifier.

name string

Event name: rfi.action_required.

account_id string

Unique identifier of the account requiring action.

data object

Event payload containing RFI details.

id string

Unique identifier of the RFI request.

type string

Type of action required. Allowed values:

KYC – Know Your Customer documentation required
AML – Anti-Money Laundering verification
ADDRESS – Proof of address required
IDENTITY – Identity verification required

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "8be6af0f-f946-4b2d-ab4c-a04e66cfe82a",
  "name": "rfi.action_required",
  "account_id": "acct_5zJ0AJ2HMHKKvUGZf6os8w",
  "data": {
    "id": "89362bcb-0fbc-41ab-ae57-2cb7c3d8dbec",
    "type": "KYC"
  },
  "created_at": "2025-04-23T10:23:36+0000",
  "version": "2025-02-14"
}

2. Global Accounts

Global Account New

Triggered when a deposit is received via Global Account, pending settlement to wallet balance.

Description

Sent when a new deposit is received in a global account but hasn't yet been settled to the wallet balance.

📦 Event Details

id string

Unique event identifier.

name string

Event name: ga.new.

account_id string

Unique identifier of the account associated with the transaction.

data object

Event payload containing transaction details.

amount double

Transaction amount.

ccy string

Transaction currency (3-letter ISO-4217 code).

transaction_type string

Type of transaction. Value: DEPOSIT.

process_status string

Current processing status.
Status flow:
NEW → PENDING → SETTLED. May transition to FAILED if settlement fails.

settlement_info object

Settlement-related information.

beneficiary_account_number string

Beneficiary account number.

beneficiary_name string

Name of the beneficiary.

payer_name string

Name of the payer.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "b19b2529-3f6c-4a79-b575-c595a0043985_ga.new",
  "name": "ga.new",
  "account_id": "acct_hUiVInamMd68NDDm5VVmyA",
  "data": {
    "amount": 100.0,
    "ccy": "SGD",
    "transaction_type": "DEPOSIT",
    "process_status": "NEW",
    "settlement_info": {
      "beneficiary_account_number": "88520209770",
      "beneficiary_name": "Zoqq (Singapore) Pte Ltd",
      "payer_name": "JS"
    }
  },
  "created_at": "2025-04-28T12:06:45+0000",
  "version": "2025-02-14"
}

Balance Collection

Triggered when wallet balance increases due to a settled deposit from Global Account.

Description

Sent when funds from a Global Account deposit have been successfully settled and added to the wallet balance.

📦 Event Details

id string

Unique event identifier.

name string

Event name: balance.ga.top_up.

account_id string

Unique identifier of the account whose balance was updated.

data object

Event payload containing balance top-up details.

ccy string

Currency of the transaction (3-letter ISO-4217 code).

amount double

Top-up amount credited to the account.

balance double

Updated account balance after the top-up.

type string

Transaction type. Value: DEPOSIT.

transaction_reference object

Reference details associated with the deposit transaction.

deposit_id string

Unique identifier of the deposit transaction.

global_account_id string

Global account identifier linked to the deposit.

payer_name string

Name of the payer.

payer_bank_name string

Name of the payer’s bank.

reference string

Client-provided reference for the transaction.

created_at string

ISO 8601 timestamp indicating when the balance update occurred.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "d5429604-0f3e-3e60-9058-46f44e4552f5",
  "name": "balance.ga.top_up",
  "account_id": "acct_hUiVInamMd68NDDm5VVmyA",
  "data": {
    "ccy": "SGD",
    "amount": 100,
    "balance": 100,
    "type": "DEPOSIT",
    "transaction_reference": {
      "deposit_id": "b19b2529-3f6c-4a79-b575-c595a0043985",
      "global_account_id": "2a5f4d31-e290-4192-9746-61c862ba2d27",
      "payer_name": "JS",
      "payer_bank_name": "SBI"
    },
    "reference": "123",
    "created_at": "2025-04-28T12:06:45+0000"
  },
  "created_at": "2025-04-28T12:06:45+0000",
  "version": "2025-02-14"
}

3. Conversions

Conversion Scheduled

Triggered when a currency conversion has been successfully booked and scheduled for future settlement.

Description

Sent when a currency conversion request has been accepted and scheduled for execution on the specified conversion date.

📦 Event Details

id string

Unique event identifier.

name string

Event name: conversion.scheduled.

account_id string

Unique identifier of the account associated with the conversion.

data object

Event payload containing foreign exchange conversion details.

conversion_id string

Unique identifier of the conversion.

short_reference_id string

Human-readable short reference for the conversion.

status string

Current conversion status. Value: SCHEDULED.

currency_pair string

Currency pair involved in the conversion, represented using two (3-letter ISO-4217) currency codes concatenated together (e.g., USD + SGD → USDSGD).

client_rate double

FX rate applied to the conversion.

buy_currency string

Currency being bought (3-letter ISO-4217 code).

buy_amount double

Amount of currency being bought.

sell_currency string

Currency being sold (3-letter ISO-4217 code).

sell_amount double

Amount of currency being sold.

conversion_date string

Scheduled date for the conversion (ISO 8601 date format: YYYY-MM-DD).

settlement_cutoff_time string

ISO 8601 timestamp indicating the Cutoff time for settlement.

created_at string

ISO 8601 timestamp indicating when the conversion was created.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "0d549741-f460-4457-8f15-2965b7af108dSCHEDULED",
  "name": "conversion.scheduled",
  "account_id": "acct_i74Os0HwMhmqPw9ND12TRQ",
  "data": {
    "conversion_id": "0d549741-f460-4457-8f15-2965b7af108d",
    "short_reference_id": "C250429-5UBTP0F",
    "status": "SCHEDULED",
    "currency_pair": "USDSGD",
    "client_rate": 1.315168,
    "buy_currency": "USD",
    "buy_amount": 1,
    "sell_currency": "SGD",
    "sell_amount": 1.32,
    "conversion_date": "2025-04-29",
    "settlement_cutoff_time": "2025-04-29T09:55:59+0000",
    "created_at": "2025-04-29T09:55:59+0000"
  },
  "created_at": "2025-04-29T09:55:59+0000",
  "version": "2025-02-14"
}

Conversion Settled

Triggered when funds from a currency conversion have been successfully settled in the wallet.

Description

Sent when a scheduled currency conversion has been successfully executed and funds are available in the wallet.

📦 Event Details

id string

Unique event identifier.

name string

Event name: conversion.settled.

account_id string

Unique identifier of the account associated with the conversion.

data object

Event payload containing foreign exchange conversion details.

conversion_id string

Unique identifier of the conversion.

short_reference_id string

Human-readable short reference for the conversion.

status string

Current conversion status. Value: SETTLED.

currency_pair string

Currency pair involved in the conversion, represented using two (3-letter ISO-4217) currency codes concatenated together (e.g., USD + SGD → USDSGD).

client_rate double

FX rate applied to the conversion.

buy_currency string

Currency being bought (3-letter ISO-4217 code).

buy_amount double

Amount of currency being bought.

sell_currency string

Currency being sold (3-letter ISO-4217 code).

sell_amount double

Amount of currency being sold.

conversion_date string

Date on which the conversion was settled (ISO 8601 date format: YYYY-MM-DD).

updated_at string

ISO 8601 timestamp indicating when the conversion was settled.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "0d549741-f460-4457-8f15-2965b7af108dSETTLED",
  "name": "conversion.settled",
  "account_id": "acct_i74Os0HwMhmqPw9ND12TRQ",
  "data": {
    "conversion_id": "0d549741-f460-4457-8f15-2965b7af108d",
    "short_reference_id": "C250429-5UBTP0F",
    "status": "SETTLED",
    "currency_pair": "USDSGD",
    "client_rate": 1.315168,
    "buy_currency": "USD",
    "buy_amount": 1,
    "sell_currency": "SGD",
    "sell_amount": 1.32,
    "conversion_date": "2025-04-29",
    "updated_at": "2025-04-29T09:55:59+0000"
  },
  "created_at": "2025-04-29T09:55:59+0000",
  "version": "2025-02-14"
}

4. Deposits

Deposit Settled

Triggered when a deposit has been successfully processed and settled to the wallet balance.

Description

Sent when funds from a deposit have cleared all processing and are fully available in the wallet balance.

📦 Event Details

id string

Unique event identifier.

name string

Event name: deposit.settled.

account_id string

Unique identifier of the account associated with the deposit.

data object

Event payload containing deposit settlement details.

id string

Unique identifier of the deposit.

amount double

Deposit amount credited to the account.

currency string

Currency of the deposit (3-letter ISO-4217 code).

fee object

Fee charged for the deposit transaction, if any.

amount double

Fee amount applied to the deposit.

currency string

Currency of the fee (3-letter ISO-4217 code).

global_account_id string

Global account identifier linked to the deposit.

payer object

Details of the payer who initiated the deposit.

name string

Name of the payer.

provider_transaction_id string

Transaction identifier provided by the payment provider.

reference string

Client-provided reference for the deposit.

status string

Current deposit status. Value: SETTLED.

type string

Deposit method used. Value: BANK_TRANSFER.

settled_at long

Epoch timestamp (milliseconds) indicating when the deposit was settled.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "1a06397d-6919-40d7-98de-e10c66f250c1_deposit.settled",
  "name": "deposit.settled",
  "account_id": "acct_hUiVInamMd68NDDm5VVmyA",
  "data": {
    "amount": 50.0,
    "currency": "USD",
    "fee": {
      "amount": 0,
      "currency": "USD"
    },
    "global_account_id": "bc2669d5-9ae3-41a5-9589-f8c424c47da5",
    "id": "1a06397d-6919-40d7-98de-e10c66f250c1",
    "payer": {
      "name": "JS"
    },
    "provider_transaction_id": "5487287789",
    "reference": "123",
    "status": "SETTLED",
    "type": "BANK_TRANSFER",
    "settled_at": 1746006056378
  },
  "created_at": "2025-04-30T09:40:56+0000",
  "version": "2025-02-14"
}

Deposit Rejected

Triggered when a deposit has been rejected during processing by Zoqq or the clearing system.

Description

Sent when a deposit fails verification or is rejected by compliance checks, preventing settlement to the wallet balance.

📦 Event Details

id string

Unique event identifier.

name string

Event name: deposit.rejected.

account_id string

Unique identifier of the account associated with the deposit.

data object

Event payload containing deposit rejection details.

id string

Unique identifier of the deposit.

amount double

Deposit amount that was rejected.

currency string

Currency of the deposit (3-letter ISO-4217 code).

fee object

Fee details associated with the deposit, if any.

amount double

Fee amount applied to the deposit.

currency string

Currency of the fee (3-letter ISO-4217 code).

global_account_id string

Global account identifier linked to the deposit.

payer object

Details of the payer who initiated the deposit.

name string

Name of the payer.

provider_transaction_id string

Transaction identifier provided by the payment provider.

reference string

Client-provided reference for the deposit.

status string

Current deposit status. Value: REJECTED.

type string

Deposit method used. Value: BANK_TRANSFER.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "303ae28f-3ab0-4682-8253-3f605beb3db1_deposit.rejected",
  "name": "deposit.rejected",
  "account_id": "acct_hUiVInamMd68NDDm5VVmyA",
  "data": {
    "amount": 50.0,
    "currency": "USD",
    "fee": {},
    "global_account_id": "bc2669d5-9ae3-41a5-9589-f8c424c47da5",
    "id": "303ae28f-3ab0-4682-8253-3f605beb3db1",
    "payer": {
      "name": "JS"
    },
    "provider_transaction_id": "5487287789",
    "reference": "123",
    "status": "REJECTED",
    "type": "BANK_TRANSFER"
  },
  "created_at": "2025-04-30T12:05:35+0000",
  "version": "2025-02-14"
}

5. Transfers

Payout Transfer Funding Scheduled

Description: Transfer funding scheduled.

Description

The funding is scheduled to be processed on the transfer date.

Funding Details

Indicates scheduled processing
Contains complete transfer details
Includes fee breakdown
Shows both payer and beneficiary information
Provides transfer timing information

📦 Event Details

id string

Unique event identifier.

name string

Event name: payout.transfer.funding.scheduled.

account_id string

Unique identifier of the account associated with the payout transfer.

data object

Event payload containing payout transfer and funding details.

id string

Unique identifier of the payout transfer request.

amount_beneficiary_receives double

Amount the beneficiary will receive.

amount_payer_pays double

Total amount the payer will pay.

beneficiary object

Details of the beneficiary receiving the payout.

address object

Beneficiary's address details.

street_address string

Street address of the beneficiary.

city string

City of the beneficiary.

state string

State of the beneficiary.

country_code string

Country code of the beneficiary (2-letter ISO 3166-2 code).

postcode string

Postal code of the beneficiary.

bank_details object

Bank account details of the beneficiary.

account_name string

Name on the beneficiary's bank account.

account_number string

Beneficiary's bank account number.

account_currency string

Currency of the beneficiary's bank account (3-letter ISO-4217 code).

bank_name string

Beneficiary's bank name.

bank_country_code string

Country code of the bank (2-letter ISO 3166-2 code).

swift_code string

SWIFT/BIC code of the beneficiary's bank.

company_name string

Beneficiary's company name.

entity_type string

Entity type of the beneficiary. Value: COMPANY.

type string

Beneficiary account type. Value: BANK_ACCOUNT.

fee_amount double

Fee amount charged for the transfer.

fee_currency string

Currency of the fee (3-letter ISO-4217 code).

fee_paid_by string

Indicates who pays the fee. Value: PAYER.

payer object

Details of the payer initiating the transfer.

additional_info object

Additional business information about the payer.

business_registration_number string

Payer's business registration number.

business_registration_type string

Type of business registration. Value: COMPANY.

business_incorporation_date string

Incorporation date of the payer's business (ISO 8601 date format: YYYY-MM-DD).

address object

Address details of the payer.

street_address string

Street address of the payer.

city string

City of the payer.

state string

State of the payer.

country_code string

Country code of the payer (2-letter ISO 3166-2 code).

postcode string

Postal code of the payer.

company_name string

Company name of the payer.

entity_type string

Entity type of the payer. Value: COMPANY.

funding object

Funding status of the payout transfer.

status string

Current funding status. Value: SCHEDULED.

transfer_date string

Scheduled date for the transfer (ISO 8601 date format: YYYY-MM-DD).

transfer_amount double

Amount to be transferred.

transfer_currency string

Currency of the transfer (3-letter ISO-4217 code).

transfer_method string

Method used to transfer the funds. Value: SWIFT.

source_currency string

Source currency of the transfer (3-letter ISO-4217 code).

swift_charge_option string

Option for who bears the SWIFT transfer charges. Value: SHARED.

short_reference_id string

Human-readable short reference for the transfer.

request_id string

Unique identifier of the request associated with the payout transfer.

reason string

Reason for the payout. Value: professional_business_services.

reference string

Client-provided reference for the payout transfer.

remarks string

Additional remarks provided for the payout transfer.

updated_at string

ISO 8601 timestamp indicating when the payout transfer was last updated.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "c7096585-ea08-460a-a404-794a7b7c3051",
  "name": "payout.transfer.funding.scheduled",
  "account_id": "acct_i74Os0HwMhmqPw9ND12TRQ",
  "data": {
    "amount_beneficiary_receives": 1000.0,
    "amount_payer_pays": 153.32,
    "beneficiary": {
      "address": {
        "street_address": "4456 Boyle Dale",
        "city": "Altamonte Springs",
        "state": "Brisaside",
        "country_code": "CN",
        "postcode": "25000"
      },
      "bank_details": {
        "account_currency": "CNY",
        "account_name": "Sylvia Hayes",
        "account_number": "75312643",
        "bank_country_code": "CN",
        "bank_name": "Denesik Inc",
        "swift_code": "ABOCCNBJ"
      },
      "company_name": "Considine - Jones",
      "entity_type": "COMPANY",
      "type": "BANK_ACCOUNT"
    },
    "created_at": "2025-04-30T12:31:37+0000",
    "fee_amount": 15.32,
    "fee_currency": "USD",
    "fee_paid_by": "PAYER",
    "funding": {
      "status": "SCHEDULED"
    },
    "id": "0ae18279-3260-4fb5-9658-61fb74cec888",
    "payer": {
      "additional_info": {
        "business_incorporation_date": "2024-02-19",
        "business_registration_number": "SG-444-32-9207",
        "business_registration_type": "COMPANY"
      },
      "address": {
        "city": "Melbourne",
        "country_code": "SG",
        "postcode": "3000",
        "state": "VIC",
        "street_address": "Melbourne St, Melbourne St"
      },
      "company_name": "demo_zoqq",
      "entity_type": "COMPANY"
    },
    "reason": "professional_business_services",
    "reference": "Test 5672b696-418e-4f56-a6cb-f3c77403409f",
    "remarks": "",
    "request_id": "4f5eaad9-35a6-4f4d-8a88-5d9e7d390113",
    "short_reference_id": "P250430-2PR7PF3",
    "source_currency": "USD",
    "status": "SCHEDULED",
    "swift_charge_option": "SHARED",
    "transfer_amount": 1000.0,
    "transfer_currency": "CNY",
    "transfer_date": "2025-04-30",
    "transfer_method": "SWIFT",
    "updated_at": "2025-04-30T12:31:37+0000"
  },
  "created_at": "2025-04-30T12:31:38+0000",
  "version": "2025-02-14"
}

Payout Transfer Funded

Triggered when funds for a payout transfer have been successfully allocated and are ready for processing.

Description

Sent when the funding stage of a payout transfer is complete, indicating funds are secured for the upcoming transfer.

Funding Details

Confirms funds are secured for transfer
Shows complete fee breakdown
Includes beneficiary bank details
Contains payer information
Provides transfer method details

📦 Event Details

id string

Unique event identifier.

name string

Event name: payout.transfer.funding.funded.

account_id string

Unique identifier of the account associated with the payout transfer.

data object

Event payload containing payout transfer and funding details.

id string

Unique identifier of the payout transfer request.

amount_beneficiary_receives double

Amount the beneficiary will receive.

amount_payer_pays double

Total amount the payer will pay.

beneficiary object

Details of the beneficiary receiving the payout.

bank_details object

Bank account details of the beneficiary.

account_name string

Name on the beneficiary's bank account.

account_number string

Beneficiary's bank account number.

account_currency string

Currency of the beneficiary's bank account (3-letter ISO-4217 code).

bank_name string

Beneficiary's bank name.

bank_country_code string

Country code of the bank (2-letter ISO 3166-2 code).

swift_code string

SWIFT/BIC code of the beneficiary's bank.

company_name string

Beneficiary's company name.

entity_type string

Entity type of the beneficiary. Value: COMPANY.

fee_amount double

Fee amount charged for the transfer.

fee_currency string

Currency of the fee (3-letter ISO-4217 code).

payer object

Details of the payer initiating the transfer.

company_name string

Company name of the payer.

entity_type string

Entity type of the payer. Value: COMPANY.

funding object

Funding status of the payout transfer.

status string

Current funding status. Value: FUNDED.

transfer_amount double

Amount to be transferred.

transfer_currency string

Currency of the transfer (3-letter ISO-4217 code).

transfer_method string

Method used to transfer the funds. Value: SWIFT.

source_currency string

Source currency of the transfer (3-letter ISO-4217 code).

reference string

Client-provided reference for the payout transfer.

short_reference_id string

Human-readable short reference for the transfer.

updated_at string

ISO 8601 timestamp indicating when the payout transfer was last updated.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "a16aba92-7ff3-49fd-91f0-5109c8391f9f",
  "name": "payout.transfer.funding.funded",
  "account_id": "acct_i74Os0HwMhmqPw9ND12TRQ",
  "data": {
    "amount_beneficiary_receives": 1000.0,
    "amount_payer_pays": 153.32,
    "beneficiary": {
      "bank_details": {
        "account_currency": "CNY",
        "account_name": "Sylvia Hayes",
        "account_number": "75312643",
        "bank_country_code": "CN",
        "bank_name": "Denesik Inc",
        "swift_code": "ABOCCNBJ"
      },
      "company_name": "Considine - Jones",
      "entity_type": "COMPANY"
    },
    "fee_amount": 15.32,
    "fee_currency": "USD",
    "funding": {
      "status": "FUNDED"
    },
    "id": "0ae18279-3260-4fb5-9658-61fb74cec888",
    "payer": {
      "company_name": "demo_zoqq",
      "entity_type": "COMPANY"
    },
    "reference": "Test 5672b696-418e-4f56-a6cb-f3c77403409f",
    "short_reference_id": "P250430-2PR7PF3",
    "source_currency": "USD",
    "status": "SCHEDULED",
    "transfer_amount": 1000.0,
    "transfer_currency": "CNY",
    "transfer_method": "SWIFT",
    "updated_at": "2025-04-30T12:31:38+0000"
  },
  "created_at": "2025-04-30T12:31:38+0000",
  "version": "2025-02-14"
}

6. Cardholder

Cardholder Ready

Description

Cardholder has passed the review process and is ready to be issued cards.

📦 Event Details

id string

Unique event identifier.

name string

Event name: issuing.cardholder.ready.

account_id string

Unique identifier of the account associated with the cardholder.

data object

Event payload containing cardholder details.

cardholder_id string

Unique identifier of the cardholder.

email string

Email address of the cardholder.

individual object

Individual details of the cardholder, if applicable. Otherwise: null.

date_of_birth string

Date of birth ((ISO 8601 date format: YYYY-MM-DD))

name object

Full name of the Individual. Only characters in English are supported

title string

Optional title of cardholder

first_name string

First name of cardholder

middle_name string

Middle name of cardholder

last_name string

Last name of cardholder

address object

Physical address of cardholder

city string

City of address

country string

Country code (2-letter ISO 3166-2) of address

line1 string

Address line 1

state string

Address state

postcode string

Address postal code

employers array

Information of the individual's employers, if available. Otherwise: null.

business_identifiers array

Local business registration number i.e. an official signal of identification for the business

country_code string

Country code (2-letter ISO 3166-2 code).

number string

Local business registration number

type string

Type of business registration number

business_name string

Name of the employer

mobile_number string

Mobile number of the cardholder.

postal_address object

Postal address of the cardholder, if applicable. Otherwise: null.

city string

City of address

country string

Country code (2-letter ISO 3166-2) of address

line1 string

Address line 1

state string>

Address state

postcode string

Address postal code

status string

Current cardholder status. Value: READY.

type string

Type of cardholder. Value: INDIVIDUAL, DELEGATE.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "606deff5-df70-31de-ac72-bf4ec4cbdd65",
  "name": "issuing.cardholder.ready",
  "account_id": "acct__F86YxUYP2CeUQoucTySnA",
  "data": {
    "cardholder_id": "699f578c-04d2-418f-9da4-5c60b30c68ac",
    "email": "Lon_Sauer@gmail.com",
    "individual": null,
    "mobile_number": "58-15961607",
    "postal_address": null,
    "status": "READY",
    "type": "DELEGATE"
  },
  "created_at": "2025-10-15T06:27:06+0000",
  "version": "2025-02-14"
}

Cardholder Pending

Description

Cardholder needs to pass the review process before accessing card details.

📦 Event Details

id string

Unique event identifier.

name string

Event name: issuing.cardholder.pending.

account_id string

Unique identifier of the account associated with the cardholder.

data object

Event payload containing cardholder details.

cardholder_id string

Unique identifier of the cardholder.

email string

Email address of the cardholder.

individual object

Individual details of the cardholder, if applicable. Otherwise: null.

date_of_birth string

Date of birth (ISO 8601 date format: YYYY-MM-DD).

name object

Full name of the individual. Only characters in English are supported.

title string

Optional title of the cardholder.

first_name string

First name of the cardholder.

middle_name string

Middle name of the cardholder.

last_name string

Last name of the cardholder.

address object

Physical address of the cardholder.

line1 string

Address line 1.

line2 string

Address line 2, if applicable. Otherwise: null.

city string

City of the address.

state string

State of the address.

postcode string

Postal code of the address.

country string

Country code (2-letter ISO 3166-2) of the address.

employers array

Information about the individual's employers, if applicable. Otherwise: null.

business_identifiers array

Local business registration number i.e. an official signal of identification for the business

country_code string

Country code (2-letter ISO 3166-2 code).

number string

Local business registration number

type string

Type of business registration number

business_name string

Name of the employer

identification object

Identification documents of the individual, if available. Otherwise: null.

nationality string

Nationality of the individual (2-letter ISO 3166-2 code). Otherwise: null.

mobile_number string

Mobile number of the cardholder.

postal_address object

Postal address of the cardholder, if applicable. Otherwise: null.

line1 string

Postal address line 1.

line2 string

Postal address line 2, if applicable. Otherwise: null.

city string

City of the postal address.

state string

State of the postal address.

postcode string

Postal code of the postal address.

country string

Country code (2-letter ISO 3166-2) of the postal address.

status string

Current cardholder status. Value: PENDING.

type string

Type of cardholder. Value: INDIVIDUAL, DELEGATE.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "d63af2a2-01ed-347e-9361-8349219f7f20",
  "name": "issuing.cardholder.pending",
  "account_id": "acct__F86YxUYP2CeUQoucTySnA",
  "data": {
    "cardholder_id": "0515792e-8d22-4dd7-bbd5-d34a2bc0316e",
    "email": "Nichole_Jacobson@yahoo.com",
    "individual": {
      "address": {
        "city": "Austin",
        "country": "US",
        "line1": "1234 Elm Street",
        "line2": null,
        "postcode": "94932",
        "state": "TX"
      },
      "date_of_birth": "1990-01-01",
      "employers": null,
      "identification": null,
      "name": {
        "first_name": "John",
        "last_name": "Doe vh",
        "middle_name": "P",
        "name_on_card": "miss John Doe vh",
        "title": null
      },
      "nationality": null
    },
    "mobile_number": "91-95053039",
    "postal_address": {
      "city": "Los Angeles",
      "country": "US",
      "line1": "5678 Oak Avenue",
      "line2": null,
      "postcode": "94932",
      "state": "CA"
    },
    "status": "PENDING",
    "type": "INDIVIDUAL"
  },
  "created_at": "2025-10-15T06:40:45+0000",
  "version": "2025-02-14"
}

Cardholder Deleted

Description

After the cardholder is deleted successfully, then this event will be triggered.

📦 Event Details

id string

Unique event identifier.

name string

Event name: issuing.cardholder.deleted.

account_id string

Unique identifier of the account associated with the cardholder.

data object

Event payload containing cardholder deletion details.

cardholder_id string

Unique identifier of the cardholder.

deleted boolean

Indicates whether the cardholder has been deleted. Value: true.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "697769df-c6c4-3e33-878a-f10cdf03698a",
  "name": "issuing.cardholder.deleted",
  "account_id": "acct__F86YxUYP2CeUQoucTySnA",
  "data": {
    "cardholder_id": "0515792e-8d22-4dd7-bbd5-d34a2bc0316e",
    "deleted": true
  },
  "created_at": "2025-10-15T06:47:46+0000",
  "version": "2025-02-14"
}

7. Cards

Card Active (Delegate-Virtual)

Description

The card is active and can be used for transactions.

📦 Event Details

id string

Unique event identifier.

name string

Event name: issuing.card.active.

account_id string

Unique identifier of the account associated with the card.

data object

Event payload containing card details.

activate_on_issue boolean

Indicates whether the card should be activated upon issue. Otherwise: null.

additional_cardholder_ids array of string

Additional cardholder identifiers linked to the card. Otherwise: null.

authorization_controls object

Authorization and spending controls applied to the card.

active_from string

Date and time from which the card is active (ISO 8601 timestamp). Otherwise: null.

active_to string

Date and time until which the card is active (ISO 8601 timestamp). Otherwise: null.

allowed_currencies array of string

List of allowed transaction currencies.

allowed_merchant_categories array of string

List of allowed merchant category codes (MCC).

allowed_transaction_count string

Specifies whether this card is a Single or Multiple Use card. Possible values are SINGLE, MULTIPLE. Single Use means that the card can only be used for 1 successful debit transaction.

transaction_limits object

Transaction limit configuration.

cash_withdrawal_limits array

Cash withdrawal limits.

amount double

Maximum withdrawal amount.

interval string

Time interval for the withdrawal limit. Example: DAILY.

currency string

Currency for transaction limits (3-letter ISO-4217 code).

limits array

Transaction spending limits.

amount double

Maximum allowed transaction amount.

interval string

Limit interval: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

brand string

Card network brand. Value: VISA.

card_id string

Unique identifier of the card.

card_number string

Masked card number.

card_status string

Current card status. Value: ACTIVE.

card_version number

Version number of the card.

cardholder_id string

Associated cardholder identifier. Otherwise: null.

client_data object

Client-specific metadata. Otherwise: null.

created_at string

ISO 8601 timestamp when the card was created.

created_by string

Identifier of the entity that created the card.

delivery_details object

Card delivery details, if applicable. Otherwise: null.

form_factor string

Form factor of the card. Value: VIRTUAL.

is_personalized boolean

Indicates whether the card is assigned to a single individual or to the business with multiple authorized users. Only personalized cards can be physical and added to digital wallets.

issue_to string

Entity to which the card is issued. Otherwise: null.

metadata object

Custom metadata associated with the card. Otherwise: null.

name_on_card string

Name printed on the card.

nick_name string

Nickname assigned to the card. Otherwise: null.

note string

Internal note associated with the card. Otherwise: null.

postal_address object

Postal address for card delivery, if applicable. Otherwise: null.

primary_contact_details object

Primary contact details linked to the card. Otherwise: null.

program object

Program configuration associated with the card.

interchange_percent double

Interchange percentage applied. Otherwise: null.

purpose string

Program purpose. Example: COMMERCIAL.

sub_type string

Program subtype. Otherwise: null.

type string

Program type. Example: DEBIT.

purpose string

Card usage purpose. Value: BUSINESS_EXPENSES.

request_id string

Request identifier associated with the card creation.

type string

Card type, if applicable. Otherwise: null.

updated_at string

ISO 8601 timestamp when the card was last updated.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "b42f7e95-7158-30fd-a8b1-ff8919a80ea1",
  "name": "issuing.card.active",
  "account_id": "acct__F86YxUYP2CeUQoucTySnA",
  "data": {
    "activate_on_issue": null,
    "additional_cardholder_ids": null,
    "authorization_controls": {
      "active_from": null,
      "active_to": null,
      "allowed_currencies": [],
      "allowed_merchant_categories": [],
      "allowed_transaction_count": "MULTIPLE",
      "transaction_limits": {
        "cash_withdrawal_limits": [
          {
            "amount": 5000,
            "interval": "DAILY"
          }
        ],
        "currency": "HKD",
        "limits": [
          {
            "amount": 10000,
            "interval": "PER_TRANSACTION"
          }
        ]
      }
    },
    "brand": "VISA",
    "card_id": "2fa9bee6-b233-4952-863b-e0506b2d2f6d",
    "card_number": "************5230",
    "card_status": "ACTIVE",
    "card_version": 1,
    "cardholder_id": null,
    "client_data": null,
    "created_at": "2025-10-15T10:38:50.408+0000",
    "created_by": "dba7e321-9740-4ec2-85b6-9b8c1738e3d7",
    "delivery_details": null,
    "form_factor": "VIRTUAL",
    "is_personalized": false,
    "issue_to": null,
    "metadata": null,
    "name_on_card": "PRPPCmedia OU",
    "nick_name": "null",
    "note": null,
    "postal_address": null,
    "primary_contact_details": null,
    "program": {
      "interchange_percent": null,
      "purpose": "COMMERCIAL",
      "sub_type": null,
      "type": "DEBIT"
    },
    "purpose": "BUSINESS_EXPENSES",
    "request_id": "2e0c6a53-4373-427a-b9da-80929bee4ba6",
    "type": null,
    "updated_at": "2025-10-15T10:38:50.408+0000"
  },
  "created_at": "2025-10-15T10:38:50+0000",
  "version": "2025-02-14"
}

Card Active (Individual - Virtual)

Description

The card is active and can be used for transactions.

📦 Event Details

id string

Unique event identifier.

name string

Event name: issuing.card.active.

account_id string

Unique identifier of the account associated with the card.

data object

Event payload containing card details.

activate_on_issue boolean

Indicates whether the card should be activated upon issue. Otherwise: null.

additional_cardholder_ids array of string

Additional cardholder identifiers linked to the card. Otherwise: null.

authorization_controls object

Authorization and spending controls applied to the card.

active_from string

Date and time from which the card is active (ISO 8601 timestamp). Otherwise: null.

active_to string

Date and time until which the card is active (ISO 8601 timestamp). Otherwise: null.

allowed_currencies array of string

List of allowed transaction currencies.

allowed_merchant_categories array of string

List of allowed merchant category codes (MCC).

allowed_transaction_count string

Specifies whether this card is a Single or Multiple Use card. Possible values are SINGLE, MULTIPLE. Single Use means that the card can only be used for 1 successful debit transaction.

transaction_limits object

Transaction limit configuration.

cash_withdrawal_limits array

Cash withdrawal limits.

amount double

Maximum withdrawal amount.

interval string

Time interval for the withdrawal limit. Example: DAILY.

currency string

Currency for transaction limits (3-letter ISO-4217 code).

limits array

Transaction spending limits.

amount double

Maximum allowed transaction amount.

interval string

Limit interval: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

brand string

Card network brand. Example: VISA.

card_id string

Unique identifier of the card.

card_number string

Masked card number.

card_status string

Current card status. Value: ACTIVE.

card_version number

Version number of the card.

cardholder_id string

Associated cardholder identifier. Otherwise: null.

client_data object

Client-specific metadata. Otherwise: null.

created_at string

ISO 8601 timestamp when the card was created.

created_by string

Identifier of the entity that created the card.

delivery_details object

Card delivery details, if applicable. Otherwise: null.

form_factor string

Form factor of the card. Value: VIRTUAL.

is_personalized boolean

Indicates whether the card is assigned to a single individual or to the business with multiple authorized users. Only personalized cards can be physical and added to digital wallets.

issue_to string

Entity to which the card is issued. Otherwise: null.

metadata object

Custom metadata associated with the card. Otherwise: null.

name_on_card string

Name printed on the card.

nick_name string

Nickname assigned to the card. Otherwise: null.

note string

Internal note associated with the card. Otherwise: null.

postal_address object

Postal address for card delivery, if applicable. Otherwise: null.

primary_contact_details object

Primary contact details linked to the card. Otherwise: null.

program object

Program configuration associated with the card.

interchange_percent double

Interchange percentage applied. Otherwise: null.

purpose string

Program purpose. Example: COMMERCIAL.

sub_type string

Program subtype. Otherwise: null.

type string

Program type. Example: DEBIT.

purpose string

Card usage purpose. Value: BUSINESS_EXPENSES.

request_id string

Request identifier associated with the card creation.

type string

Card type, if applicable. Otherwise: null.

updated_at string

ISO 8601 timestamp when the card was last updated.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "45e7eabc-1cfb-3aa6-b2ad-8ede17f78ddc",
  "name": "issuing.card.active",
  "account_id": "acct__F86YxUYP2CeUQoucTySnA",
  "data": {
    "activate_on_issue": null,
    "additional_cardholder_ids": null,
    "authorization_controls": {
      "active_from": null,
      "active_to": null,
      "allowed_currencies": [],
      "allowed_merchant_categories": [],
      "allowed_transaction_count": "MULTIPLE",
      "transaction_limits": {
        "cash_withdrawal_limits": [
          {
            "amount": 5000,
            "interval": "DAILY"
          }
        ],
        "currency": "HKD",
        "limits": [
          {
            "amount": 10000,
            "interval": "PER_TRANSACTION"
          }
        ]
      }
    },
    "brand": "VISA",
    "card_id": "f5cc6b7d-e56b-4350-8bb9-ab098db6ab9d",
    "card_number": "************8006",
    "card_status": "ACTIVE",
    "card_version": 1,
    "cardholder_id": null,
    "client_data": null,
    "created_at": "2025-10-15T11:10:22.624+0000",
    "created_by": "dba7e321-9740-4ec2-85b6-9b8c1738e3d7",
    "delivery_details": null,
    "form_factor": "VIRTUAL",
    "is_personalized": false,
    "issue_to": null,
    "metadata": null,
    "name_on_card": "PRPPCmedia OU",
    "nick_name": "null",
    "note": null,
    "postal_address": null,
    "primary_contact_details": null,
    "program": {
      "interchange_percent": null,
      "purpose": "COMMERCIAL",
      "sub_type": null,
      "type": "DEBIT"
    },
    "purpose": "BUSINESS_EXPENSES",
    "request_id": "c20e1d30-4d90-443b-b415-774ba65f91e5",
    "type": null,
    "updated_at": "2025-10-15T11:10:22.624+0000"
  },
  "created_at": "2025-10-15T11:10:22+0000",
  "version": "2025-02-14"
}

Card Inactive

Description

The card is successfully frozen and cannot be used for transactions. However, it can be unfrozen and used again.

📦 Event Details

id string

Unique event identifier.

name string

Event name: issuing.card.inactive.

account_id string

Unique identifier of the account associated with the card.

data object

Event payload containing card details.

activate_on_issue boolean

Indicates whether the card should be activated upon issue. Otherwise: null.

additional_cardholder_ids array of string

Additional cardholder identifiers linked to the card. Otherwise: null.

authorization_controls object

Authorization and spending controls applied to the card.

active_from string

Date and time from which the card was active (ISO 8601 timestamp).

active_to string

Date and time until which the card was active (ISO 8601 timestamp).

allowed_currencies array of string

Allowed transaction currencies.

allowed_merchant_categories array of string

Allowed merchant category codes (MCC).

allowed_transaction_count string

Specifies whether this card is a Single or Multiple Use card. Possible values are SINGLE, MULTIPLE. Single Use means that the card can only be used for 1 successful debit transaction.

transaction_limits object

Transaction and withdrawal limit configuration.

cash_withdrawal_limits array

Cash withdrawal limits applied to the card.

amount double

Maximum cash withdrawal amount.

interval string

Withdrawal limit interval. Example: DAILY.

currency string

Currency used for transaction limits (3-letter ISO-4217 code).

limits array

Spending limits applied to the card.

amount double

Maximum allowed transaction amount.

interval string

Limit interval: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

brand string

Card network brand. Example: VISA.

card_id string

Unique identifier of the card.

card_number string

Masked card number.

card_status string

Current card status. Value: INACTIVE.

card_version number

Version number of the card.

cardholder_id string

Associated cardholder identifier. Otherwise: null.

created_at string

ISO 8601 timestamp when the card was created.

updated_at string

ISO 8601 timestamp when the card was last updated.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "563b6d32-abea-3dc2-be0f-de2f13c3409a",
  "name": "issuing.card.inactive",
  "account_id": "acct__F86YxUYP2CeUQoucTySnA",
  "data": {
    "activate_on_issue": null,
    "additional_cardholder_ids": null,
    "authorization_controls": {
      "active_from": "2025-05-01T00:00:00.000+00:00",
      "active_to": "2025-12-31T23:59:59.000+00:00",
      "allowed_currencies": ["USD", "EUR", "INR"],
      "allowed_merchant_categories": ["5411", "5732", "5999"],
      "allowed_transaction_count": "MULTIPLE",
      "transaction_limits": {
        "cash_withdrawal_limits": [
          {
            "amount": 500,
            "interval": "DAILY"
          }
        ],
        "currency": "USD",
        "limits": [
          {
            "amount": 1,
            "interval": "DAILY"
          },
          {
            "amount": 10000,
            "interval": "PER_TRANSACTION"
          }
        ]
      }
    },
    "brand": "VISA",
    "card_id": "f5cc6b7d-e56b-4350-8bb9-ab098db6ab9d",
    "card_number": "************8006",
    "card_status": "INACTIVE",
    "card_version": 1,
    "cardholder_id": null,
    "client_data": null,
    "created_at": "2025-10-15T11:10:22.624+0000",
    "created_by": "dba7e321-9740-4ec2-85b6-9b8c1738e3d7",
    "delivery_details": null,
    "form_factor": "VIRTUAL",
    "is_personalized": false,
    "issue_to": null,
    "metadata": null,
    "name_on_card": "PRPPCmedia OU",
    "nick_name": "null",
    "note": null,
    "postal_address": null,
    "primary_contact_details": null,
    "program": {
      "interchange_percent": null,
      "purpose": "COMMERCIAL",
      "sub_type": null,
      "type": "DEBIT"
    },
    "purpose": "BUSINESS_EXPENSES",
    "request_id": "c20e1d30-4d90-443b-b415-774ba65f91e5",
    "type": null,
    "updated_at": "2025-10-15T11:40:56.717+0000"
  },
  "created_at": "2025-10-15T11:40:56+0000",
  "version": "2025-02-14"
}

Card Closed

Description

The card is cancelled. This is a terminal state.

📦 Event Details

id string

Unique event identifier.

name string

Event name: issuing.card.closed.

account_id string

Unique identifier of the account associated with the card.

data object

Event payload containing card details.

activate_on_issue boolean

Indicates whether the card should be activated upon issue. Otherwise: null.

additional_cardholder_ids array of string

Additional cardholder identifiers linked to the card. Otherwise: null.

authorization_controls object

Authorization and spending controls applied to the card.

active_from string

Date and time from which the card was active (ISO 8601 timestamp).

active_to string

Date and time until which the card was active (ISO 8601 timestamp).

allowed_currencies array of string

List of allowed transaction currencies.

allowed_merchant_categories array of string

List of allowed merchant category codes (MCC).

allowed_transaction_count string

Specifies whether this card is a Single or Multiple Use card. Possible values are SINGLE, MULTIPLE. Single Use means that the card can only be used for 1 successful debit transaction.

transaction_limits object

Transaction limit configuration.

cash_withdrawal_limits array

Cash withdrawal limits.

amount double

Maximum withdrawal amount.

interval string

Time interval for the withdrawal limit. Example: DAILY.

currency string

Currency for transaction limits (3-letter ISO-4217 code).

limits array

Spending limits configuration.

amount double

Maximum allowed transaction amount.

interval string

Limit interval: PER_TRANSACTION, DAILY, WEEKLY, MONTHLY, ALL_TIME.

brand string

Card network brand. Example: VISA.

card_id string

Unique identifier of the card.

card_number string

Masked card number.

card_status string

Current card status. Value: CLOSED.

card_version number

Version number of the card.

cardholder_id string

Associated cardholder identifier. Otherwise: null.

client_data object

Client-specific metadata. Otherwise: null.

created_at string

ISO 8601 timestamp when the card was created.

created_by string

Identifier of the entity that created the card.

delivery_details object

Card delivery details, if applicable. Otherwise: null.

form_factor string

Form factor of the card. Value: VIRTUAL.

is_personalized boolean

Indicates whether the card is assigned to a single individual or to the business with multiple authorized users. Only personalized cards can be physical and added to digital wallets.

issue_to string

Entity to which the card was issued. Otherwise: null.

metadata object

Custom metadata associated with the card. Otherwise: null.

name_on_card string

Name printed on the card.

nick_name string

Nickname assigned to the card. Otherwise: null.

note string

Internal note associated with the card. Otherwise: null.

postal_address object

Postal address for card delivery, if applicable. Otherwise: null.

primary_contact_details object

Primary contact details linked to the card. Otherwise: null.

program object

Program configuration associated with the card.

interchange_percent double

Interchange percentage applied. Otherwise: null.

purpose string

Program purpose. Example: COMMERCIAL.

sub_type string

Program subtype. Otherwise: null.

type string

Program type. Example: DEBIT.

purpose string

Card usage purpose. Value: BUSINESS_EXPENSES.

request_id string

Request identifier associated with the card lifecycle.

type string

Card type, if applicable. Otherwise: null.

updated_at string

ISO 8601 timestamp when the card was last updated.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "0ea973d5-3e4b-3c2b-a82b-b303c916b9dd",
  "name": "issuing.card.closed",
  "account_id": "acct__F86YxUYP2CeUQoucTySnA",
  "data": {
    "activate_on_issue": null,
    "additional_cardholder_ids": null,
    "authorization_controls": {
      "active_from": "2025-05-01T00:00:00.000+00:00",
      "active_to": "2025-12-31T23:59:59.000+00:00",
      "allowed_currencies": ["USD", "EUR", "INR"],
      "allowed_merchant_categories": ["5411", "5732", "5999"],
      "allowed_transaction_count": "MULTIPLE",
      "transaction_limits": {
        "cash_withdrawal_limits": [
          {
            "amount": 500,
            "interval": "DAILY"
          }
        ],
        "currency": "USD",
        "limits": [
          {
            "amount": 1,
            "interval": "DAILY"
          },
          {
            "amount": 10000,
            "interval": "PER_TRANSACTION"
          }
        ]
      }
    },
    "brand": "VISA",
    "card_id": "f5cc6b7d-e56b-4350-8bb9-ab098db6ab9d",
    "card_number": "************8006",
    "card_status": "CLOSED",
    "card_version": 1,
    "cardholder_id": null,
    "client_data": null,
    "created_at": "2025-10-15T11:10:22.624+0000",
    "created_by": "dba7e321-9740-4ec2-85b6-9b8c1738e3d7",
    "delivery_details": null,
    "form_factor": "VIRTUAL",
    "is_personalized": false,
    "issue_to": null,
    "metadata": null,
    "name_on_card": "PRPPCmedia OU",
    "nick_name": "null",
    "note": null,
    "postal_address": null,
    "primary_contact_details": null,
    "program": {
      "interchange_percent": null,
      "purpose": "COMMERCIAL",
      "sub_type": null,
      "type": "DEBIT"
    },
    "purpose": "BUSINESS_EXPENSES",
    "request_id": "c20e1d30-4d90-443b-b415-774ba65f91e5",
    "type": null,
    "updated_at": "2025-10-15T12:16:59.923+0000"
  },
  "created_at": "2025-10-15T12:16:59+0000",
  "version": "2025-02-14"
}

Successful Transaction on an Issued Card

Description

Successful transaction on an issued card.

📦 Event Details

id string

Unique event identifier.

name string

Event name: issuing.transaction.succeeded.

account_id string

Unique identifier of the account associated with the transaction.

data object

Event payload containing transaction details.

acquiring_institution_identifier string

Identifier of the acquiring institution.

auth_code string

Authorization code returned by the card network.

billing_amount double

Billed amount for the transaction.

billing_currency string

Billing currency (3-letter ISO-4217 code).

card_id string

Unique identifier of the card used.

card_nickname string

Nickname assigned to the card. Otherwise: null.

client_data object

Client-specific metadata. Otherwise: null.

failure_reason string

Reason for transaction failure, if applicable. Otherwise: null.

lifecycle_id string

Lifecycle identifier for the transaction.

masked_card_number string

Masked card number used for the transaction.

merchant object

Merchant details associated with the transaction.

category_code string

Merchant Category Code (MCC).

city string

Merchant city.

country string

Merchant country code. Otherwise: empty string.

identifier string

Merchant identifier.

name string

Merchant name.

postcode string

Merchant postal code. Otherwise: null.

state string

Merchant state or region. Otherwise: null.

network_transaction_id string

Transaction identifier assigned by the card network.

posted_date string

ISO 8601 timestamp when the transaction was posted.

retrieval_ref string

Retrieval reference number (RRN).

status string

Current transaction status. Value: PENDING.

transaction_amount double

Transaction amount.

transaction_currency string

Transaction currency (3-letter ISO-4217 code).

transaction_date string

ISO 8601 timestamp when the transaction occurred.

transaction_id string

Unique identifier of the transaction.

transaction_type string

Type of transaction. Example: AUTHORIZATION.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "f88c8fe0-aeec-31ef-9778-ebbbae7e7734",
  "name": "issuing.transaction.succeeded",
  "account_id": "acct_ot2tV8ecOZij3EMn9Ksuzg",
  "data": {
    "acquiring_institution_identifier": "30344929405",
    "auth_code": "QPSQFV",
    "billing_amount": -10.1,
    "billing_currency": "USD",
    "card_id": "dd1f2226-5871-4e1b-a3d4-beacbd83ea43",
    "card_nickname": "null",
    "client_data": null,
    "failure_reason": null,
    "lifecycle_id": "776d74fc-81e6-4341-82ac-4a5ed1122b21",
    "masked_card_number": "************2647",
    "merchant": {
      "category_code": "7531",
      "city": "n____________",
      "country": "",
      "identifier": "380086636828641",
      "name": "Airwallex Cards Simulatio",
      "postcode": null,
      "state": null
    },
    "network_transaction_id": "990540637164692",
    "posted_date": "2025-10-16T10:06:53.269+0000",
    "retrieval_ref": "055440877874",
    "status": "PENDING",
    "transaction_amount": -10.1,
    "transaction_currency": "USD",
    "transaction_date": "2025-10-16T10:06:53.269+0000",
    "transaction_id": "d1dc0dfa-f426-4cc8-a085-a58b4b96131c",
    "transaction_type": "AUTHORIZATION"
  },
  "created_at": "2025-10-16T10:06:53+0000",
  "version": "2025-02-14"
}

Failed Card Transaction

Description

Failed transaction on an issued card.

📦 Event Details

id string

Unique event identifier.

name string

Event name: issuing.transaction.failed.

account_id string

Unique identifier of the account associated with the transaction.

data object

Event payload containing transaction details.

acquiring_institution_identifier string

Identifier of the acquiring institution.

auth_code string

Authorization code returned by the card network.

billing_amount double

Billed amount for the transaction.

billing_currency string

Billing currency (3-letter ISO-4217 code).

card_id string

Unique identifier of the card used.

card_nickname string

Nickname assigned to the card.

client_data object

Client-specific metadata. Otherwise: null.

failure_reason string

Reason for transaction failure. Example: CARD_CLOSED.

lifecycle_id string

Lifecycle identifier for the transaction.

masked_card_number string

Masked card number used for the transaction.

merchant object

Merchant details associated with the transaction.

category_code string

Merchant Category Code (MCC).

city string

Merchant city.

country string

Merchant country code. Otherwise: empty string.

identifier string

Merchant identifier.

name string

Merchant name.

postcode string

Merchant postal code. Otherwise: null.

state string

Merchant state or region. Otherwise: null.

network_transaction_id string

Transaction identifier assigned by the card network.

posted_date string

ISO 8601 timestamp when the transaction was posted.

retrieval_ref string

Retrieval reference number (RRN).

status string

Current transaction status. Value: FAILED.

transaction_amount double

Transaction amount.

transaction_currency string

Transaction currency (3-letter ISO-4217 code).

transaction_date string

ISO 8601 timestamp when the transaction occurred.

transaction_id string

Unique identifier of the transaction.

transaction_type string

Type of transaction. Example: AUTHORIZATION.

created_at string

ISO 8601 timestamp indicating when the event was created.

version string

API version associated with the event.

Request Body Example

{
  "id": "7b30f394-52af-3854-8011-c4248f7d82d5",
  "name": "issuing.transaction.failed",
  "account_id": "acct_ot2tV8ecOZij3EMn9Ksuzg",
  "data": {
    "acquiring_institution_identifier": "08852578255",
    "auth_code": "123519",
    "billing_amount": -0.2,
    "billing_currency": "SGD",
    "card_id": "7e4d7e2b-01f9-4c92-b286-324b4a759975",
    "card_nickname": "debio",
    "client_data": null,
    "failure_reason": "CARD_CLOSED",
    "lifecycle_id": "d0e7426a-04f0-4921-a10e-fd984b0d5a8f",
    "masked_card_number": "************9660",
    "merchant": {
      "category_code": "7531",
      "city": "n____________",
      "country": "",
      "identifier": "622410427837708",
      "name": "Airwallex Cards Simulatio",
      "postcode": null,
      "state": null
    },
    "network_transaction_id": "849773712566140",
    "posted_date": "2025-10-16T10:15:48.224+0000",
    "retrieval_ref": "415926304868",
    "status": "FAILED",
    "transaction_amount": -1.1,
    "transaction_currency": "CNY",
    "transaction_date": "2025-10-16T10:15:48.224+0000",
    "transaction_id": "403029a4-76b9-4bf9-b948-e6b9005b3bbf",
    "transaction_type": "AUTHORIZATION"
  },
  "created_at": "2025-10-16T10:15:48+0000",
  "version": "2025-02-14"
}

🔄 Webhook Management

📥 Get All Webhooks​

📩 Request Headers

🔍 Query Parameters

Response Example

📨 Subscribe Webhook​

📩 Request Headers

📦 Request Body Parameters

⚠️ Important Note on subscription_type

Request Body for subscription_type: "w"

Request Body for subscription_type: "n"

Response Example

📥 Retrieve Subscribed Webhook Details​

📩 Request Headers

📦 Request Body Parameters

🔍 Query Parameters

Response Example

♻️ Update Webhook​

📩 Request Headers

📦 Request Body Parameters

Request Example

Response Example

❌ Delete Webhook​

📩 Request Headers

📦 Request Body Parameters

Request Example

Response Example

📨 Webhook Events

1. Account Status​

Account Submitted​

Description

📦 Event Details

Request Body Example

Account Active​

Description

📦 Event Details

Request Body Example

Account Suspended​

Description

📦 Event Details

Request Body Example

Account Action Required​

Description

📦 Event Details

Request Body Example

2. Global Accounts​

Global Account New​

Description

📦 Event Details

Request Body Example

Balance Collection​

Description

📦 Event Details

Request Body Example

3. Conversions​

Conversion Scheduled​

Description

📦 Event Details

Request Body Example

Conversion Settled​

Description

📦 Event Details

Request Body Example

4. Deposits​

Deposit Settled​

Description

📦 Event Details

Request Body Example

Deposit Rejected​

Description

📦 Event Details

Request Body Example

5. Transfers​

Payout Transfer Funding Scheduled​

Description

Funding Details

📦 Event Details

Request Body Example

Payout Transfer Funded​

Description

📥 Get All Webhooks

📨 Subscribe Webhook

⚠️ Important Note on `subscription_type`

📥 Retrieve Subscribed Webhook Details

♻️ Update Webhook

❌ Delete Webhook

1. Account Status

Account Submitted

Account Active

Account Suspended

Account Action Required

2. Global Accounts

Global Account New

Balance Collection

3. Conversions

Conversion Scheduled

Conversion Settled

4. Deposits

Deposit Settled

Deposit Rejected

5. Transfers

Payout Transfer Funding Scheduled

Payout Transfer Funded

6. Cardholder

Cardholder Ready

Cardholder Pending

Cardholder Deleted

7. Cards

Card Active (Delegate-Virtual)

Card Active (Individual - Virtual)

Card Inactive

Card Closed

Successful Transaction on an Issued Card

Failed Card Transaction