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.

🔐 Authentication & Headers

All webhook requests require the following headers:

Request Headers

Parameter	Type	Required	Description
x-api-key	string	Yes	Shared X-API key provided by Zoqq
x-product-id	string	Yes	Program identifier
x-request-id	string	Yes	Idempotency key
x-user-id	string	Yes	User identification key
Authorization	string	Yes	Bearer token
Content-Type	string	Yes	Must be application/json

🔄 Webhook Management

📥 Get All Webhooks

GET {{baseUrl}}/getallwebhooks?program_code={{Shared ProductID By Zoqq}}

🔹 Description

Returns a list of all webhooks associated with a program.

✅ 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"
}

POST {{baseUrl}}/api/subscribe

🔹 Description

Subscribe to a webhook for a specific event.

📝 Request Body

Field	Type	Required	Description
`event_name`	string	✅ Yes	The name of the event to subscribe
`subscription_type`	string	✅ Yes	Subscription type ( `w` for webhook or `n` for notification )
`agent_code`	string	✅ Yes	Main agent identifier
`subagent_code`	string	✅ Yes	Sub-agent identifier
`program_code`	string	✅ Yes	Program code provided by Zoqq
`company_code`	string	✅ Yes	Your company’s unique identifier
`created_by`	string	✅ Yes	Name of creator
`webhook_url`	string	✅ Yes	Target URL to send event payloads
`updated_by`	string	❎ No	Only while updating the webhook
`sender_email`	string	✅ Yes	Email address of the sender initiating the request
`x-api-key`	string	✅ Yes	Shared X-API key provided by Zoqq

✅ 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}}",
  "created_by": "Test",
  "webhook_url": "{{webhook_url}}",
  "updated_by": "",
  "sender_email": "notification@zoqq.com",
  "x_api_key": "{{Shared X-API key By Zoqq}}"
}

Response Example

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

📥 Retrieve Subscribed Webhook Details

POST {{baseUrl}}/api/subscribedwebhook?program_code={{Shared ProductID By Zoqq}}

🔹 Description

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

📝 Request Body

Field	Type	Required	Description
`agent_code`	string	✅ Yes	Main agent identifier
`subagent_code`	string	✅ Yes	Sub-agent identifier

✅ 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"
  },
  {
    "agent_code": "agent-code",
    "company_code": "company-code",
    "created_by": "Pabitra",
    "created_time": "Thu, 07 Aug 2025 09:34:20 GMT",
    "event_name": "conversion.overdue",
    "program_code": "program-code",
    "sender_email": "notification@zoqq.com",
    "sl_no": 3,
    "subagent_code": "sub-agent-code",
    "subscription_type": "n",
    "updated_by": null,
    "updated_time": "Thu, 07 Aug 2025 09:34:20 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:20 GMT",
    "event_name": "conversion.scheduled",
    "program_code": "program-code",
    "sender_email": "notification@zoqq.com",
    "sl_no": 4,
    "subagent_code": "sub-agent-code",
    "subscription_type": "n",
    "updated_by": null,
    "updated_time": "Thu, 07 Aug 2025 09:34:20 GMT",
    "webhook_url": "test",
    "x_api_key": "TEST"
  }
]

♻️ Update Webhook

PATCH {{baseUrl}}/api/subscribe

🔹 Description

Update an existing webhook configuration.

📝 Request Body

Field	Type	Required	Description
`event_name`	string	✅ Yes	The event whose subscription is updated
`subscription_type`	string	✅ Yes	Subscription type ( `w` for webhook or `n` for notification )
`agent_code`	string	✅ Yes	Main agent identifier
`subagent_code`	string	✅ Yes	Sub-agent identifier
`program_code`	string	✅ Yes	Program code provided by Zoqq
`company_code`	string	✅ Yes	Your company’s unique identifier
`created_by`	string	✅ Yes	Name of creator
`webhook_url`	string	✅ Yes	Target URL to send event payloads
`updated_by`	string	✅ Yes	User updating the webhook
`x-api-key`	string	✅ Yes	Shared X-API key provided by Zoqq

✅ 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}}",
  "created_by": "Test Admin",
  "webhook_url": "{{webhook_url}}",
  "updated_by":"Test Admin",
  "x_api_key":"{{Shared X-API key By Zoqq}}"
}

Response Example

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

❌ Delete Webhook

DELETE {{baseUrl}}/api/subscribe

🔹 Description

Delete an existing webhook subscription.

📝 Request Body

Field	Type	Required	Description
`event_name`	string	✅ Yes	The name of the event
`subscription_type`	string	✅ Yes	Subscription type ( `w` for webhook or `n` for notification )
`agent_code`	string	✅ Yes	Main agent identifier
`subagent_code`	string	✅ Yes	Sub-agent identifier
`program_code`	string	✅ Yes	Program code provided by Zoqq
`company_code`	string	✅ Yes	Your company’s unique identifier
`created_by`	string	✅ Yes	Name of creator
`webhook_url`	string	✅ Yes	Target URL to send event payloads
`updated_by`	string	✅ Yes	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}}",
  "created_by": "Test Admin",
  "webhook_url": "{{webhook_url}}",
  "updated_by":"Test Admin"
}

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`account.submitted`)
account_id	string	Account identifier
data	object	Empty object (no additional data)
created_at	string	ISO 8601 timestamp of submission
version	string	API version

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`account.active`)
account_id	string	Account identifier
data.account_details	object	Contains verified business details
created_at	string	ISO 8601 timestamp of activation
version	string	API version

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",
          "country_code": "US",
          "postcode": "58888",
          "state": "FL",
          "suburb": "Fadelton"
        },
        "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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`account.suspended`)
account_id	string	Account identifier
data.status	string	Account status (`SUSPENDED`)
created_at	string	ISO 8601 timestamp of event
version	string	API version

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",
          "country_code": "US",
          "postcode": "58888",
          "state": "FL",
          "suburb": "New Tryciaburgh"
        },
        "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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`rfi.action_required`)
account_id	string	Account identifier
data.id	string	Request for Information ID
data.type	string	Requirement type (e.g., `KYC`)
created_at	string	ISO 8601 timestamp of event
version	string	API version

Possible Action Types

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

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`ga.new`)
account_id	string	Account identifier
data.amount	number	Deposit amount
data.ccy	string	Currency code (e.g., SGD)
data.transaction_type	string	Transaction type (`DEPOSIT`)
data.process_status	string	Current status (`NEW`)
created_at	string	ISO 8601 timestamp of event
version	string	API version

Status Flow

NEW → PENDING → SETTLED
May transition to FAILED if settlement fails

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`balance.ga.top_up`)
account_id	string	Account identifier
data.ccy	string	Currency code (e.g., SGD)
data.amount	number	Deposit amount
data.balance	number	New wallet balance
data.type	string	Transaction type (`DEPOSIT`)
created_at	string	ISO 8601 timestamp of settlement
version	string	API version

Transaction References

Links to original deposit transaction
Includes payer and bank details
Contains global account reference

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`conversion.scheduled`)
account_id	string	Account identifier
data.conversion_id	string	Unique conversion identifier
data.status	string	Current status (`SCHEDULED`)
data.currency_pair	string	Currency pair (e.g., USDSGD)
data.client_rate	number	Rate offered to client
data.buy_amount	number	Amount to be bought
data.sell_amount	number	Amount to be sold
data.conversion_date	string	Scheduled execution date (YYYY-MM-DD)
created_at	string	ISO 8601 timestamp of booking
version	string	API version

Rate Information

Client rate: Rate offered to customer
AWX rate: Internal rate used
Mid rate: Market reference rate
Rate locked until settlement cutoff

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`conversion.settled`)
account_id	string	Account identifier
data.conversion_id	string	Unique conversion identifier
data.status	string	Current status (`SETTLED`)
data.currency_pair	string	Currency pair (e.g., USDSGD)
data.client_rate	number	Executed client rate
data.buy_amount	number	Amount bought
data.sell_amount	number	Amount sold
data.conversion_date	string	Execution date (YYYY-MM-DD)
data.updated_at	string	ISO 8601 timestamp of settlement
version	string	API version

Settlement Details

Final confirmation of completed conversion
Funds now available in wallet balance
Includes all rate and amount details
References original conversion request

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`deposit.settled`)
account_id	string	Account identifier
data.amount	number	Deposit amount
data.currency	string	Currency code (e.g., USD)
data.status	string	Current status (`SETTLED`)
data.type	string	Deposit method (`BANK_TRANSFER`)
data.settled_at	number	Timestamp of settlement
data.reference	string	Deposit reference
created_at	string	ISO 8601 timestamp of event
version	string	API version

Settlement Details

Confirms funds are fully available
Includes fee information (if any)
Contains payer details
References global account
Provides provider transaction ID

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`deposit.rejected`)
account_id	string	Account identifier
data.amount	number	Deposit amount
data.currency	string	Currency code (e.g., USD)
data.status	string	Current status (`REJECTED`)
data.type	string	Deposit method (`BANK_TRANSFER`)
data.global_account_id	string	Related global account ID
data.reference	string	Deposit reference
created_at	string	ISO 8601 timestamp of rejection
version	string	API version

Rejection Details

May occur due to compliance checks
Could indicate invalid transaction details
Includes original deposit information
References provider transaction
Contains payer information

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.

Event Details

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`payout.transfer.funding.scheduled`)
account_id	string	Account identifier
data.amount_beneficiary_receives	number	Amount beneficiary will receive
data.amount_payer_pays	number	Total amount payer will pay
data.beneficiary	object	Beneficiary details including bank information
data.created_at	string	ISO 8601 creation timestamp
data.fee_amount	number	Fee amount
data.fee_currency	string	Currency code for fees
data.fee_paid_by	string	Who pays the fee (`PAYER` or `BENEFICIARY`)
data.funding.status	string	Funding status (`SCHEDULED`)
data.id	string	Transfer identifier
data.payer	object	Payer details including company information
data.reason	string	Transfer reason
data.reference	string	Transfer reference
data.request_id	string	Request identifier
data.short_reference_id	string	Short reference ID
data.source_currency	string	Source currency code
data.status	string	Transfer status (`SCHEDULED`)
data.swift_charge_option	string	SWIFT charge option (`SHARED`, `OUR`, `BEN`)
data.transfer_amount	number	Transfer amount
data.transfer_currency	string	Transfer currency code
data.transfer_date	string	Scheduled transfer date (YYYY-MM-DD)
data.transfer_method	string	Transfer method (`SWIFT`)
data.updated_at	string	ISO 8601 update timestamp
created_at	string	ISO 8601 event timestamp
version	string	API version

Funding Details

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

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": {
        "city": "Altamonte Springs",
        "country_code": "CN",
        "postcode": "25000",
        "state": "Brisaside",
        "street_address": "4456 Boyle Dale"
      },
      "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.

Event Details

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`payout.transfer.funding.funded`)
account_id	string	Account identifier
data.id	string	Transfer identifier
data.status	string	Current status (`SCHEDULED`)
data.funding.status	string	Funding status (`FUNDED`)
data.transfer_amount	number	Amount to be transferred
data.transfer_currency	string	Transfer currency (e.g., CNY)
data.source_currency	string	Source currency (e.g., USD)
data.fee_amount	number	Fee amount
data.fee_currency	string	Fee currency
created_at	string	ISO 8601 timestamp of funding
version	string	API version

Funding Details

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

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`issuing.cardholder.ready`)
account_id	string	Account identifier
data.cardholder_id	string	Unique identifier of the cardholder
data.email	string	Email address of the cardholder
data.individual	object	Individual details of the cardholder (if available)
data.mobile_number	string	Mobile number of the cardholder
data.postal_address	object	Postal address details of the cardholder (if available)
data.status	string	Current status of the cardholder (`READY`)
data.type	string	Type of the cardholder (`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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`issuing.cardholder.pending`)
account_id	string	Account identifier
data.cardholder_id	string	Unique identifier of the cardholder
data.email	string	Email address of the cardholder
data.individual.address.city	string	City of the individual’s address
data.individual.address.country	string	Country of the individual’s address
data.individual.address.line1	string	Primary address line
data.individual.address.line2	string	Secondary address line (if any)
data.individual.address.postcode	string	Postal code of the individual’s address
data.individual.address.state	string	State or region of the individual’s address
data.individual.date_of_birth	string	Date of birth of the individual (`YYYY-MM-DD`)
data.individual.employers	object	Employer information (if available)
data.individual.identification	object	Identification details (if available)
data.individual.name.first_name	string	First name of the individual
data.individual.name.last_name	string	Last name of the individual
data.individual.name.middle_name	string	Middle name of the individual
data.individual.name.name_on_card	string	Full name to appear on the card
data.individual.name.title	string	Title or prefix (if any)
data.individual.nationality	string	Nationality of the individual (if available)
data.mobile_number	string	Mobile number of the cardholder
data.postal_address.city	string	City in the postal address
data.postal_address.country	string	Country in the postal address
data.postal_address.line1	string	Primary line of the postal address
data.postal_address.line2	string	Secondary line of the postal address (if any)
data.postal_address.postcode	string	Postal code in the postal address
data.postal_address.state	string	State or region in the postal address
data.status	string	Current status of the cardholder (`PENDING`)
data.type	string	Type of the cardholder (`INDIVIDUAL`)
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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`issuing.cardholder.deleted`)
account_id	string	Account identifier
data.cardholder_id	string	Unique identifier of the deleted cardholder
data.deleted	boolean	Indicates whether the cardholder has been deleted (`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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`issuing.card.active`)
account_id	string	Account identifier
data.card_id	string	Unique card identifier
data.card_number	string	Masked card number
data.card_status	string	Card status (`ACTIVE`)
data.card_version	number	Version of the card
data.cardholder_id	string	Cardholder ID
data.activate_on_issue	boolean	Activates on issue
data.additional_cardholder_ids	array	Additional cardholder IDs
data.authorization_controls.active_from	string	Authorization start date
data.authorization_controls.active_to	string	Authorization end date
data.authorization_controls.allowed_currencies	array	Allowed currencies
data.authorization_controls.allowed_merchant_categories	array	Allowed merchant categories
data.authorization_controls.allowed_transaction_count	string	Allowed transaction count
data.authorization_controls.transaction_limits.cash_withdrawal_limits	array	Cash withdrawal limits
data.authorization_controls.transaction_limits.currency	string	Currency for limits
data.authorization_controls.transaction_limits.limits	array	Transaction limits
data.brand	string	Card brand (`VISA`)
data.client_data	object	Client data
data.created_at	string	Card creation timestamp
data.created_by	string	Creator ID
data.delivery_details	object	Delivery details
data.form_factor	string	Card form factor (`VIRTUAL`)
data.is_personalized	boolean	Personalized card
data.issue_to	string	Recipient of the card
data.metadata	object	Metadata
data.name_on_card	string	Name on the card
data.nick_name	string	Card nickname
data.note	string	Notes
data.postal_address	object	Postal address
data.primary_contact_details	object	Contact details
data.program.interchange_percent	number	Interchange percentage
data.program.purpose	string	Program purpose (`COMMERCIAL`)
data.program.sub_type	string	Program subtype
data.program.type	string	Program type (`DEBIT`)
data.purpose	string	Card purpose (`BUSINESS_EXPENSES`)
data.request_id	string	Request ID
data.type	string	Card type
data.updated_at	string	Last update timestamp
created_at	string	Event creation timestamp
version	string	API version

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`issuing.card.active`)
account_id	string	Account identifier
data.card_id	string	Unique card identifier
data.card_number	string	Masked card number
data.card_status	string	Card status (`ACTIVE`)
data.card_version	number	Card version
data.cardholder_id	string	Cardholder ID
data.brand	string	Card brand (`VISA`)
data.authorization_controls.allowed_transaction_count	string	Allowed transaction count
data.authorization_controls.transaction_limits.cash_withdrawal_limits	array	Cash withdrawal limits
data.authorization_controls.transaction_limits.currency	string	Limit currency (`HKD`)
data.authorization_controls.transaction_limits.limits	array	Transaction limits
data.form_factor	string	Card form factor (`VIRTUAL`)
data.is_personalized	boolean	Personalized card
data.name_on_card	string	Name on the card
data.program.purpose	string	Program purpose (`COMMERCIAL`)
data.program.type	string	Program type (`DEBIT`)
data.purpose	string	Card purpose (`BUSINESS_EXPENSES`)
data.request_id	string	Request ID
data.created_at	string	Card creation timestamp
data.updated_at	string	Last update timestamp
data.created_by	string	Creator ID
created_at	string	Event creation timestamp
version	string	API version

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`issuing.card.inactive`)
account_id	string	Account identifier
data.card_id	string	Unique card identifier
data.card_number	string	Masked card number
data.card_status	string	Card status (`INACTIVE`)
data.card_version	number	Card version
data.cardholder_id	string	Cardholder ID
data.brand	string	Card brand (`VISA`)
data.authorization_controls.active_from	string	Authorization start date
data.authorization_controls.active_to	string	Authorization end date
data.authorization_controls.allowed_currencies	array	Allowed currencies
data.authorization_controls.allowed_merchant_categories	array	Allowed merchant categories
data.authorization_controls.allowed_transaction_count	string	Allowed transaction count
data.authorization_controls.transaction_limits.cash_withdrawal_limits	array	Cash withdrawal limits
data.authorization_controls.transaction_limits.currency	string	Currency for limits (`USD`)
data.authorization_controls.transaction_limits.limits	array	Transaction limits
data.form_factor	string	Card form factor (`VIRTUAL`)
data.is_personalized	boolean	Personalized card
data.name_on_card	string	Name on the card
data.program.purpose	string	Program purpose (`COMMERCIAL`)
data.program.type	string	Program type (`DEBIT`)
data.purpose	string	Card purpose (`BUSINESS_EXPENSES`)
data.request_id	string	Request ID
data.created_at	string	Card creation timestamp
data.updated_at	string	Last update timestamp
data.created_by	string	Creator ID
created_at	string	Event creation timestamp
version	string	API version

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`issuing.card.closed`)
account_id	string	Account identifier
data.card_id	string	Unique card identifier
data.card_number	string	Masked card number
data.card_status	string	Card status (`CLOSED`)
data.card_version	number	Card version
data.cardholder_id	string	Cardholder ID
data.brand	string	Card brand (`VISA`)
data.authorization_controls.active_from	string	Authorization start date
data.authorization_controls.active_to	string	Authorization end date
data.authorization_controls.allowed_currencies	array	Allowed currencies
data.authorization_controls.allowed_merchant_categories	array	Allowed merchant categories
data.authorization_controls.allowed_transaction_count	string	Allowed transaction count
data.authorization_controls.transaction_limits.cash_withdrawal_limits	array	Cash withdrawal limits
data.authorization_controls.transaction_limits.currency	string	Limit currency (`USD`)
data.authorization_controls.transaction_limits.limits	array	Transaction limits
data.form_factor	string	Card form factor (`VIRTUAL`)
data.is_personalized	boolean	Personalized card
data.name_on_card	string	Name on the card
data.program.purpose	string	Program purpose (`COMMERCIAL`)
data.program.type	string	Program type (`DEBIT`)
data.purpose	string	Card purpose (`BUSINESS_EXPENSES`)
data.request_id	string	Request ID
data.created_at	string	Card creation timestamp
data.updated_at	string	Last update timestamp
data.created_by	string	Creator ID
created_at	string	Event creation timestamp
version	string	API version

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`issuing.transaction.succeeded`)
account_id	string	Account identifier
data.transaction_id	string	Unique transaction identifier
data.card_id	string	Card ID used for the transaction
data.masked_card_number	string	Masked card number
data.card_nickname	string	Card nickname
data.transaction_amount	number	Transaction amount
data.transaction_currency	string	Transaction currency
data.billing_amount	number	Billing amount
data.billing_currency	string	Billing currency
data.transaction_type	string	Type of transaction (`AUTHORIZATION`)
data.status	string	Transaction status (`PENDING`)
data.auth_code	string	Authorization code
data.network_transaction_id	string	Network transaction ID
data.retrieval_ref	string	Retrieval reference
data.lifecycle_id	string	Lifecycle ID of the transaction
data.failure_reason	string	Failure reason (if any)
data.client_data	object	Client-specific data
data.merchant.name	string	Merchant name
data.merchant.identifier	string	Merchant ID
data.merchant.category_code	string	Merchant category code
data.merchant.city	string	Merchant city
data.merchant.state	string	Merchant state
data.merchant.country	string	Merchant country
data.merchant.postcode	string	Merchant postcode
data.transaction_date	string	Transaction date and time
data.posted_date	string	Posted date of the transaction
data.acquiring_institution_identifier	string	Acquiring institution ID
created_at	string	Event creation timestamp
version	string	API version

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

Parameter	Type	Description
id	string	Unique event identifier
name	string	Event name (`issuing.transaction.failed`)
account_id	string	Account identifier
data.transaction_id	string	Unique transaction identifier
data.card_id	string	Card ID used for the transaction
data.masked_card_number	string	Masked card number
data.card_nickname	string	Card nickname
data.transaction_amount	number	Transaction amount
data.transaction_currency	string	Transaction currency
data.billing_amount	number	Billing amount
data.billing_currency	string	Billing currency
data.transaction_type	string	Type of transaction (`AUTHORIZATION`)
data.status	string	Transaction status (`FAILED`)
data.auth_code	string	Authorization code
data.network_transaction_id	string	Network transaction ID
data.retrieval_ref	string	Retrieval reference
data.lifecycle_id	string	Lifecycle ID of the transaction
data.failure_reason	string	Reason for failure (`CARD_CLOSED`)
data.client_data	object	Client-specific data
data.merchant.name	string	Merchant name
data.merchant.identifier	string	Merchant ID
data.merchant.category_code	string	Merchant category code
data.merchant.city	string	Merchant city
data.merchant.state	string	Merchant state
data.merchant.country	string	Merchant country
data.merchant.postcode	string	Merchant postcode
data.transaction_date	string	Transaction date and time
data.posted_date	string	Posted date of the transaction
data.acquiring_institution_identifier	string	Acquiring institution ID
created_at	string	Event creation timestamp
version	string	API version

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"
}

🔐 Authentication & Headers​

Request Headers

🔄 Webhook Management​

📥 Get All Webhooks​

🔹 Description​

✅ Response Example​

📨 Subscribe Webhook​

🔹 Description​

📝 Request Body​

✅ Request Example​

Response Example

📥 Retrieve Subscribed Webhook Details​

🔹 Description​

📝 Request Body​

✅ Response Example​

♻️ Update Webhook​

🔹 Description​

📝 Request Body​

✅ Request Example​

Response Example

❌ Delete Webhook​

🔹 Description​

📝 Request Body​

✅ 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

Possible Action Types

Request Body Example

2. Global Accounts​

Global Account New​

Description

Event Details

Status Flow

Request Body Example

Balance Collection​

Description

Event Details

Transaction References

Request Body Example

3. Conversions​

Conversion Scheduled​

Description

Event Details

Rate Information

Request Body Example

Conversion Settled​

Description

Event Details

Settlement Details

Request Body Example

4. Deposits​

Deposit Settled​

Description

Event Details

Settlement Details

Request Body Example

Deposit Rejected​

Description

Event Details

Rejection Details

Request Body Example

5. Transfers​

Payout Transfer Funding Scheduled​

Description

🔐 Authentication & Headers

🔄 Webhook Management

📥 Get All Webhooks

🔹 Description

✅ Response Example

📨 Subscribe Webhook

🔹 Description

📝 Request Body

✅ Request Example

📥 Retrieve Subscribed Webhook Details

🔹 Description

📝 Request Body

✅ Response Example

♻️ Update Webhook

🔹 Description

📝 Request Body

✅ Request Example

❌ Delete Webhook

🔹 Description

📝 Request Body

✅ Request Example

📨 Webhook Events

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