> For the complete documentation index, see [llms.txt](https://docs.zumrails.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zumrails.com/api-reference/webhooks.md).

# Webhooks

The goal of the webhooks is to give your organization a real time update on the status and events of users, transactions, products, invoices, subscriptions, taxes and common fees so you can automate your next call to action depending of the status of the payments or the occurrence of events.

To enable webhooks you have to open the settings page using the portal.

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2FwPXjPKUGJu79jCcQkbrA%2FWebhook%20Settings%20Screenshot.png?alt=media&#x26;token=f35085d1-cb86-4120-beac-2a7b5c82e113" alt=""><figcaption></figcaption></figure>

When a URL is defined, Zūm will send a POST request each time there is a status change or event triggered for:

* Users (only available for customers)
* Transactions (only available for customers)
* Payment Instruments (only available for customers; US only)
* Customers (only available for partners)
* Recurrent Transaction (only available for customers)
* Products (only available for customers)
* Invoices (only available for customers)
* Subscriptions (only available for customers)
* Taxes (only available for customers)
* Common Fees (only available for customers)
* Insights (only available for customers)
* Chargeback Action (only available for customers)
* Aggregation Status (only available for customers)
* Aggregation Transaction Events (only available for customers)

{% tabs %}
{% tab title="Canada" %}

```json
  {
      "Type": "Invoice",
      "Event": "Created",
      "Data": {
          ...
      }
  }
```

{% endtab %}

{% tab title="US" %}

```json
  {
      "Type": "Transaction",
      "Event": "Updated",
      "Data": {
          ...
      }
  }
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**INFO**

The payload has a property Type to indicate to each entity the webhook status change is coming from and also a property called Event that indicates the type of event that trigger the webhook.
{% endhint %}

**Event**

<table><thead><tr><th width="156">Event</th><th width="292">Description</th><th align="center">Availability</th></tr></thead><tbody><tr><td>Created</td><td>Entity was created</td><td align="center">Invoice, Subscription, Product, Tax Rate, Common Fee</td></tr><tr><td>Updated</td><td>Entity was updated on some manner</td><td align="center">Invoice, Subscription, Product, Tax Rate, Common Fee</td></tr><tr><td>Deleted</td><td>Entity was deleted</td><td align="center">Product</td></tr><tr><td>StatusChange</td><td>Entity had it's status changed</td><td align="center">Invoice, Subscription, Product, Tax Rate, Common Fee</td></tr><tr><td>Completed</td><td>Entity was ready to use</td><td align="center">Insights</td></tr><tr><td>Failed</td><td>Entity was not ready to use</td><td align="center">Insights</td></tr></tbody></table>

{% hint style="info" %}
**NOTE**

For now, transactions and user entities does not posses events to be associated with
{% endhint %}

**Type**

<table><thead><tr><th width="226">Type</th><th>Description</th></tr></thead><tbody><tr><td>User</td><td>Indicates the webhook call is for a user status change</td></tr><tr><td>Transaction</td><td>Indicates the webhook call is for a transaction status change</td></tr><tr><td>Customer</td><td>Indicates the webhook call is for a customer account status change</td></tr><tr><td>Recurrent Transaction</td><td>Indicates the webhook call is for a recurrent transaction creation</td></tr><tr><td>Product</td><td>Indicates the webhook call is for a product event</td></tr><tr><td>Invoice</td><td>Indicates the webhook call is for a invoice event</td></tr><tr><td>Subscription</td><td>Indicates the webhook call is for a subscription event</td></tr><tr><td>TaxRate</td><td>Indicates the webhook call is for a tax rate event</td></tr><tr><td>CommonFee</td><td>Indicates the webhook call is for a common fee event</td></tr><tr><td>Insights</td><td>Indicates the webhook call is for a insights event</td></tr></tbody></table>

{% tabs %}
{% tab title="Canada" %}

<table><thead><tr><th width="226">Type</th><th>Description</th></tr></thead><tbody><tr><td>User</td><td>Indicates the webhook call is for a user status change</td></tr><tr><td>Transaction</td><td>Indicates the webhook call is for a transaction status change</td></tr><tr><td>Customer</td><td>Indicates the webhook call is for a customer account status change</td></tr><tr><td>Recurrent Transaction</td><td>Indicates the webhook call is for a recurrent transaction creation</td></tr><tr><td>Product</td><td>Indicates the webhook call is for a product event</td></tr><tr><td>Invoice</td><td>Indicates the webhook call is for a invoice event</td></tr><tr><td>Subscription</td><td>Indicates the webhook call is for a subscription event</td></tr><tr><td>TaxRate</td><td>Indicates the webhook call is for a tax rate event</td></tr><tr><td>CommonFee</td><td>Indicates the webhook call is for a common fee event</td></tr><tr><td>Insights</td><td>Indicates the webhook call is for a insights event</td></tr></tbody></table>
{% endtab %}

{% tab title="US" %}

<table><thead><tr><th width="187.39996337890625">Type</th><th>Description</th></tr></thead><tbody><tr><td>Transaction</td><td>Indicates the webhook call is for a transaction status change</td></tr><tr><td>Customer</td><td>Indicates the webhook call is for a customer account status change</td></tr><tr><td>Chargeback Action</td><td>Indicates the webhook call is for a transaction chargeback status change</td></tr><tr><td>PaymentInstrument</td><td>Indicates the webhook call is for a payment instrument status change</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

The webhook payload uses the same JSON format as the responses for the get User, Transaction, Product, Invoice, Subscription, Tax Rates, Common Fees and Insights.

The [Chargeback](#chargeback-webhook) webhook payload follows the JSON structure shown in the example response.

{% hint style="info" %}
**INFO**

If you don't want to receive webhook for a specific status, then you can specify the status in the portal settings.
{% endhint %}

## Verifying authenticity

When Zūm Rails sends data to external services (e.g. when triggering a webhook to a service owned by you), the payload will be authenticated with a [hash-based message authentication code (HMAC)](https://en.wikipedia.org/wiki/HMAC).

The key used to create the HMAC is your Webhook Secret, and you verify it by running the algorithm yourself with the payload and the key to re-create the HMAC. Your Webhook Secret can be found in the portal under your settings.

The signature is always sent with the webhook in a header named *zumrails-signature*

You can verify the authenticity of the webhook response by using HMAC. The HMAC verification process is as follows:

1. You receive a POST request via the webhook
2. Your app computes a signature based on payload received, using your Webhook Secret
3. You verify that your signature matches the zumrails-signature in the request

Here are the steps to validate a request coming from Zūm Rails You’ll need the zumrails-signature sent by the webhook and your key (which is your Webhook Secret):

1. Retrieve the zumrails-signature header
2. Retrieve json body of the request. Make sure you are not adding any new spaces or formats.
3. Using HMAC SHA256 implemented in your programming language, calculate the signature in your side. The body is the payload and the secret is your Webhook Secret.
4. Compare your hash with the value provided under the zumrails-signature in the request, they should match.

A few examples on how to calculate HMAC in different languages: <https://github.com/danharper/hmac-examples>

{% tabs %}
{% tab title="Canada" %}
{% hint style="info" %}
**INFO**

When generating the signature, make sure you are using the body received in the payload, as it is. Some languages might add spaces or tabs.
{% endhint %}

{% hint style="info" %}
**WE CALCULATE THE SIGNATURE MAKING SURE THE PAYLOAD IS IN UTF-8 CHARSET,**

When generating the signature, make sure you are using the body received in the payload, as it is. Some languages might add spaces or tabs.
{% endhint %}
{% endtab %}

{% tab title="US" %}
{% hint style="danger" %}
**CAUTION**

When generating the signature, make sure you are using the body received in the payload, as it is. Some languages might add spaces or tabs.
{% endhint %}

{% hint style="danger" %}
**CAUTION**

We calculate the signature when the payload is in UTF-8 charset, so make sure it is the same on your side, or else the signatures won't match.
{% endhint %}
{% endtab %}
{% endtabs %}

## Retry in case of failure

In the event of a failure to deliver the webhook (!= 200) we will try again 3 times every 5 minutes in sandbox. In production we will retry 5 times every 60 minutes.

If you have anything specific in our retry policy, don't hesitate to talk with us, to <support@zumrails.com>, changes can be made.

## User webhook

When a user completes the [Update Payment Profile](https://docs.zumrails.com/tokenization-1/zum-connect.md#update-payment-profile) Connect flow, a `User` webhook is sent with Event `Connected` (or `NotConnected` if unsuccessful), using the same payload as the User webhook.

## Receiving users' financial institution details

{% tabs %}
{% tab title="Response" %}

```json
{
    "Type": "Transaction",
    "Data": {
        ...
        "InteracDebtorInstitutionNumber": "999",
        "InteracDebtorInstitutionName": "Testing Financial Institution",
        "InteracDebtorFullName": "Debtor Full Name",
        ...
    }
}
```

{% endtab %}
{% endtabs %}

For Interac transactions, you can now receive the end users' financial institution name and financial institution number which was used to complete the Interac requests. To receive this information, make sure you have configured the InteracSettledIntoWallet webhook event. (You can set this event by going to settings > webhook and API settings > Interac status change).

{% hint style="info" %}
**NOTE**

In some cases the bank may return the same input provided on Zum Rails and not the name on the user’s account for the parameter "InteracDebtorFullName". This will result in the transaction going through successfully even when the name might not be a match. This is rare and the banks are working to improve on their end.
{% endhint %}

{% hint style="info" %}
**INFO**

This information might not be available for all accounts. For any questions contact our support team
{% endhint %}

## Payment Instrument webhook

{% hint style="warning" %}
**US customers only**

The Payment Instrument webhook is currently only triggered for US customers verifying ACH bank accounts. It is not sent for Canadian (EFT) bank accounts.
{% endhint %}

The Payment Instrument webhook notifies you about changes to the verification status of a user's payment instrument (for example, a bank account). It's triggered when a payment instrument is added and verification begins, and again whenever that verification status is later resolved or updated.

It's also triggered when a notification of change (NOC) is received for the bank account. In this case the verification status itself does not change, but the webhook is still sent to inform you of the correction details reported by the bank.

{% tabs %}
{% tab title="Pending" %}

```json
{
  "Type": "PaymentInstrument",
  "Event": "Pending",
  "EventGeneratedAt": "2026-10-07T14:10:11.590404Z",
  "Data": {
    "Id": "f1a71263-d642-4f93-8d81-b8224d29d364",
    "UserId": "e653831f-a019-4f26-bdaa-ee89314c1148",
    "PaymentMethodType": "BankAccount",
    "Verified": false,
    "VerifyAccountStatus": "Pending",
    "NachaChangeCode": null,
    "NocCorrectionInfo": null,
    "IsoReturnCode": null,
    "NachaReturnCode": null,
    "NachaReturnReason": null,
    "IsoCode": null,
    "FailureReason": null
  }
}
```

{% endtab %}

{% tab title="Verified" %}

```json
{
  "Type": "PaymentInstrument",
  "Event": "Verified",
  "EventGeneratedAt": "2026-10-07T14:11:06.164481Z",
  "Data": {
    "Id": "f1a71263-d642-4f93-8d81-b8224d29d364",
    "UserId": "e653831f-a019-4f26-bdaa-ee89314c1148",
    "PaymentMethodType": "BankAccount",
    "Verified": true,
    "VerifyAccountStatus": "Verified",
    "NachaChangeCode": null,
    "NocCorrectionInfo": null,
    "IsoReturnCode": null,
    "NachaReturnCode": null,
    "NachaReturnReason": null,
    "IsoCode": null,
    "FailureReason": null
  }
}
```

{% endtab %}

{% tab title="Invalid" %}

```json
{
  "Type": "PaymentInstrument",
  "Event": "Invalid",
  "EventGeneratedAt": "2026-10-07T14:01:07.963323Z",
  "Data": {
    "Id": "a512a1a0-b28c-4707-be3f-1bb738dc5b69",
    "UserId": "541de902-699f-4625-8cc4-a5b264184246",
    "PaymentMethodType": "BankAccount",
    "Verified": false,
    "VerifyAccountStatus": "Invalid",
    "NachaChangeCode": null,
    "NocCorrectionInfo": null,
    "IsoReturnCode": null,
    "NachaReturnCode": "R03",
    "NachaReturnReason": "No account or unable to locate account",
    "IsoCode": null,
    "FailureReason": "R03: No account or unable to locate account"
  }
}
```

{% endtab %}

{% tab title="NotificationOfChange" %}

```json
{
  "Type": "PaymentInstrument",
  "Event": "NotificationOfChange",
  "EventGeneratedAt": "2026-10-06T19:25:05.961279Z",
  "Data": {
    "Id": "5ab2c4ba-3adb-41e2-9c6a-aa6bbdbeed84",
    "UserId": "974411c2-5f93-46e9-a5fb-4b553448ca30",
    "PaymentMethodType": "BankAccount",
    "Verified": true,
    "VerifyAccountStatus": "Verified",
    "NachaChangeCode": "C02",
    "NocCorrectionInfo": "Simulated NOC correction (AchSimulate:NOC_C02)",
    "IsoReturnCode": null,
    "NachaReturnCode": null,
    "NachaReturnReason": null,
    "IsoCode": null,
    "FailureReason": null
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**INFO**

You can choose which Payment Instrument events to receive from **Settings > Webhook and API** in the portal, under **Payment Instrument Events**.
{% endhint %}

**Event**

| Event                | Description                                                                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Pending              | Verification has been initiated for the payment instrument and is awaiting a result.                                                     |
| Verified             | The payment instrument was successfully verified.                                                                                        |
| Unverified           | The payment instrument has not yet been verified.                                                                                        |
| Failed               | Verification could not be completed for the payment instrument.                                                                          |
| Invalid              | The receiving bank reported the payment instrument's account information as invalid.                                                     |
| Unknown              | Verification could not be definitively resolved within the expected window.                                                              |
| NotificationOfChange | The bank reported that some of the payment instrument's details (e.g. account or routing number) need to be corrected before future use. |

{% hint style="info" %}
**NOTE**

`PaymentMethodType` is currently always `BankAccount` for this webhook.
{% endhint %}

## Chargeback webhook

{% tabs %}
{% tab title="Response" %}

```json
  {
      "Type": "ChargebackAction",
      "Event": "Disputed",
      "Data": {
        "Id": "e5ec36c3...5445500db505",
        "TransactionId": "ff116078...eee1a4f399a5",
        "ReceivedDate": "2024-04-10",
        "AuthorizationCode": "OK5234",
        "AcquirerReferenceNumber": "1674915201620667421592979",
        "ChargebackAmount": 9.9131,
        "DisputeCurrencyCode": "USD",
        "DisputeReasonCode": "1350",
        "MemberMessageText": "Misrepresentation",
        "FileId": "685221186",
        "ChargebackControlNumber": "771638347",
        "DueDate": "2024-04-14",
        "ChargebackWorkTypeCode": "1",
        "ChargebackStatus": "Disputed"
      }
  }
```

{% endtab %}
{% endtabs %}

The payload has a property Type to indicate to each entity the webhook status change is coming from and also a property called Event that indicates the type of event that trigger the webhook.

**Event**

| Event             | Description                            |
| ----------------- | -------------------------------------- |
| AcceptedByUser    | Chargeback was accepted by user.       |
| AcceptedByDefault | Chargeback was accepted past due date. |
| Disputed          | Chargeback was disputed by user.       |

## Aggregation Transaction webhook

The webhook is triggered at the end of the aggregation process, once the user’s bank account transactions have been retrieved.

If the process completes successfully, the response payload will include all account and transaction data. In this case, there is no need to call the API to retrieve aggregation details, as all the required information is already provided in the webhook.

If the process fails, the webhook payload will include an error message describing the issue.

**Event**

<table><thead><tr><th width="155">Event</th><th>Description</th></tr></thead><tbody><tr><td>Completed</td><td>Aggregation transaction scraping has been successfully completed. This event is triggered regardless of whether the process runs synchronously or asynchronously.</td></tr><tr><td>Failed</td><td>Aggregation transaction scraping has failed. This event is triggered only when the process runs asynchronously.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="Untitled" %}

```json
{
    "Type": "AggregationTransaction",
    "Event": "Completed",
    "EventGeneratedAt": "2026-04-23T17:07:27.324644Z",
    "Data": {
        "RequestId": "2986eb0d-ae75-4190-847b-559972cfaf59",
        "CustomerId": "b9f7c096-6fb0-4338-aba3-b59f1da27d46",
        "Card": {
            "Id": "c2b3b4a4-2c5a-499e-a318-6a3c35426abf",
            "UpdatedAt": "2026-04-23T17:07:26.166376",
            "CreatedAt": "0001-01-01T00:00:00Z",
            "Accounts": [
                {
                    "Id": "6a020cee-3147-4b29-a4c0-dd38e142e036",
                    "InstitutionNumber": "900",
                    "TransitNumber": "10000",
                    "AccountNumber": "35317855",
                    "Title": "Zum Chequing",
                    "Balance": 662.64,
                    "Currency": "CAD",
                    "AccountCategory": "Operation",
                    "AccountSubCategory": "Chequing",
                    "Transactions": [
                        {
                            "Id": "b75d43db-e2e8-458d-ad9e-eb912a9730f8",
                            "UpdatedAt": "0001-01-01T00:00:00Z",
                            "Date": "2026-04-23T00:00:00",
                            "Description": "VISA DEBIT PURCHASE REVERSAL Questrade",
                            "Credit": 0.01,
                            "Balance": 662.64,
                            "Category": {
                                "Id": "baeda044-cca9-4da7-8a50-ae6ed78cf547",
                                "Name": "Credit Reversals",
                                "CategoryGroupId": "00000000-0000-0000-0000-000000000000",
                                "InsightsType": "Expense"
                            }
                        },
                        ...
                    ]
                },
                {
                    "Id": "167b866a-e9d6-4851-a44d-c9b53ef245d4",
                    "InstitutionNumber": "900",
                    "TransitNumber": "10000",
                    "AccountNumber": "8806974",
                    "Title": "Savings",
                    "Balance": 662.64,
                    "Currency": "CAD",
                    "AccountCategory": "Operation",
                    "AccountSubCategory": "Savings",
                    "Transactions": [
                        {
                            "Id": "b75d43db-e2e8-458d-ad9e-eb912a9730f8",
                            "UpdatedAt": "0001-01-01T00:00:00Z",
                            "Date": "2026-04-23T00:00:00",
                            "Description": "VISA DEBIT PURCHASE REVERSAL Questrade",
                            "Credit": 0.01,
                            "Balance": 662.64,
                            "Category": {
                                "Id": "baeda044-cca9-4da7-8a50-ae6ed78cf547",
                                "Name": "Credit Reversals",
                                "CategoryGroupId": "00000000-0000-0000-0000-000000000000",
                                "InsightsType": "Expense"
                            }
                        },
                        ...
                    ]
                },
                {
                    "Id": "422be6f9-1198-40f4-bde0-9895f73c77fb",
                    "AccountNumber": "4242424242424242",
                    "Title": "Credit Card",
                    "Balance": 2247.67,
                    "Currency": "CAD",
                    "AccountCategory": "Credit",
                    "AccountSubCategory": "CreditCard",
                    "Transactions": [
                        {
                            "Id": "1aaa80ad-7b2c-49b4-b2e2-8a251329b9c7",
                            "UpdatedAt": "0001-01-01T00:00:00Z",
                            "Date": "2026-04-23T00:00:00",
                            "Description": "Roku for Sirius XM 816-2728107, DE 4500********2426",
                            "Credit": 1.34,
                            "Category": {
                                "Id": "baeda044-cca9-4da7-8a50-ae6ed78cf598",
                                "Name": "Uncategorized Income",
                                "CategoryGroupId": "00000000-0000-0000-0000-000000000000",
                                "InsightsType": "Expense"
                            }
                        },
                        ...
                    ]
                },
                {
                    "Id": "0196cbff-ee96-4969-9bbd-8df326fde7eb",
                    "AccountNumber": "78953",
                    "Title": "Mortgage",
                    "Balance": 9876.0,
                    "Currency": "CAD",
                    "AccountCategory": "Product",
                    "AccountSubCategory": "Mortgage",
                    "Transactions": []
                }
            ],
            "InstitutionId": "2a778283-d87a-4b8c-aa3e-af1ed16bc486",
            "InstitutionName": "Zūm Rails Testing Bank",
            "HolderId": "75924a9c-0023-4418-b870-a06b813ec0be",
            "Holder": {
                "FirstName": "John",
                "LastName": "Doe",
                "FullName": "John Doe",
                "Email": "john@doe.com",
                "PhoneNumber": "8171204182",
                "DateOfBirth": "01-01-1990",
                "AddressCivic": "1st Street",
                "AddressCity": "Toronto",
                "AddressProvince": "ON",
                "AddressCountry": "CA",
                "AddressPostalCode": "A0A0A0"
            },
            "SelectedAccountId": "6a020cee-3147-4b29-a4c0-dd38e142e036"
        }
    }
}
```

{% endtab %}

{% tab title="Failed" %}

```json
{
  "Type": "AggregationTransaction",
  "Event": "Failed",
  "EventGeneratedAt": "2026-04-23T17:38:07.935049Z",
  "Data": {
    "RequestId": "8a6ac025-2685-437f-9739-a7c65bedca89",
    "CustomerId": "0d0df5d6-6bbd-46f5-802c-bd1afd16b06f",
    "Card": {
      "Id": "c003a54c-3a7a-4c3c-b6b1-137f00108aba",
      "UpdatedAt": "2026-04-23T17:22:41.372738",
      "CreatedAt": "0001-01-01T00:00:00Z",
      "Accounts": [
        {
          "Id": "8958e418-ff29-4040-b42e-5127343906a4",
          "AccountNumber": "499968763",
          "RoutingNumber": "021000021",
          "Title": "Zum Chequing",
          "Balance": 662.64,
          "Currency": "USD",
          "AccountCategory": "Operation",
          "AccountSubCategory": "Chequing",
          "Transactions": []
        },
        {
          "Id": "385513bf-2159-409c-b106-f75aad902479",
          "AccountNumber": "599168988",
          "RoutingNumber": "021000021",
          "Title": "Savings",
          "Balance": 662.64,
          "Currency": "USD",
          "AccountCategory": "Operation",
          "AccountSubCategory": "Savings",
          "Transactions": []
        },
        {
          "Id": "9dc0dd2b-3fac-4423-b513-253ad7a730ca",
          "AccountNumber": "4242424242424242",
          "RoutingNumber": "021000021",
          "Title": "Credit Card",
          "Balance": 2247.67,
          "Currency": "USD",
          "AccountCategory": "Credit",
          "AccountSubCategory": "CreditCard",
          "Transactions": []
        },
        {
          "Id": "b3e4f549-8f20-4a50-902f-757914a71c1f",
          "AccountNumber": "265900951",
          "RoutingNumber": "021000021",
          "Title": "Mortgage",
          "Balance": 2506,
          "Currency": "USD",
          "AccountCategory": "Product",
          "AccountSubCategory": "Mortgage",
          "Transactions": []
        }
      ],
      "InstitutionId": "2a778283-d87a-4b8c-aa3e-af1ed16bc486",
      "InstitutionName": "Zūm Rails Testing Bank",
      "HolderId": "7605617a-d085-4603-a057-62d1e984300a",
      "Holder": {
        "FirstName": "John",
        "LastName": "Doe",
        "FullName": "John Doe",
        "Email": "john@doe.com",
        "PhoneNumber": "9486778618",
        "DateOfBirth": "01-01-1990",
        "AddressCivic": "1st Street",
        "AddressCity": "New York",
        "AddressProvince": "New York",
        "AddressCountry": "US",
        "AddressPostalCode": "111111111"
      },
      "SelectedAccountId": "8958e418-ff29-4040-b42e-5127343906a4"
    },
    "ErrorMessage": "Simulated permanent async transaction failure (zumAsyncTxnFail): all retries will be exhausted"
  }
}
```

{% endtab %}
{% endtabs %}

## Prepaid Card User webhook

{% tabs %}
{% tab title="OnboardIncomplete" %}

```json
{
  "Type": "PrepaidCardUser",
  "Event": "OnboardIncomplete",
  "EventGeneratedAt": "2026-03-31T16:14:53.5639672Z",
  "Data": {
    "SharedBalanceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "CardVerificationStatus": "INCOMPLETE",
    "Warnings": [
      "Face mismatch between document/govern,ent photo and selfie photo.",
      "The given identity document/number has been previously verified.",
      "Selfie photo is not live."
    ],
    "CardOnboardingSession": "https://checkout-master.zumrails.ca/baas/register/21d76d60-559f-48a3-bf17-68878956e2bc/508a2a3f-8cdc-40e9-987c-6d9343a21b9e",
    "User": {
      "FirstName": "Test",
      "MiddleName": null,
      "LastName": "webhook3",
      "DateOfBirth": "01/01/1990"
    },
    "CardApplicationStatus": "Incomplete",
    "CardRegistrationStatus": "",
    "PhysicalCard": "N",
    "FulfillmentStatus": null,
    "FulfillmentType": null,
    "PhysicalCardCreatedAt": null,
    "PhysicalCardActivatedAt": null,
    "IDVVerification": "Not Bypassed",
    "CustomerId": "21d76d60-559f-48a3-bf17-68878956e2bc",
    "CreatedAt": "2026-03-31T16:13:49.758566",
    "UserCardId": "e4d41dc2-b369-4888-aa18-741fa8c556f1",
    "CardType": "PrepaidCard",
    "UserId": "4a78182b-4958-4f88-a50b-89f15835b81b"
  }
}
```

{% endtab %}

{% tab title="OnboardApproval" %}

```json
{
  "Type": "PrepaidCardUser",
  "Event": "OnboardApproval",
  "EventGeneratedAt": "2026-03-31T16:20:07.8649699Z",
  "Data": {
    "SharedBalanceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "CardVerificationStatus": "APPROVED",
    "Warnings": [],
    "CardOnboardingSession": "https://checkout-master.zumrails.ca/baas/register/21d76d60-559f-48a3-bf17-68878956e2bc/508a2a3f-8cdc-40e9-987c-6d9343a21b9e",
    "User": {
      "FirstName": "Test",
      "MiddleName": null,
      "LastName": "webhook3",
      "DateOfBirth": "01/01/1990",
      "Occupation": "Financial Services (Investment Advisor, Insurance Agent, Mortgage Broker, Financial Analyst, etc)",
      "ShippingAddress": {
        "AddressLine1": "5456 Tomken Road",
        "AddressPostalCode": "L4W 2Z5",
        "AddressCountry": "CA",
        "AddressCity": "Mississauga",
        "AddressState": "ON"
      },
      "BillingAddress": {
        "AddressLine1": "5456 Tomken Road",
        "AddressPostalCode": "L4W 2Z5",
        "AddressCountry": "CA",
        "AddressCity": "Mississauga",
        "AddressState": "ON"
      }
    },
    "CardApplicationStatus": "PendingApproval",
    "CardStatus": "PendingCardIssuance",
    "CardRegistrationStatus": "NotRegistered",
    "PhysicalCard": "N",
    "FulfillmentStatus": null,
    "FulfillmentType": null,
    "PhysicalCardCreatedAt": null,
    "PhysicalCardActivatedAt": null,
    "IDVVerification": "Not Bypassed",
    "CustomerId": "21d76d60-559f-48a3-bf17-68878956e2bc",
    "CreatedAt": "2026-03-31T16:13:49.758566",
    "UserCardId": "e4d41dc2-b369-4888-aa18-741fa8c556f1",
    "CardType": "PrepaidCard",
    "UserId": "4a78182b-4958-4f88-a50b-89f15835b81b"
  }
}
```

{% endtab %}

{% tab title="Card Issued" %}

```json
{
  "Type": "PrepaidCardUser",
  "Event": "CardIssued",
  "EventGeneratedAt": "2026-03-31T16:44:07.1663038Z",
  "Data": {
    "SharedBalanceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "User": {
      "FirstName": "Test",
      "MiddleName": null,
      "LastName": "webhook3",
      "DateOfBirth": "01/01/1990",
      "Occupation": "Financial Services (Investment Advisor, Insurance Agent, Mortgage Broker, Financial Analyst, etc)",
      "ShippingAddress": {
        "AddressLine1": "5456 Tomken Road",
        "AddressPostalCode": "L4W 2Z5",
        "AddressCountry": "CA",
        "AddressCity": "Mississauga",
        "AddressState": "ON"
      },
      "BillingAddress": {
        "AddressLine1": "5456 Tomken Road",
        "AddressPostalCode": "L4W 2Z5",
        "AddressCountry": "CA",
        "AddressCity": "Mississauga",
        "AddressState": "ON"
      }
    },
    "CardBrand": "Unknown",
    "CardApplicationStatus": "Approved",
    "CardNumber": "************4204",
    "ExpireMonth": "03",
    "ExpireYear": "29",
    "CardStatus": "IssuedInactive",
    "CardReferenceId": "599000169970",
    "CardRegistrationStatus": "NotRegistered",
    "CardProgramId": "Zumrail_ProdT",
    "CardHolderId": "599000000000001699",
    "AvailableBalance": 0,
    "LedgerBalance": 0,
    "PhysicalCard": "N",
    "FulfillmentStatus": null,
    "FulfillmentType": null,
    "PhysicalCardCreatedAt": null,
    "PhysicalCardActivatedAt": null,
    "IDVVerification": "Not Bypassed",
    "CustomerId": "21d76d60-559f-48a3-bf17-68878956e2bc",
    "CreatedAt": "2026-03-31T16:13:49.758566",
    "CardActivatedAt": "2026-03-31T16:44:04.223791Z",
    "UserCardId": "e4d41dc2-b369-4888-aa18-741fa8c556f1",
    "CardType": "PrepaidCard",
    "UserId": "4a78182b-4958-4f88-a50b-89f15835b81b"
  }
}

```

{% endtab %}

{% tab title="PinSet" %}

```json
{
  "Type": "PrepaidCardUser",
  "Event": "PinSet",
  "EventGeneratedAt": "2026-11-04T14:12:30.4471203Z",
  "Data": {
    "SharedBalanceGroupId": "5b1e7c2a-9d3f-4e8a-b6c1-0f3d9a6b1c44",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "User": {
      "FirstName": "Jane",
      "MiddleName": null,
      "LastName": "Sample",
      "DateOfBirth": "01/01/1990",
      "Email": "cardholder@example.com",
      "PhoneNumber": "4165550100",
      "Language": "English",
      "Occupation": "Other",
      "ShippingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Toronto",
        "AddressState": "ON"
      },
      "BillingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Toronto",
        "AddressState": "ON"
      }
    },
    "CardBrand": "Mastercard",
    "CardApplicationStatus": "Approved",
    "CardNumber": "************1234",
    "ExpireMonth": "11",
    "ExpireYear": "29",
    "CardStatus": "Active",
    "CardRegistrationStatus": "Registered",
    "CardProgramId": "Zumrails_Test_P",
    "CardHolderId": "599000000000000001",
    "AvailableBalance": 150.00,
    "LedgerBalance": 150.00,
    "PhysicalCard": "Y",
    "FulfillmentStatus": "Delivered",
    "FulfillmentType": "Expedited",
    "PhysicalCardCreatedAt": "2026-10-28T15:02:11.512Z",
    "PhysicalCardActivatedAt": "2026-11-04T14:12:29.981Z",
    "IDVVerification": "Not Bypassed",
    "CustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "CreatedAt": "2026-10-20T13:45:02.118Z",
    "CardActivatedAt": "2026-11-04T14:12:29.981Z",
    "CardClosedAt": null,
    "PinManagement": {
      "PinInitiator": "Cardholder",
      "PinInitiatedFrom": "CardholderPortal"
    },
    "UserCardId": "9b2c7e4a-1f3d-4c5b-8a6e-2d7f0c1b3a45",
    "CardType": "PrepaidCard",
    "UserId": "6d1e8f2a-3b4c-4d5e-9f6a-7b8c9d0e1f2a"
  }
}
```

{% endtab %}

{% tab title="RecipientAdded" %}

```json
{
  "Type": "PrepaidCardUser",
  "Event": "RecipientAdded",
  "EventGeneratedAt": "2026-11-04T16:05:44.2217810Z",
  "Data": {
    "RecipientId": "c4d5e6f7-8a9b-4c0d-a1e2-f3a4b5c6d7e8",
    "FirstName": "John",
    "LastName": "Example",
    "Email": "recipient@example.com",
    "Status": "Active"
  }
}
```

{% endtab %}

{% tab title="CardAddedToGroup" %}

```json
{
  "Type": "PrepaidCardUser",
  "Event": "CardAddedToGroup",
  "EventGeneratedAt": "2026-11-04T17:31:12.6620451Z",
  "Data": {
    "SharedBalanceGroupId": "5b1e7c2a-9d3f-4e8a-b6c1-0f3d9a6b1c44",
    "IsPrimaryCard": false,
    "Nickname": "Online shopping",
    "SiblingCards": [
      {
        "Id": "9b2c7e4a-1f3d-4c5b-8a6e-2d7f0c1b3a45",
        "CardReferenceId": "599000000101",
        "IsPrimaryCard": true,
        "CardStatus": "Active",
        "PhysicalCard": true,
        "Last4Digits": "1234"
      }
    ],
    "WalletProvisionings": [],
    "User": {
      "FirstName": "Jane",
      "MiddleName": null,
      "LastName": "Sample",
      "DateOfBirth": "01/01/1990",
      "Email": "cardholder@example.com",
      "PhoneNumber": "4165550100",
      "Language": "English",
      "Occupation": "Other",
      "ShippingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Toronto",
        "AddressState": "ON"
      },
      "BillingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Toronto",
        "AddressState": "ON"
      }
    },
    "CardBrand": "Mastercard",
    "CardApplicationStatus": "Approved",
    "CardNumber": "************5678",
    "ExpireMonth": "11",
    "ExpireYear": "29",
    "CardStatus": "IssuedInactive",
    "CardProgramId": "Zumrails_Test",
    "AvailableBalance": 150.00,
    "LedgerBalance": 150.00,
    "PhysicalCard": "N",
    "FulfillmentStatus": null,
    "FulfillmentType": null,
    "IDVVerification": "Not Bypassed",
    "CustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "CreatedAt": "2026-11-04T17:31:10.004Z",
    "CardActivatedAt": null,
    "UserCardId": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "CardType": "PrepaidCard",
    "UserId": "6d1e8f2a-3b4c-4d5e-9f6a-7b8c9d0e1f2a"
  }
}
```

{% endtab %}

{% tab title="WalletTokenAdded" %}

```json
{
  "Type": "PrepaidCardUser",
  "Event": "WalletTokenAdded",
  "EventGeneratedAt": "2026-11-04T18:44:51.0937265Z",
  "Data": {
    "SharedBalanceGroupId": "5b1e7c2a-9d3f-4e8a-b6c1-0f3d9a6b1c44",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [
      {
        "Id": "8f14e45f-ceea-4e7a-9b1c-2d3e4f5a6b7c",
        "DeviceName": "Jane's Pixel",
        "WalletType": "GooglePay",
        "Status": "Added",
        "TokenRequesterId": "40010075001",
        "EventDate": "2026-11-04T18:44:49Z"
      }
    ],
    "WalletProvisioning": {
      "Id": "8f14e45f-ceea-4e7a-9b1c-2d3e4f5a6b7c",
      "DeviceName": "Jane's Pixel",
      "WalletType": "GooglePay",
      "Status": "Added",
      "TokenRequesterId": "40010075001",
      "EventDate": "2026-11-04T18:44:49Z"
    },
    "User": {
      "FirstName": "Jane",
      "MiddleName": null,
      "LastName": "Sample",
      "DateOfBirth": "01/01/1990",
      "Email": "cardholder@example.com",
      "PhoneNumber": "4165550100",
      "Language": "English",
      "Occupation": "Other",
      "ShippingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Toronto",
        "AddressState": "ON"
      },
      "BillingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Toronto",
        "AddressState": "ON"
      }
    },
    "CardNumber": "************1234",
    "CardStatus": "Active",
    "CardProgramId": "Zumrails_Test_P",
    "PhysicalCard": "Y",
    "UserCardId": "9b2c7e4a-1f3d-4c5b-8a6e-2d7f0c1b3a45",
    "CardType": "PrepaidCard",
    "UserId": "6d1e8f2a-3b4c-4d5e-9f6a-7b8c9d0e1f2a"
  }
}
```

{% endtab %}
{% endtabs %}

All PIN events (PinSet, PinChanged, PinReset, PinUnblock, PinBlocked, OfflinePinBlock) use the same format as PinSet.

RecipientUpdated uses the same format as RecipientAdded.

CardRemovedFromGroup and GroupClosed uses the same format as CardAddedToGroup.

WalletTokenSuspended, WalletTokenResumed, WalletTokenRemoved, WalletTokenProvisioningDeclined, WalletTokenStepUpRequired and WalletTokenUnknown use the same format as WalletTokenAdded.

**Event**

| Type            | Event                           | Description                                                                                           |
| --------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------- |
| PrepaidCardUser | OnboardIncomplete               | Prepaid card application profile setup completed but did not complete the KYC/IDV step                |
| PrepaidCardUser | OnboardInProgress               | Prepaid card application verification started but not finished                                        |
| PrepaidCardUser | OnboardApproval                 | Prepaid card application verification is successful and passed                                        |
| PrepaidCardUser | OnboardDeclined                 | Prepaid card application is declined (same format as OnboardIncomplete)                               |
| PrepaidCardUser | OnboardUnderReview              | Prepaid card application is under review (same format as OnboardIncomplete)                           |
| PrepaidCardUser | OnboardSessionExpired           | Card application KYC verification session passed its expiry window (same format as OnboardIncomplete) |
| PrepaidCardUser | CardIssued                      | Prepaid card is issued to the approved user                                                           |
| PrepaidCardUser | CardActivated                   | Prepaid card is activated (same format as CardIssued)                                                 |
| PrepaidCardUser | CardStatusChanged               | Prepaid card status change (same format as CardIssued)                                                |
| PrepaidCardUser | CardProgramChanged              | Prepaid card program change (same format as CardIssued)                                               |
| PrepaidCardUser | CardReissue                     | Prepaid card is reissued (same format as CardIssued)                                                  |
| PrepaidCardUser | ProfileUpdate                   | Prepaid card profile change (same format as CardIssued)                                               |
| PrepaidCardUser | LowBalanceAlert                 | Prepaid card has a low balance (same format as CardIssued)                                            |
| PrepaidCardUser | PinSet                          | PIN set (see PinSet example)                                                                          |
| PrepaidCardUser | PinChanged                      | PIN changed (see PinSet example)                                                                      |
| PrepaidCardUser | PinReset                        | PIN reset (see PinSet example)                                                                        |
| PrepaidCardUser | PinUnblock                      | PIN unblocked (see PinSet example)                                                                    |
| PrepaidCardUser | PinBlocked                      | PIN blocked after too many incorrect attempts (see PinSet example)                                    |
| PrepaidCardUser | OfflinePinBlock                 | PIN blocked from an offline transaction (see PinSet example)                                          |
| PrepaidCardUser | RecipientAdded                  | Cardholder added an Interac e-Transfer recipient                                                      |
| PrepaidCardUser | RecipientUpdated                | Cardholder updated a recipient                                                                        |
| PrepaidCardUser | RecipientDeleted                | Cardholder removed a recipient                                                                        |
| PrepaidCardUser | CardAddedToGroup                | A card was added to the user's card group                                                             |
| PrepaidCardUser | CardRemovedFromGroup            | A secondary card was removed from the card group                                                      |
| PrepaidCardUser | GroupClosed                     | All cards in the group were closed                                                                    |
| PrepaidCardUser | WalletTokenAdded                | Card added to a digital wallet                                                                        |
| PrepaidCardUser | WalletTokenSuspended            | Digital wallet token suspended                                                                        |
| PrepaidCardUser | WalletTokenResumed              | Digital wallet token resumed                                                                          |
| PrepaidCardUser | WalletTokenRemoved              | Card removed from a digital wallet                                                                    |
| PrepaidCardUser | WalletTokenProvisioningDeclined | Card provisioning to a digital wallet was declined                                                    |
| PrepaidCardUser | WalletTokenStepUpRequired       | Digital wallet requires additional cardholder verification (step-up)                                  |
| PrepaidCardUser | WalletTokenUnknown              | Unrecognized digital wallet token event                                                               |

Wallet token event payloads include the `WalletProvisioning` object for the token that changed. Enable them under **Settings → Webhook & API Settings → Card User Events → Wallet Token Events**.

{% hint style="info" %}
Low Balance Alert thresholds and the Negative Balance write-off period are configured per card program under **Program Management → Rules**.
{% endhint %}

Onboard Status

| Type            | Event                 | Card Verification Status |
| --------------- | --------------------- | ------------------------ |
| PrepaidCardUser | OnboardIncomplete     | INCOMPLETE               |
| PrepaidCardUser | OnboardInProgress     | IN PROGRESS              |
| PrepaidCardUser | OnboardApproval       | APPROVED                 |
| PrepaidCardUser | OnboardDeclined       | DECLINED                 |
| PrepaidCardUser | OnboardUnderReview    | UNDER REVIEW             |
| PrepaidCardUser | OnboardSessionExpired | EXPIRED                  |

{% hint style="info" %}
**NOTE**

The CardOnboardingSession parameter is a URL link to the card applicants IDV session and the link expires after 7 days based on the initial IDV session.

The card applicant can access the CardOnboardingSession URL anytime and after authentication, they will land on where they dropped off if the card application was not finished.

Once the card onboarding link expires, the cardholder's application has expired. The cardholder will need to re-apply from the beginning and a new card onboarding link will be generated.
{% endhint %}

**Data fields**

| Field                                              | Description                                                                                                                                                                                                     |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PhysicalCard                                       | `Y` if the card is a physical card, otherwise `N`                                                                                                                                                               |
| FulfillmentStatus                                  | `Ordered`, `Shipped`, `Delivered` (physical cards)                                                                                                                                                              |
| FulfillmentType                                    | `Standard`, `Expedited` (physical cards)                                                                                                                                                                        |
| PhysicalCardCreatedAt                              | Date the physical card was ordered                                                                                                                                                                              |
| PhysicalCardActivatedAt                            | Date the physical card was activated                                                                                                                                                                            |
| IDVVerification                                    | `Bypassed`, `Not Bypassed`, `KYC Completed by Customer`                                                                                                                                                         |
| User.MiddleName                                    | Cardholder middle name, if provided                                                                                                                                                                             |
| PinManagement                                      | PIN events only: `PinInitiator`, `PinInitiatedFrom`                                                                                                                                                             |
| PinManagement.PinInitiator                         | Who initiated the PIN action. See PinInitiator values                                                                                                                                                           |
| PinManagement.PinInitiatedFrom                     | Where the PIN action came from. See PinInitiatedFrom values                                                                                                                                                     |
| LowBalanceAlert.CardholderEmailNotificationEnabled | `LowBalanceAlert` only: whether the cardholder was emailed                                                                                                                                                      |
| IsPrimaryCard                                      | Whether the card is the Primary card                                                                                                                                                                            |
| Nickname                                           | Card nickname set by the cardholder                                                                                                                                                                             |
| SharedBalanceGroupId                               | Identifier shared by all cards that share the same balance or credit line                                                                                                                                       |
| SiblingCards                                       | Other cards in the same group (`Id`, `CardReferenceId`, `IsPrimaryCard`, `CardStatus`, `PhysicalCard`, `Last4Digits`)                                                                                           |
| WalletProvisionings                                | Digital wallets the card has been added to (`Id`, `DeviceName`, `WalletType`, `Status`, `TokenRequesterId`, `EventDate`). `Removed` and `Declined` tokens are not listed, except in wallet token event webhooks |
| WalletProvisioning                                 | Wallet token events only: the digital wallet token that changed                                                                                                                                                 |

**WalletType values**

| Value      | Description                |
| ---------- | -------------------------- |
| ApplePay   | Apple Pay                  |
| GooglePay  | Google Pay                 |
| SamsungPay | Samsung Pay                |
| Unknown    | Wallet type not recognized |

**WalletProvisioning Status values**

| Value         | Description                                 |
| ------------- | ------------------------------------------- |
| Added         | Card added to the wallet                    |
| Suspended     | Wallet token suspended                      |
| Resumed       | Wallet token resumed                        |
| Removed       | Card removed from the wallet                |
| Declined      | Provisioning declined                       |
| PendingStepUp | Additional cardholder verification required |
| Unknown       | Status not recognized                       |

**PinInitiator values**

| Value      | When it's set                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------- |
| Cardholder | The cardholder did the PIN action in the Cardholder Portal.                                                         |
| Customer   | A user from the customer that owns the card did the PIN action.                                                     |
| Partner    | A Partner user did the PIN action on a client's card.                                                               |
| ZumRails   | System actions, such as an offline PIN block reported by the card processor. Also used when no other value applies. |

**PinInitiatedFrom values**

| Value            | When it's set                                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Api              | The PIN action was requested through the PIN Management API using API credentials. Offline PIN block webhooks also use Api. |
| AdminPortal      | The PIN action was done by a user in the Zūm Portal.                                                                        |
| CardholderPortal | The cardholder did the PIN action in the Cardholder Portal.                                                                 |
| Sdk              | Reserved for future use. Not currently sent.                                                                                |

**Recipient webhook fields**

| Field       | Description           |
| ----------- | --------------------- |
| RecipientId | Recipient Id          |
| FirstName   | Recipient first name  |
| LastName    | Recipient last name   |
| Email       | Recipient email       |
| Status      | `Active` or `Deleted` |

## Secured Credit Card User webhook

{% tabs %}
{% tab title="OnboardIncomplete" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "OnboardIncomplete",
  "EventGeneratedAt": "2026-04-30T14:45:23.1203217Z",
  "Data": {
    "SharedBalanceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "CardVerificationStatus": "INCOMPLETE",
    "Warnings": [],
    "CardOnboardingSession": "https://checkout-master.zumrails.ca/baas/register/secured-credit-card/5c6b68c7-225a-4611-be48-b6b338d9f4fe/c5af2fa7-c110-4fe6-8c1d-581c371577db",
    "User": {
      "FirstName": "Test",
      "MiddleName": null,
      "LastName": "web1",
      "DateOfBirth": "09/23/1987",
      "Email": "cardholder@example.com",
      "PhoneNumber": "8768768768",
      "Language": "En"
    },
    "CardApplicationStatus": "Incomplete",
    "CardRegistrationStatus": "",
    "PhysicalCard": "N",
    "FulfillmentStatus": null,
    "FulfillmentType": null,
    "PhysicalCardCreatedAt": null,
    "PhysicalCardActivatedAt": null,
    "IDVVerification": "Not Bypassed",
    "CustomerId": "5c6b68c7-225a-4611-be48-b6b338d9f4fe",
    "CreatedAt": "2026-04-30T14:44:37.023242",
    "CreditLimitRequested": 1000,
    "UserCardId": "62cfe658-b5fe-47d7-aea4-36745872ea96",
    "CardType": "SecuredCreditCard",
    "UserId": "f1a816b1-a480-4fd9-b1eb-fff65f24c30d"
  }
}

```

{% endtab %}

{% tab title="OnboardApproval" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "OnboardApproval",
  "EventGeneratedAt": "2026-04-30T14:48:28.3292066Z",
  "Data": {
    "SharedBalanceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "CardVerificationStatus": "APPROVED",
    "Warnings": [],
    "CardOnboardingSession": "https://checkout-master.zumrails.ca/baas/register/secured-credit-card/5c6b68c7-225a-4611-be48-b6b338d9f4fe/c5af2fa7-c110-4fe6-8c1d-581c371577db",
    "User": {
      "FirstName": "Test",
      "MiddleName": null,
      "LastName": "web1",
      "DateOfBirth": "09/23/1987",
      "Email": "cardholder@example.com",
      "PhoneNumber": "8768768768",
      "Language": "En",
      "Occupation": "Information Technology (Software Developer, IT Consultant, Systems Analyst, Network Administrator, etc)",
      "ShippingAddress": {
        "AddressLine1": "435 Wilson Avenue",
        "AddressPostalCode": "N2C 2R9",
        "AddressCountry": "CA",
        "AddressCity": "Kitchener",
        "AddressState": "ON"
      },
      "BillingAddress": {
        "AddressLine1": "435 Wilson Avenue",
        "AddressPostalCode": "N2C 2R9",
        "AddressCountry": "CA",
        "AddressCity": "Kitchener",
        "AddressState": "ON"
      }
    },
    "CardApplicationStatus": "PendingApproval",
    "CardStatus": "PendingCardIssuance",
    "CardRegistrationStatus": "NotRegistered",
    "PhysicalCard": "N",
    "FulfillmentStatus": null,
    "FulfillmentType": null,
    "PhysicalCardCreatedAt": null,
    "PhysicalCardActivatedAt": null,
    "IDVVerification": "Not Bypassed",
    "CustomerId": "5c6b68c7-225a-4611-be48-b6b338d9f4fe",
    "CreatedAt": "2026-04-30T14:44:37.023242",
    "CreditLimitRequested": 1000,
    "UserCardId": "62cfe658-b5fe-47d7-aea4-36745872ea96",
    "CardType": "SecuredCreditCard",
    "UserId": "f1a816b1-a480-4fd9-b1eb-fff65f24c30d"
  }
}

```

{% endtab %}

{% tab title="OnboardDepositPending" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "OnboardDepositPending",
  "EventGeneratedAt": "2026-07-03T22:02:24.0375901Z",
  "Data": {
    "SharedBalanceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "CardVerificationStatus": "APPROVED",
    "Warnings": [],
    "CardOnboardingSession": "https://checkout-master.zumrails.ca/baas/register/secured-credit-card/04054b0c-a6d4-48e4-9bc8-36ebbacc408f/82ddb29a-a4dc-4531-814c-af023369bf4c",
    "SecurityDeposit": {
      "SecurityDepositMethod": "Interac",
      "TransactionId": "87074833-2187-418b-bbce-cecf0cbce6c3",
      "Status": "InProgress",
      "Error": null
    },
    "User": {
      "FirstName": "Test1",
      "MiddleName": null,
      "LastName": "Doe",
      "DateOfBirth": "2008-07-02",
      "Email": "cardholder@example.com",
      "PhoneNumber": "2222222222",
      "Language": "En",
      "Occupation": "ZUM_DEV",
      "ShippingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressLine2": "Suite 123",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Anytown",
        "AddressState": "ON"
      },
      "BillingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressLine2": "Suite 123",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Anytown",
        "AddressState": "ON"
      }
    },
    "CardApplicationStatus": "DepositPending",
    "CardStatus": "PendingCardIssuance",
    "CardRegistrationStatus": "NotRegistered",
    "CardProgramId": "SECURE_TEST",
    "PhysicalCard": "N",
    "FulfillmentStatus": null,
    "FulfillmentType": null,
    "PhysicalCardCreatedAt": null,
    "PhysicalCardActivatedAt": null,
    "IDVVerification": "Not Bypassed",
    "CustomerId": "04054b0c-a6d4-48e4-9bc8-36ebbacc408f",
    "CreatedAt": "2026-07-03T22:02:06.479301",
    "CreditLimitRequested": 300,
    "UserCardId": "619aebb5-e56f-4d57-bb62-95a871c0d9bb",
    "CardType": "SecuredCreditCard",
    "UserId": "db5c4209-f108-4832-a3dc-6da5943bdd3d"
  }
}
```

{% endtab %}

{% tab title="OnboardDepositFailed" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "OnboardDepositFailed",
  "EventGeneratedAt": "2026-07-03T22:02:36.866576Z",
  "Data": {
    "SharedBalanceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "CardVerificationStatus": "APPROVED",
    "Warnings": [],
    "CardOnboardingSession": "https://checkout-master.zumrails.ca/baas/register/secured-credit-card/04054b0c-a6d4-48e4-9bc8-36ebbacc408f/82ddb29a-a4dc-4531-814c-af023369bf4c",
    "SecurityDeposit": {
      "SecurityDepositMethod": "Interac",
      "TransactionId": "87074833-2187-418b-bbce-cecf0cbce6c3",
      "Status": "Failed",
      "Error": "Interac failed for reason: InteracFailedGenericError"
    },
    "User": {
      "FirstName": "Test1",
      "MiddleName": null,
      "LastName": "Doe",
      "DateOfBirth": "2008-07-02",
      "Email": "cardholder@example.com",
      "PhoneNumber": "2222222222",
      "Language": "En",
      "Occupation": "ZUM_DEV",
      "ShippingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressLine2": "Suite 123",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Anytown",
        "AddressState": "ON"
      },
      "BillingAddress": {
        "AddressLine1": "123 Main Street",
        "AddressLine2": "Suite 123",
        "AddressPostalCode": "A1A 1A1",
        "AddressCountry": "CA",
        "AddressCity": "Anytown",
        "AddressState": "ON"
      }
    },
    "CardApplicationStatus": "DepositPending",
    "CardStatus": "PendingCardIssuance",
    "CardRegistrationStatus": "NotRegistered",
    "CardProgramId": "SECURE_TEST",
    "PhysicalCard": "N",
    "FulfillmentStatus": null,
    "FulfillmentType": null,
    "PhysicalCardCreatedAt": null,
    "PhysicalCardActivatedAt": null,
    "IDVVerification": "Not Bypassed",
    "CustomerId": "04054b0c-a6d4-48e4-9bc8-36ebbacc408f",
    "CreatedAt": "2026-07-03T22:02:06.479301",
    "CreditLimitRequested": 300,
    "UserCardId": "619aebb5-e56f-4d57-bb62-95a871c0d9bb",
    "CardType": "SecuredCreditCard",
    "UserId": "db5c4209-f108-4832-a3dc-6da5943bdd3d"
  }
}
```

{% endtab %}

{% tab title="Card Issued" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "CardIssued",
  "EventGeneratedAt": "2026-04-30T14:50:27.133021Z",
  "Data": {
    "SharedBalanceGroupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "User": {
      "FirstName": "Test",
      "MiddleName": null,
      "LastName": "web1",
      "DateOfBirth": "09/23/1987",
      "Email": "cardholder@example.com",
      "PhoneNumber": "8768768768",
      "Language": "En",
      "Occupation": "Information Technology (Software Developer, IT Consultant, Systems Analyst, Network Administrator, etc)",
      "ShippingAddress": {
        "AddressLine1": "435 Wilson Avenue",
        "AddressPostalCode": "N2C 2R9",
        "AddressCountry": "CA",
        "AddressCity": "Kitchener",
        "AddressState": "ON"
      },
      "BillingAddress": {
        "AddressLine1": "435 Wilson Avenue",
        "AddressPostalCode": "N2C 2R9",
        "AddressCountry": "CA",
        "AddressCity": "Kitchener",
        "AddressState": "ON"
      }
    },
    "CardBrand": "Unknown",
    "CardApplicationStatus": "Approved",
    "CardNumber": "************6644",
    "ExpireMonth": "04",
    "ExpireYear": "28",
    "CardStatus": "IssuedInactive",
    "CardRegistrationStatus": "NotRegistered",
    "CardProgramId": "SECURE_TEST",
    "CardHolderId": "599000000000002218",
    "AvailableBalance": -10,
    "LedgerBalance": -10,
    "PhysicalCard": "N",
    "FulfillmentStatus": null,
    "FulfillmentType": null,
    "PhysicalCardCreatedAt": null,
    "PhysicalCardActivatedAt": null,
    "IDVVerification": "Not Bypassed",
    "CustomerId": "5c6b68c7-225a-4611-be48-b6b338d9f4fe",
    "CreatedAt": "2026-04-30T14:44:37.023242",
    "PendingAmount": 0,
    "CreditLimitRequested": 1000,
    "CreditLimit": 250,
    "SecurityDepositAmount": 250,
    "SecurityDepositCardNumber": "95T5925560164758685",
    "SecurityDepositCardReferenceId": "599000221747",
    "LastPaymentAmount": 0,
    "MinimumPaymentAmount": 0,
    "StatementAmount": 0,
    "UserCardId": "62cfe658-b5fe-47d7-aea4-36745872ea96",
    "CardType": "SecuredCreditCard",
    "UserId": "f1a816b1-a480-4fd9-b1eb-fff65f24c30d"
  }
}

```

{% endtab %}

{% tab title="PinChanged" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "PinChanged",
  "EventGeneratedAt": "2026-11-04T15:08:17.5530912Z",
  "Data": {
    "SharedBalanceGroupId": "8f9a0b1c-2d3e-4f5a-9b6c-7d8e9f0a1b2c",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [],
    "User": {
      "FirstName": "Alex",
      "MiddleName": null,
      "LastName": "Sample",
      "DateOfBirth": "02/02/1988",
      "Email": "cardholder@example.com",
      "PhoneNumber": "5145550100",
      "Language": "French",
      "Occupation": "Other",
      "ShippingAddress": {
        "AddressLine1": "456 Rue Exemple",
        "AddressPostalCode": "H1H 1H1",
        "AddressCountry": "CA",
        "AddressCity": "Montréal",
        "AddressState": "QC"
      },
      "BillingAddress": {
        "AddressLine1": "456 Rue Exemple",
        "AddressPostalCode": "H1H 1H1",
        "AddressCountry": "CA",
        "AddressCity": "Montréal",
        "AddressState": "QC"
      }
    },
    "CardBrand": "Mastercard",
    "CardApplicationStatus": "Approved",
    "CardNumber": "************4321",
    "ExpireMonth": "11",
    "ExpireYear": "29",
    "CardStatus": "Active",
    "CardRegistrationStatus": "Registered",
    "CardProgramId": "SECURE_TEST_P",
    "CardHolderId": "599000000000000002",
    "AvailableBalance": 420.00,
    "LedgerBalance": 80.00,
    "PhysicalCard": "Y",
    "FulfillmentStatus": "Shipped",
    "FulfillmentType": "Standard",
    "PhysicalCardCreatedAt": "2026-10-25T12:10:03.221Z",
    "PhysicalCardActivatedAt": "2026-11-01T09:30:44.017Z",
    "IDVVerification": "Not Bypassed",
    "CustomerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "CreatedAt": "2026-10-15T11:02:55.640Z",
    "CardActivatedAt": "2026-11-01T09:30:44.017Z",
    "CardClosedAt": null,
    "PendingAmount": 0.00,
    "CreditLimitRequested": 500.00,
    "CreditLimit": 500.00,
    "SecurityDepositAmount": 500.00,
    "SecurityDepositCardNumber": "************8765",
    "SecurityDepositCardReferenceId": "599000000002",
    "LastPaymentDate": "2026-10-30",
    "LastPaymentAmount": 25.00,
    "MinimumPaymentAmount": 10.00,
    "MinimumPaymentDueDate": "2026-11-25",
    "StatementDate": "2026-10-31",
    "StatementAmount": 80.00,
    "PinManagement": {
      "PinInitiator": "Customer",
      "PinInitiatedFrom": "Api"
    },
    "UserCardId": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "CardType": "SecuredCreditCard",
    "UserId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b"
  }
}
```

{% endtab %}

{% tab title="CardAddedToGroup" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "CardAddedToGroup",
  "EventGeneratedAt": "2026-11-04T17:55:09.1148830Z",
  "Data": {
    "SharedBalanceGroupId": "8f9a0b1c-2d3e-4f5a-9b6c-7d8e9f0a1b2c",
    "IsPrimaryCard": false,
    "Nickname": "Online shopping",
    "SiblingCards": [
      {
        "Id": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
        "CardReferenceId": "599000000201",
        "IsPrimaryCard": true,
        "CardStatus": "Active",
        "PhysicalCard": true,
        "Last4Digits": "4321"
      }
    ],
    "WalletProvisionings": [],
    "User": {
      "FirstName": "Alex",
      "MiddleName": null,
      "LastName": "Sample",
      "DateOfBirth": "02/02/1988",
      "Email": "cardholder@example.com",
      "PhoneNumber": "5145550100",
      "Language": "French",
      "Occupation": "Other",
      "ShippingAddress": {
        "AddressLine1": "456 Rue Exemple",
        "AddressPostalCode": "H1H 1H1",
        "AddressCountry": "CA",
        "AddressCity": "Montréal",
        "AddressState": "QC"
      },
      "BillingAddress": {
        "AddressLine1": "456 Rue Exemple",
        "AddressPostalCode": "H1H 1H1",
        "AddressCountry": "CA",
        "AddressCity": "Montréal",
        "AddressState": "QC"
      }
    },
    "CardNumber": "************9900",
    "CardStatus": "IssuedInactive",
    "CardProgramId": "SECURE_TEST",
    "AvailableBalance": 420.00,
    "LedgerBalance": 80.00,
    "PhysicalCard": "N",
    "CreditLimit": 500.00,
    "SecurityDepositAmount": 500.00,
    "UserCardId": "0d1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
    "CardType": "SecuredCreditCard",
    "UserId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b"
  }
}
```

{% endtab %}

{% tab title="WalletTokenSuspended" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "WalletTokenSuspended",
  "EventGeneratedAt": "2026-11-05T08:21:37.6604119Z",
  "Data": {
    "SharedBalanceGroupId": "8f9a0b1c-2d3e-4f5a-9b6c-7d8e9f0a1b2c",
    "IsPrimaryCard": true,
    "Nickname": null,
    "SiblingCards": [],
    "WalletProvisionings": [
      {
        "Id": "c9f0f895-fb98-4b9a-8e7d-6c5b4a3f2e1d",
        "DeviceName": "Alex's iPhone",
        "WalletType": "ApplePay",
        "Status": "Suspended",
        "TokenRequesterId": "40010030273",
        "EventDate": "2026-11-05T08:21:35Z"
      }
    ],
    "WalletProvisioning": {
      "Id": "c9f0f895-fb98-4b9a-8e7d-6c5b4a3f2e1d",
      "DeviceName": "Alex's iPhone",
      "WalletType": "ApplePay",
      "Status": "Suspended",
      "TokenRequesterId": "40010030273",
      "EventDate": "2026-11-05T08:21:35Z"
    },
    "User": {
      "FirstName": "Alex",
      "MiddleName": null,
      "LastName": "Sample",
      "DateOfBirth": "02/02/1988",
      "Email": "cardholder@example.com",
      "PhoneNumber": "5145550100",
      "Language": "French",
      "Occupation": "Other",
      "ShippingAddress": {
        "AddressLine1": "456 Rue Exemple",
        "AddressPostalCode": "H1H 1H1",
        "AddressCountry": "CA",
        "AddressCity": "Montréal",
        "AddressState": "QC"
      },
      "BillingAddress": {
        "AddressLine1": "456 Rue Exemple",
        "AddressPostalCode": "H1H 1H1",
        "AddressCountry": "CA",
        "AddressCity": "Montréal",
        "AddressState": "QC"
      }
    },
    "CardNumber": "************4321",
    "CardStatus": "Active",
    "CardProgramId": "SECURE_TEST_P",
    "PhysicalCard": "Y",
    "UserCardId": "7c8d9e0f-1a2b-4c3d-8e4f-5a6b7c8d9e0f",
    "CardType": "SecuredCreditCard",
    "UserId": "2e3f4a5b-6c7d-4e8f-9a0b-1c2d3e4f5a6b"
  }
}
```

{% endtab %}
{% endtabs %}

All PIN events (PinSet, PinChanged, PinReset, PinUnblock, PinBlocked, OfflinePinBlock) use the same format as PinChanged.

CardRemovedFromGroup and GroupClosed use the same format as CardAddedToGroup.

WalletTokenAdded, WalletTokenResumed, WalletTokenRemoved, WalletTokenProvisioningDeclined, WalletTokenStepUpRequired and WalletTokenUnknown use the same format as WalletTokenSuspended.

**Event**

| Type                  | Event                           | Description                                                                                                                                    |
| --------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| SecuredCreditCardUser | OnboardIncomplete               | Card application profile setup completed but did not complete the KYC/IDV step                                                                 |
| SecuredCreditCardUser | OnboardInProgress               | Card application verification started but not finished                                                                                         |
| SecuredCreditCardUser | OnboardApproval                 | Card application verification is successful and passed                                                                                         |
| SecuredCreditCardUser | OnboardDeclined                 | Card application is declined (same format as OnboardIncomplete)                                                                                |
| SecuredCreditCardUser | OnboardUnderReview              | Card application is under review (same format as OnboardIncomplete)                                                                            |
| SecuredCreditCardUser | OnboardSessionExpired           | Card application KYC verification session passed its expiry window (same format as OnboardIncomplete)                                          |
| SecuredCreditCardUser | CardIssued                      | Card is issued to the approved user                                                                                                            |
| SecuredCreditCardUser | CardActivated                   | Card is activated (same format as CardIssued)                                                                                                  |
| SecuredCreditCardUser | CardStatusChanged               | Card status change (same format as CardIssued)                                                                                                 |
| SecuredCreditCardUser | CardProgramChanged              | Card program change (same format as CardIssued)                                                                                                |
| SecuredCreditCardUser | CardReissue                     | Card is reissued (same format as CardIssued)                                                                                                   |
| SecuredCreditCardUser | ProfileUpdate                   | Card profile change (same format as CardIssued)                                                                                                |
| SecuredCreditCardUser | CardAttributeUpdate             | Card related attribute updates such as security deposit and credit limit changes (same format as CardIssued)                                   |
| SecuredCreditCardUser | LowBalanceAlert                 | Card has a low available credit (same format as CardIssued)                                                                                    |
| SecuredCreditCardUser | CardOverlimit                   | Card balance has went over the credit limit due to various reasons: force-post on spend, fees and interest charges (same format as CardIssued) |
| SecuredCreditCardUser | OnboardDepositNotStarted        | Applicant passed KYC and has not started the Security Deposit step (same format as OnboardApproval)                                            |
| SecuredCreditCardUser | OnboardDepositPending           | Applicant initiated an Interac e-Transfer Security Deposit                                                                                     |
| SecuredCreditCardUser | OnboardDepositFailed            | Interac e-Transfer Security Deposit failed                                                                                                     |
| SecuredCreditCardUser | OnboardLoanDepositPending       | Applicant selected the Loan option for the Security Deposit (same format as OnboardDepositPending)                                             |
| SecuredCreditCardUser | PinSet                          | PIN set (see PinChanged example)                                                                                                               |
| SecuredCreditCardUser | PinChanged                      | PIN changed (see PinChanged example)                                                                                                           |
| SecuredCreditCardUser | PinReset                        | PIN reset (see PinChanged example)                                                                                                             |
| SecuredCreditCardUser | PinUnblock                      | PIN unblocked (see PinChanged example)                                                                                                         |
| SecuredCreditCardUser | PinBlocked                      | PIN blocked after too many incorrect attempts (see PinChanged example)                                                                         |
| SecuredCreditCardUser | OfflinePinBlock                 | PIN blocked from an offline transaction (see PinChanged example)                                                                               |
| SecuredCreditCardUser | CardAddedToGroup                | A card was added to the user's card group                                                                                                      |
| SecuredCreditCardUser | CardRemovedFromGroup            | A secondary card was removed from the card group                                                                                               |
| SecuredCreditCardUser | GroupClosed                     | All cards in the group were closed                                                                                                             |
| SecuredCreditCardUser | WalletTokenAdded                | Card added to a digital wallet                                                                                                                 |
| SecuredCreditCardUser | WalletTokenSuspended            | Digital wallet token suspended                                                                                                                 |
| SecuredCreditCardUser | WalletTokenResumed              | Digital wallet token resumed                                                                                                                   |
| SecuredCreditCardUser | WalletTokenRemoved              | Card removed from a digital wallet                                                                                                             |
| SecuredCreditCardUser | WalletTokenProvisioningDeclined | Card provisioning to a digital wallet was declined                                                                                             |
| SecuredCreditCardUser | WalletTokenStepUpRequired       | Digital wallet requires additional cardholder verification (step-up)                                                                           |
| SecuredCreditCardUser | WalletTokenUnknown              | Unrecognized digital wallet token event                                                                                                        |

Wallet token event payloads include the `WalletProvisioning` object for the token that changed. Enable them under **Settings → Webhook & API Settings → Card User Events → Wallet Token Events**.

{% hint style="info" %}
Low Balance Alert thresholds and the Negative Balance write-off period are configured per card program under **Program Management → Rules**.
{% endhint %}

Onboard Status

| Type                  | Event                     | Card Verification Status |
| --------------------- | ------------------------- | ------------------------ |
| SecuredCreditCardUser | OnboardIncomplete         | INCOMPLETE               |
| SecuredCreditCardUser | OnboardInProgress         | IN PROGRESS              |
| SecuredCreditCardUser | OnboardApproval           | APPROVED                 |
| SecuredCreditCardUser | OnboardDeclined           | DECLINED                 |
| SecuredCreditCardUser | OnboardUnderReview        | UNDER REVIEW             |
| SecuredCreditCardUser | OnboardDepositNotStarted  | DEPOSIT NOT STARTED      |
| SecuredCreditCardUser | OnboardDepositPending     | DEPOSIT PENDING          |
| SecuredCreditCardUser | OnboardDepositFailed      | DEPOSIT FAILED           |
| SecuredCreditCardUser | OnboardLoanDepositPending | LOAN DEPOSIT PENDING     |
| SecuredCreditCardUser | OnboardSessionExpired     | EXPIRED                  |

{% hint style="info" %}
**NOTE**

The CardOnboardingSession parameter is a URL link to the card applicants IDV session and the link expires after 7 days based on the initial IDV session.

The card applicant can access the CardOnboardingSession URL anytime and after authentication, they will land on where they dropped off if the card application was not finished.

Once the card onboarding link expires, the cardholder's application has expired. The cardholder will need to re-apply from the beginning and a new card onboarding link will be generated.
{% endhint %}

**Data fields**

| Field                                              | Description                                                                                                                                                                                                     |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PhysicalCard                                       | `Y` if the card is a physical card, otherwise `N`                                                                                                                                                               |
| FulfillmentStatus                                  | `Ordered`, `Shipped`, `Delivered` (physical cards)                                                                                                                                                              |
| FulfillmentType                                    | `Standard`, `Expedited` (physical cards)                                                                                                                                                                        |
| PhysicalCardCreatedAt                              | Date the physical card was ordered                                                                                                                                                                              |
| PhysicalCardActivatedAt                            | Date the physical card was activated                                                                                                                                                                            |
| IDVVerification                                    | `Bypassed`, `Not Bypassed`, `KYC Completed by Customer`                                                                                                                                                         |
| User.MiddleName                                    | Cardholder middle name, if provided                                                                                                                                                                             |
| SecurityDeposit.SecurityDepositMethod              | `Interac` or `Loan`. Sent on `OnboardDepositPending`, `OnboardLoanDepositPending`, `OnboardDepositFailed`, `OnboardApproval`                                                                                    |
| CardOnboardingSession                              | Link for the applicant to resume onboarding                                                                                                                                                                     |
| PinManagement                                      | PIN events only: `PinInitiator`, `PinInitiatedFrom`                                                                                                                                                             |
| PinManagement.PinInitiator                         | Who initiated the PIN action. See PinInitiator values                                                                                                                                                           |
| PinManagement.PinInitiatedFrom                     | Where the PIN action came from. See PinInitiatedFrom values                                                                                                                                                     |
| LowBalanceAlert.CardholderEmailNotificationEnabled | `LowBalanceAlert` only: whether the cardholder was emailed                                                                                                                                                      |
| IsPrimaryCard                                      | Whether the card is the Primary card                                                                                                                                                                            |
| Nickname                                           | Card nickname set by the cardholder                                                                                                                                                                             |
| SharedBalanceGroupId                               | Identifier shared by all cards that share the same balance or credit line                                                                                                                                       |
| SiblingCards                                       | Other cards in the same group (`Id`, `CardReferenceId`, `IsPrimaryCard`, `CardStatus`, `PhysicalCard`, `Last4Digits`)                                                                                           |
| WalletProvisionings                                | Digital wallets the card has been added to (`Id`, `DeviceName`, `WalletType`, `Status`, `TokenRequesterId`, `EventDate`). `Removed` and `Declined` tokens are not listed, except in wallet token event webhooks |
| WalletProvisioning                                 | Wallet token events only: the digital wallet token that changed                                                                                                                                                 |

For `WalletType`, `WalletProvisioning` Status, `PinInitiator` and `PinInitiatedFrom` values, see the tables under **Data fields** in the [Prepaid Card User](#prepaid-card-user-webhook) webhook.

Secured Credit Card onboarding events also include the `SecurityDeposit` object and the `CardOnboardingSession` link:

```json
"SecurityDeposit": {
    "SecurityDepositMethod": "Interac",
    "TransactionId": "87074833-2187-418b-bbce-cecf0cbce6c3",
    "Status": "InProgress",
    "Error": null
},
"CardOnboardingSession": "https://checkout-master.zumrails.ca/baas/register/secured-credit-card/{customerId}/{sessionId}"
```

## Physical Card Lifecycle webhook

The webhook is triggered when a physical card is ordered, shipped or delivered. The payload uses the same format as the `CardIssued` event of the [Prepaid Card User](#prepaid-card-user-webhook) and [Secured Credit Card User](#secured-credit-card-user-webhook) webhooks.

| Type                               | Event                 | Description                 |
| ---------------------------------- | --------------------- | --------------------------- |
| PrepaidCardPhysicalLifecycle       | CardPhysicalOrdered   | Physical card was ordered   |
| PrepaidCardPhysicalLifecycle       | CardPhysicalShipped   | Physical card was shipped   |
| PrepaidCardPhysicalLifecycle       | CardPhysicalDelivered | Physical card was delivered |
| SecuredCreditCardPhysicalLifecycle | CardPhysicalOrdered   | Physical card was ordered   |
| SecuredCreditCardPhysicalLifecycle | CardPhysicalShipped   | Physical card was shipped   |
| SecuredCreditCardPhysicalLifecycle | CardPhysicalDelivered | Physical card was delivered |

## Card Transaction webhook

{% tabs %}
{% tab title="NetworkDebit" %}

```json
{
  "Type": "PrepaidCardTransaction",
  "Event": "NetworkDebit",
  "EventGeneratedAt": "2026-03-31T19:46:21.0615358Z",
  "Data": {
    "Transaction": {
      "TransactionId": "511",
      "MessageType": "0200",
      "Date": "2026-03-31",
      "Time": "21:47:27",
      "CardAcceptor": {
        "AcquirerId": "ACQ987",
        "MerchantCode": "MERCH12345",
        "NameAndLocation": "AIR LANKA (ABBR. AIR LANKA). New York NY",
        "MerchantCity": "New York",
        "MerchantState": "NY",
        "MerchantZipCode": "10001",
        "MCC": "3044",
        "DeviceId": "POS001",
        "DeviceType": "Terminal",
        "LocalDateTime": "2026-03-06T11:20:30"
      },
      "TransactionType": "00",
      "TransactionAmount": -3.22,
      "TransactionResponseCode": "00",
      "NetworkId": "mastercard",
      "TransactionDescription": " Network Posted Debit Transaction"
    },
    "CardReferenceId": "599000170193",
    "UserCardId": "4be272ca-81b8-43d5-840a-aa23a514403e",
    "CardType": "PrepaidCard",
    "UserId": "4a78182b-4958-4f88-a50b-89f15835b81b"
  }
}

```

{% endtab %}

{% tab title="NonNetworkDebit" %}

```json
{
  "Type": "PrepaidCardTransaction",
  "Event": "NonNetworkDebit",
  "EventGeneratedAt": "2026-03-31T20:09:28.5640318Z",
  "Data": {
    "LocalDateTime": "2026-03-05T11:20:30",
    "TransactionId": "865",
    "Date": "2026-03-31",
    "Time": "21:47:27",
    "TransactionAmount": -1.2,
    "TransactionDescription": " NO - Network Posted Debit Transaction",
    "CardReferenceId": "599000170193",
    "UserCardId": "4be272ca-81b8-43d5-840a-aa23a514403e",
    "CardType": "PrepaidCard",
    "UserId": "4a78182b-4958-4f88-a50b-89f15835b81b"
  }
}
```

{% endtab %}

{% tab title="InactiveCardFee" %}

```json
{
  "Type": "PrepaidCardTransaction",
  "Event": "InactiveCardFee",
  "EventGeneratedAt": "2026-04-01T15:03:05.4325256Z",
  "Data": {
    "TransactionId": "7706",
    "Date": "2026-04-01",
    "Time": "00:53:29",
    "TransactionAmount": -1.5,
    "TransactionCurrency": "CAD",
    "TransactionDescription": "Fee - Card Inactivity",
    "CardReferenceId": "599000170193",
    "UserCardId": "4be272ca-81b8-43d5-840a-aa23a514403e",
    "CardType": "PrepaidCard",
    "UserId": "4a78182b-4958-4f88-a50b-89f15835b81b"
  }
}
```

{% endtab %}

{% tab title="WriteOff" %}

```json
{
  "Type": "PrepaidCardTransaction",
  "Event": "WriteOff",
  "EventGeneratedAt": "2026-07-07T13:56:04.0486369Z",
  "Data": {
    "TransactionId": "38476",
    "Date": "2026-07-07",
    "Time": "09:55:07",
    "TransactionAmount": 10.01,
    "TransactionCurrency": "CAD",
    "TransactionDescription": "Write off for $10.01",
    "UserCardId": "95d3c3e1-bd1d-44c8-8ebb-6606c65bdb01",
    "CardType": "PrepaidCard",
    "UserId": "8c60f95c-3706-4e9f-821b-97aadc3dc127"
  }
}
```

{% endtab %}
{% endtabs %}

<table><thead><tr><th width="257.515625">Type</th><th>Event</th><th>Description</th></tr></thead><tbody><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>NetworkDebit</td><td>Card network debit related financial transactions</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>NetworkCredit</td><td>Card network credit related financial transactions (same format as NetworkDebit)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>NetworkDecline</td><td>Card network decline related financial transactions (same format as NetworkDebit)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>NonNetworkDebit</td><td>Card non-network debit related financial transactions</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>NonNetworkCredit</td><td>Card non-network credit related financial transactions (same format as NonNetworkDebit)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>NonNetworkDecline</td><td>Card non-network decline related financial transactions (same format as NonNetworkDebit)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>TransactionReversal</td><td>Card transaction reversals (same format as NonNetworkDebit)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>InactiveCardFee</td><td>Card inactivity fee applied to the card</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>OverdraftFee</td><td>Card overdraft fee applied to the card (same format as InactiveCardFee)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>LatePaymentFee</td><td>Card late payment fee applied to the card (same format as InactiveCardFee)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>MaintenanceFee</td><td>Card maintenance fee applied to the card (same format as InactiveCardFee)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>IssuingCardFee</td><td>Card issuing fee applied to the card (same format as InactiveCardFee)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>ActivatedFee</td><td>Card activation fee applied to the card (same format as InactiveCardFee)</td></tr><tr><td>PrepaidCardTransaction</td><td>WriteOff</td><td>Card is written off due to negative balance based on the Negative Balance rule</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransaction</p></td><td>AcquirerFee</td><td>Custom card fee (same format as NonNetworkDebit)</td></tr><tr><td><p>PrepaidCardTransaction /</p><p>SecuredCreditCardTransactio</p></td><td>AcquirerFeeReversal</td><td>Reversal of the custom card fee (same format as NonNetworkDebit)</td></tr></tbody></table>

{% hint style="info" %}
A Prepaid card with a negative balance is written off after the number of days configured in the card program's Negative Balance Rule. Write-off transactions are not subject to transaction limits. The `WriteOff` event is available for `PrepaidCardTransaction` only.
{% endhint %}

**MessageType**

Based on the `Transaction` object, you can determine the type of transaction based on the following `Transaction.MessageType`

| Value | Description                   |
| ----- | ----------------------------- |
| 0200  | Posted Transaction Normal     |
| 0220  | Posted Transaction Force Post |
| 0400  | Posted Transaction Reversal   |
| 0420  | Posted Transaction Reversal   |
| 0100  | Pending Transaction           |
| 0120  | Pending Transaction           |
| 0720  | Fee-based Transaction         |
| 0722  | Fee-based Transaction         |

## Prepaid Card Send Money webhook

The webhook is triggered when a Prepaid cardholder sends an Interac e-Transfer from the Cardholder Portal. The payload uses the same format as the Transaction webhook.

| Type                 | Event     | Description                                       |
| -------------------- | --------- | ------------------------------------------------- |
| PrepaidCardSendMoney | Started   | Cardholder sent an Interac e-Transfer             |
| PrepaidCardSendMoney | Succeeded | The Interac e-Transfer was completed successfully |

## OTP webhook

{% tabs %}
{% tab title="CardholderPortalOtp" %}

```json
{
  "Type": "CardUserOTP",
  "Event": "CardHolderPortal",
  "EventGeneratedAt": "2026-03-31T15:25:51.9038934Z",
  "Data": {
    "CreateAt": "2026-03-31T15:25:51.9036441Z",
    "OtpMessage": "84059320",
    "OtpExpiry": "10",
    "UserEmail": "cardholder@example.com",
    "UserId": "007db275-bdfa-4869-b407-501698a52fdd"
  }
}
```

{% endtab %}

{% tab title="MobileWalletOtp" %}

```json
{
  "Type": "PrepaidCardOTP",
  "Event": "MobileWalletOtp",
  "EventGeneratedAt": "2026-04-01T13:22:03.6225619Z",
  "Data": {
    "WalletType": "ApplePay",
    "CardType": "SecuredCreditCard",
    "UserCardId": "fa9e1fd6-cc5a-478d-82f1-f6929e64c9d6",
    "CreateAt": "2026-04-30T00:00:00",
    "OtpMessage": "777880",
    "OtpExpiry": "10",
    "UserEmail": "cardholder@example.com",
    "UserId": "f1a816b1-a480-4fd9-b1eb-fff65f24c30d"
  }
}

```

{% endtab %}

{% tab title="ThreeDsOtp" %}

```json
{
  "Type": "SecuredCreditCardOTP",
  "Event": "ThreeDsOtp",
  "EventGeneratedAt": "2026-04-30T15:52:03.7613484Z",
  "Data": {
    "CardType": "SecuredCreditCard",
    "UserCardId": "fa9e1fd6-cc5a-478d-82f1-f6929e64c9d6",
    "CreateAt": "2026-04-30T00:00:00",
    "OtpMessage": "123456",
    "OtpExpiry": "2",
    "UserEmail": "cardholder@example.com",
    "UserId": "f1a816b1-a480-4fd9-b1eb-fff65f24c30d"
  }
}

```

{% endtab %}

{% tab title="PinResetOtp" %}

```json
{
  "Type": "PrepaidCardOTP",
  "Event": "PinResetOtp",
  "EventGeneratedAt": "2026-11-04T14:01:12.3301254Z",
  "Data": {
    "CardType": "PrepaidCard",
    "UserCardId": "9b2c7e4a-1f3d-4c5b-8a6e-2d7f0c1b3a45",
    "CreateAt": "2026-11-04T14:01:12.3299871Z",
    "OtpMessage": "123456",
    "OtpExpiry": "10",
    "UserEmail": "cardholder@example.com",
    "UserId": "6d1e8f2a-3b4c-4d5e-9f6a-7b8c9d0e1f2a"
  }
}
```

{% endtab %}
{% endtabs %}

PinSetOtp and PinUnblockOtp, and the SecuredCreditCardOTP Type, use the same format as PinResetOtp.

**OTP Event**

The `OtpExpiry` parameter is in minutes.

| Type                                            | Event               | Description                                                                                  |
| ----------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------- |
| CardUserOTP                                     | CardHolderPortalOtp | OTP for cardholder portal login                                                              |
| <p>PrepaidCardOTP /<br>SecuredCreditCardOTP</p> | MobileWalletOtp     | Prepaid card mobile wallet provisioning triggered an OTP request                             |
| <p>PrepaidCardOTP /<br>SecuredCreditCardOTP</p> | ThreeDsOtp          | Prepaid card online transaction triggered a 3DS OTP request (same format as MobileWalletOtp) |
| <p>PrepaidCardOTP /<br>SecuredCreditCardOTP</p> | PinSetOtp           | OTP sent to the cardholder to set the card PIN (see PinResetOtp example)                     |
| <p>PrepaidCardOTP /<br>SecuredCreditCardOTP</p> | PinResetOtp         | OTP sent to the cardholder to reset the card PIN                                             |
| <p>PrepaidCardOTP /<br>SecuredCreditCardOTP</p> | PinUnblockOtp       | OTP sent to the cardholder to unblock the card PIN (see PinResetOtp example)                 |

## Card Statement webhook

The webhook is triggered when a card statement is generated for a secured credit card User.

{% tabs %}
{% tab title="CardStatement" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "CardStatement",
  "EventGeneratedAt": "2026-06-02T19:22:53.1221004Z",
  "Data": {
    "UserId": "691e9d21-9bbe-4f18-91a0-b8e41f82b28c",
    "UserCardId": "3379c595-4136-4861-b373-dd56ad0dba7f",
    "StatementId": "994279e2-48e2-4490-a368-f5e417546f14",
    "StatementStartDate": "2026-05-01",
    "StatementEndDate": "2026-05-31",
    "StatementDate": "2026-05-01",
    "PaymentDueDate": "2026-05-25T00:00:00",
    "PreviousBalance": 146.65,
    "Payments": 0,
    "OtherCredits": 0,
    "Purchases": 0,
    "CashAdvance": 0,
    "InterestCharged": 0.7,
    "FeeCharged": 35,
    "NewBalance": 182.35,
    "MinimumPaymentDue": 0,
    "CreditLimit": 360,
    "AvailableCredit": 177.65,
    "PastDueAmount": 146.65,
    "BalanceTransfers": 0,
    "TotalFeesChargedYtd": 180.22,
    "TotalInterestChargedYtd": 2.13,
    "DaysAccountPastDue": 0,
    "StatementGenerated": true,
    "Transactions": [
      {
        "Id": "f7360548-7080-48a0-b238-a2a7110c5bf8",
        "TransactionId": "7706",
        "TransactionType": "FC",
        "MessageType": "0720",
        "Type": "Purchase",
        "Description": "Maintenance fee charged",
        "TransactionDate": "2026-05-07T00:00:00",
        "TransactionPostedDate": "2026-05-07T00:00:00",
        "Amount": 2
      },
      {
        "Id": "21d42176-b37e-4066-bcdd-27334075430f",
        "TransactionId": "7712",
        "TransactionType": "40",
        "MessageType": "0200",
        "Type": "Credit",
        "Description": "Payment",
        "TransactionDate": "2026-05-07T00:00:00",
        "TransactionPostedDate": "2026-05-07T00:00:00",
        "Amount": -22
      }
    ]
  }
}

```

{% endtab %}
{% endtabs %}

## Credit Trade Report webhook

The webhook is triggered when a Credit Trade Report record is generated for a secured credit card User.

{% tabs %}
{% tab title="CreditTradeReport" %}

```json
{
  "Type": "SecuredCreditCardUser",
  "Event": "CreditTradeReport",
  "EventGeneratedAt": "2026-03-31T15:25:51.9038934Z",
  "Data": {
    "ReportId": "d9583779-e523-4816-bc19-450edfa5077a",
    "ReportMonth": "202605",
    "UserId": "d9583779-e523-4816-bc19-450edfa5077a",
    "UserCardId": "d9583779-e523-4816-bc19-450edfa5077a",
    "TransactionMethod": "CreditCardIssuance",
    "CardType": "SecuredCreditCard",
    "CreatedAt": "2026-06-09T19:42:36.612431Z"
  }
}
```

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.zumrails.com/api-reference/webhooks.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
