# Managing Safe Ownership
Source: https://docs.gnosispay.com/account/adding-safe-owner

Add a new owner to a Gnosis Pay Safe Account

Adding a new owner to a Gnosis Pay Safe registers that account as a **Delay Module owner**.\
Only Delay Module owners can approve and execute on-chain transactions.

<Warning>
  **Important distinction:**

  * **Authenticated wallets** are linked to a Gnosis Pay user for API access (via SIWE and JWT).
  * **Safe owners (Delay Module owners)** are accounts explicitly added on-chain to the Safe.\
    Authenticated wallets do **not** become Safe owners unless they are also as owners for the safe.
</Warning>

This guide walks through the process of adding an additional Safe owner. Once complete, the new owner will be able to approve and execute transactions through the Delay Module.

<Steps>
  <Step title="Get a JWT token for the session">
    Follow the [authentication flow](https://docs.gnosispay.com/auth) to obtain a JWT token for the Gnosis Pay user.
  </Step>

  <Step title="Get typed data for adding a new Safe owner">
    Call [this endpoint](https://docs.gnosispay.com/api-reference/safe-owners/get-typed-data-for-adding-a-new-safe-owner) to receive the typed data.\
    Sign the typed data with the current Safe owner’s key to produce a signature.

    ```bash theme={null}
    curl --request GET \
      --url https://api.gnosispay.com/api/v1/owners/add/transaction-data \
      --header "Authorization: Bearer <token>"
    ```
  </Step>

  <Step title="Submit the signature">
    Send the new owner’s address, the signature, and the signed message to [this endpoint](https://docs.gnosispay.com/api-reference/safe-owners/add-a-new-owner-to-the-safe).

    ```bash theme={null}
    curl --request POST \
      --url https://api.gnosispay.com/api/v1/owners \
      --header "Authorization: Bearer <token>" \
      --header "Content-Type: application/json" \
      --data '{
        "newOwner": "0x3270bf32AB647e90eF94A026c70Aa1daaaDA2382",
        "signature": "0x1234567890abcdef...",
        "message": {
          "salt": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
          "data": "0xa9059cbb0000000000000000000000003270bf32ab647e90ef94a026c70aa1daaaada2382"
        }
      }'
    ```

    The operation is processed through the Delay Relay and executes after a 3-minute delay.
  </Step>

  <Step title="Verify ownership">
    Confirm that the new owner was added to the Delay Module by checking the [Safe’s owner list](https://docs.gnosispay.com/api-reference/safe-owners/get-the-list-of-safe-owners).

    ```bash theme={null}
    curl --request GET \
      --url https://api.gnosispay.com/api/v1/owners \
      --header "Authorization: Bearer <token>"
    ```
  </Step>
</Steps>


# Accounts on Gnosis Pay
Source: https://docs.gnosispay.com/account/index

How the Gnosis Pay Safe works

When a user signs up for Gnosis Pay, a new **Gnosis Pay Safe** a smart contract wallet is created on-chain.\
This Safe holds the user’s funds and is controlled only by its **owners**.

A Gnosis Pay Safe owner can be either:

* an **EOA (Externally Owned Account)**, or
* another **smart wallet** (e.g. a Safe) whose owners may use passkeys, EOAs, or other signers.

Funds in a Gnosis Pay Safe are never held by Gnosis Pay or any third party; ownership and control remain entirely with the Safe owners.

<Frame>
  <iframe title="YouTube video player" />
</Frame>

***

## Authenticating sessions with wallets

To access the Gnosis Pay dashboard or APIs, a wallet must authenticate using [Sign-In With Ethereum (SIWE)](https://docs.login.xyz/).\
After SIWE, a JWT token is issued and used to authorize API calls (e.g. ordering cards, fetching user info, or linking additional authenticated wallets).

Authenticated wallets are used **only for login and API sessions**. They do not perform on-chain actions and may or may not overlap with the Safe owners.

<Tip>
  The first wallet connected during setup is automatically registered as both an **authenticated wallet** and the **initial Safe owner** (via the Delay Module).
</Tip>

Follow the guide on [adding an authenticated wallet](account/update-authenticated-account) for step-by-step instructions.

***

## Safe Smart Account

Each Gnosis Pay user is assigned a **Safe Smart Account**, a self-custodied smart contract wallet deployed on Gnosis Chain (L1).\
Currently, a new Safe is deployed for every user. Support for connecting an existing Safe multisig is planned.

### What is a smart contract wallet?

Smart contract wallets are contracts that manage assets on-chain with programmable rules.\
They enable advanced security and automation beyond EOAs.

[Safe](https://safe.global/) is the leading smart contract wallet, securing over \$70B in assets.

### Exploring the Safe setup

Users can view their Safe configuration in the [Safe web app](https://app.safe.global/) via the Zodiac app:

1. Open the Gnosis Pay Dashboard.
2. Click **“View all transactions here”** to open the Safe web app.
3. In the sidebar, select **Applications**.
4. Search for **Zodiac**.

The **Roles Module** and **Delay Module** are open-source contracts licensed under LGPL 3.0.

***

## Modules

Modules extend Safe functionality with custom logic.\
In Gnosis Pay, modules enforce spending rules and transaction flows while keeping user funds in self-custody.

These modules follow the [Zodiac standard](https://gnosisguild.org/zodiac/) developed by Gnosis Guild.

***

## Roles Module

The Roles Module enforces which actions Gnosis Pay can perform on behalf of the user. It defines:

1. **Token used** → which token Gnosis Pay can spend.
2. **Daily limit** → maximum amount spendable per day.
3. **Recipient address** → destination for allowed transfers (e.g. the issuer’s settlement Safe).
4. **Role delegation** → assigns these permissions to Gnosis Pay.

Only Safe owners can update these rules.\
For example, a user may adjust the daily spending limit at any time.

***

## Delay Module

The Delay Module enforces a **3-minute delay** for all non-card transactions (e.g. transfers, deposits).\
This ensures funds remain available for card payments and prevents race conditions.

<Warning>
  During the 3-minute delay, the card is paused if any non-card transactions are pending.
</Warning>

The Delay Module also ensures the user’s EOA retains ultimate control.\
During activation, the EOA becomes an indirect Safe owner via the Delay Module.

⚠️ Reconfiguring or removing the Delay Module may prevent Gnosis Pay from functioning properly.

***

## What happens if I lose access to my EOA Wallet?

If you’ve forgotten the password to your EOA Wallet, you can regain access using its seed phrase.

<Warning>
  However, if you’ve lost access to the seed phrase and cannot regain access to the EOA, you will also lose access to the Safe if it’s the only owner.
</Warning>

**To mitigate this risk, consider using a [Safe](https://safe.global/) with multiple owners instead of an EOA.**


# Adding a new wallet for authentication
Source: https://docs.gnosispay.com/account/update-authenticated-account

Link an additional wallet address to a Gnosis Pay user

A Gnosis Pay user can have multiple authenticated wallets attached to their account.\
Authenticated wallets are used to sign in via SIWE and to start new API sessions.

<Steps>
  <Step title="Get a JWT token for the session">
    Follow the [authentication flow](https://docs.gnosispay.com/auth) to obtain a JWT token for the Gnosis Pay user.
  </Step>

  <Step title="Add a new wallet address">
    Make a POST call to [this endpoint](https://docs.gnosispay.com/api-reference/account-management/create-a-new-eoa-account-for-the-current-user) with the address to add.

    ```bash theme={null}
    curl --request POST \
      --url https://api.gnosispay.com/api/v1/eoa-accounts \
      --header "Authorization: Bearer <token>" \
      --header "Content-Type: application/json" \
      --data '{
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }'
    ```
  </Step>

  <Step title="Verify that the wallet was added">
    Call the [list accounts endpoint](https://docs.gnosispay.com/api-reference/account-management/retrieve-the-eoa-accounts-for-the-current-user).\
    The new address should appear in the response.

    ```bash theme={null}
    curl --request GET \
      --url https://api.gnosispay.com/api/v1/eoa-accounts \
      --header "Authorization: Bearer <token>"
    ```
  </Step>
</Steps>

<Warning>
  * Adding an **authenticated wallet** only links it to a Gnosis Pay user for login and API sessions.
  * An authenticated wallet is **not automatically a Safe owner**.
  * Only Safe owners (EOAs or smart wallets added to the Safe) can interact with the Delay Module or execute on-chain actions.
  * Authenticated wallets can use the API (e.g. place card orders, fetch user info) but **cannot control funds** unless also added as Safe owners.
</Warning>


# Add a new account address for authentication
Source: https://docs.gnosispay.com/api-reference/account-management/add-a-new-account-address-for-authentication

https://api.gnosispay.com/api-docs/spec.json post /api/v1/eoa-accounts
Registers a new authenticated account address for the authenticated user.
This address can be used to sign in via SIWE and to start new API sessions.




# Change Onchain Daily Limit with Signature
Source: https://docs.gnosispay.com/api-reference/account-management/change-onchain-daily-limit-with-signature

https://api.gnosispay.com/api-docs/spec.json put /api/v1/accounts/onchain-daily-limit
This endpoint is deprecated and will be removed in a future version.
Please use `PUT /api/v1/accounts/daily-limit` instead.

Sets a new onchain daily spending limit for the authenticated user's Safe account.
This endpoint requires a valid signature from the user's wallet to authorize the change.

The signature should be generated by signing the transaction data obtained from
the `/api/v1/accounts/onchain-daily-limit/transaction-data` endpoint.

The limit update is processed through a delay relay mechanism that executes after 3 minutes.

**Note:** The onchainDailyLimit must be an integer value between 1 and 8000.




# Get current daily spending limit
Source: https://docs.gnosispay.com/api-reference/account-management/get-current-daily-spending-limit

https://api.gnosispay.com/api-docs/spec.json get /api/v1/accounts/daily-limit
Retrieves the current daily spending limit for the authenticated user's Safe account.



# Get EIP-712 typed data for setting daily limit
Source: https://docs.gnosispay.com/api-reference/account-management/get-eip-712-typed-data-for-setting-daily-limit

https://api.gnosispay.com/api-docs/spec.json get /api/v1/accounts/daily-limit/transaction-data
Returns the EIP-712 typed data that needs to be signed by the user's wallet to set a new daily limit.
This endpoint is used as part of a three-step process:
1. Call this endpoint to get the EIP-712 typed data
2. Sign the typed data with the user's wallet using EIP-712 signature standard
3. Submit the signature to the PUT `/api/v1/accounts/daily-limit` endpoint

**Note:** The newLimit must be an integer value between 1 and 8000.




# List authenticated account addresses
Source: https://docs.gnosispay.com/api-reference/account-management/list-authenticated-account-addresses

https://api.gnosispay.com/api-docs/spec.json get /api/v1/eoa-accounts
Returns a list of addresses associated with the authenticated user.



# Remove account address for authentication
Source: https://docs.gnosispay.com/api-reference/account-management/remove-account-address-for-authentication

https://api.gnosispay.com/api-docs/spec.json delete /api/v1/eoa-accounts/{id}
Removes the account address associated with the authenticated user.



# Retrieve Account Balance
Source: https://docs.gnosispay.com/api-reference/account-management/retrieve-account-balance

https://api.gnosispay.com/api-docs/spec.json get /api/v1/account-balances
Retrieves the balance information for the authenticated user (total, spendable and pending balances)



# Retrieve Onchain Daily Limit
Source: https://docs.gnosispay.com/api-reference/account-management/retrieve-onchain-daily-limit

https://api.gnosispay.com/api-docs/spec.json get /api/v1/accounts/onchain-daily-limit
This endpoint is deprecated and will be removed in a future version.
Please use `GET /api/v1/accounts/daily-limit` instead.

Retrieves the current onchain daily spending limit for the authenticated user's Safe account.




# Retrieve Transaction Data for changing Daily Limit
Source: https://docs.gnosispay.com/api-reference/account-management/retrieve-transaction-data-for-changing-daily-limit

https://api.gnosispay.com/api-docs/spec.json get /api/v1/accounts/onchain-daily-limit/transaction-data
This endpoint is deprecated and will be removed in a future version.
Please use `GET /api/v1/accounts/daily-limit/transaction-data` instead.

Returns the transaction data that needs to be signed by the user's wallet to set a new onchain daily limit.
This endpoint is used as part of a three-step process:
1. Call this endpoint to get the transaction data
2. Sign the transaction data with the user's wallet
3. Submit the signature to the PUT `/api/v1/accounts/onchain-daily-limit` endpoint

**Note:** The onchainDailyLimit must be an integer value between 1 and 8000.




# Retrieve Transaction Data for Withdrawing from Safe
Source: https://docs.gnosispay.com/api-reference/account-management/retrieve-transaction-data-for-withdrawing-from-safe

https://api.gnosispay.com/api-docs/spec.json get /api/v1/accounts/withdraw/transaction-data
Returns the EIP-712 typed data that needs to be signed by the user's wallet to withdraw ERC20 tokens or native tokens (xDAI) from the user's Safe account.

For ERC20 tokens, provide the token contract address.
For native token (xDAI) withdrawals, use "0x0000000000000000000000000000000000000000" as the tokenAddress.

This endpoint is used as part of a three-step process:
1. Call this endpoint to get the EIP-712 typed data
2. Sign the typed data with the user's wallet using EIP-712 signature standard
3. Submit the signature to the POST `/api/v1/accounts/withdraw` endpoint




# Set new daily spending limit
Source: https://docs.gnosispay.com/api-reference/account-management/set-new-daily-spending-limit

https://api.gnosispay.com/api-docs/spec.json put /api/v1/accounts/daily-limit
Sets a new daily spending limit for the authenticated user's Safe account.

The signature should be generated by signing the EIP-712 typed data obtained from
the `/api/v1/accounts/daily-limit/transaction-data` endpoint.
If using a smart wallet, the smartWalletAddress is required for ERC1271 signatures.

The limit update is processed through a delay relay mechanism that executes after 3 minutes.

**Note:** The newLimit must be an integer value between 1 and 8000.




# Withdraw from Safe with Signature
Source: https://docs.gnosispay.com/api-reference/account-management/withdraw-from-safe-with-signature

https://api.gnosispay.com/api-docs/spec.json post /api/v1/accounts/withdraw
Withdraws ERC20 tokens or native tokens (xDAI) from the user's Safe account.

For ERC20 tokens, provide the token contract address.
For native token (xDAI) withdrawals, use "0x0000000000000000000000000000000000000000" as the tokenAddress.

The signature should be generated by signing the transaction data obtained from
the `/api/v1/accounts/withdraw/transaction-data` endpoint.

The withdrawal is processed through a delay relay mechanism that executes after 3 minutes.




# Authentication Helper App
Source: https://docs.gnosispay.com/api-reference/auth-app

Use this app to generate and sign a message using your ethereum wallet.

<a href="https://gnosispay-api-siwe-demo.vercel.app/">
  You can also open this app in a new tab.
</a>

<AuthApp />


# Create a new User
Source: https://docs.gnosispay.com/api-reference/authentication/create-a-new-user

https://api.gnosispay.com/api-docs/spec.json post /api/v1/auth/signup
This endpoint creates a new `User` associating it with the provided email address.



# Generate nonce
Source: https://docs.gnosispay.com/api-reference/authentication/generate-nonce

https://api.gnosispay.com/api-docs/spec.json get /api/v1/auth/nonce



# Request OTP for email verification
Source: https://docs.gnosispay.com/api-reference/authentication/request-otp-for-email-verification

https://api.gnosispay.com/api-docs/spec.json post /api/v1/auth/signup/otp
This endpoint generates and sends a one-time password (OTP) to the provided email address for verification purposes.



# Verify SIWE signature
Source: https://docs.gnosispay.com/api-reference/authentication/verify-siwe-signature

https://api.gnosispay.com/api-docs/spec.json post /api/v1/auth/challenge



# Activate a Card
Source: https://docs.gnosispay.com/api-reference/card-management/activate-a-card

https://api.gnosispay.com/api-docs/spec.json post /api/v1/cards/{cardId}/activate
## Prerequisites
- Card must have not been activated
- A Safe Account should be set for the authenticated user

If those conditions are met, the card is then activated.
The activated time will be the moment that this endpoint was triggered, in UTC.

:::info
This action also notifies the user by email
:::

:::caution
 Be sure to have a Safe Account associated with the user. If a Safe Account is not tied to the user the endpoint will fail.

 To check if a user has a Safe Account, you can get the User details via `GET /api/v1/user` and check if there's at least one `safeWallets` tied to the user.

 A Safe Account can be created via `POST /api/v1/account`
 :::




# Create a Virtual Card
Source: https://docs.gnosispay.com/api-reference/card-management/create-a-virtual-card

https://api.gnosispay.com/api-docs/spec.json post /api/v1/cards/virtual
Creates a virtual card without requiring a Card Order.
Virtual cards are free and activated immediately.
No shipping address or payment validation is required.

**Card Limits**: Users can have a maximum of 5 active cards (physical + virtual combined).
Active cards exclude voided, lost, and stolen cards.




# Freeze a Card
Source: https://docs.gnosispay.com/api-reference/card-management/freeze-a-card

https://api.gnosispay.com/api-docs/spec.json post /api/v1/cards/{cardId}/freeze
This will prevent the card from being used for any transactions.

:::info
The card can be frozen and unfrozen instantly and multiple times.
:::




# Get a Card status
Source: https://docs.gnosispay.com/api-reference/card-management/get-a-card-status

https://api.gnosispay.com/api-docs/spec.json get /api/v1/cards/{cardId}/status



# Link physical card to user
Source: https://docs.gnosispay.com/api-reference/card-management/link-physical-card-to-user

https://api.gnosispay.com/api-docs/spec.json post /api/v1/cards/verify
Verifies a card by decrypting PAN details and associating it with the authenticated user



# List all Cards
Source: https://docs.gnosispay.com/api-reference/card-management/list-all-cards

https://api.gnosispay.com/api-docs/spec.json get /api/v1/cards



# Report a Card as lost
Source: https://docs.gnosispay.com/api-reference/card-management/report-a-card-as-lost

https://api.gnosispay.com/api-docs/spec.json post /api/v1/cards/{cardId}/lost



# Report a Card as stolen
Source: https://docs.gnosispay.com/api-reference/card-management/report-a-card-as-stolen

https://api.gnosispay.com/api-docs/spec.json post /api/v1/cards/{cardId}/stolen



# Revert a Card freeze
Source: https://docs.gnosispay.com/api-reference/card-management/revert-a-card-freeze

https://api.gnosispay.com/api-docs/spec.json post /api/v1/cards/{cardId}/unfreeze
This will allow the card to be used for transactions. The card needs to be active and in a frozen state.

:::info
The card can be frozen and unfrozen instantly and multiple times.
:::




# Void a Virtual Card
Source: https://docs.gnosispay.com/api-reference/card-management/void-a-virtual-card

https://api.gnosispay.com/api-docs/spec.json post /api/v1/cards/{cardId}/void
Void a virtual card. Only virtual cards can be voided using this endpoint.



# Retrieve Cashback Information
Source: https://docs.gnosispay.com/api-reference/cashback/retrieve-cashback-information

https://api.gnosispay.com/api-docs/spec.json get /api/v1/cashback
Returns user's OG status, GNO balance of Safe, cashback rate, and weekly spending cap.
The cashback rate is based on GNO balance tiers and includes the OG NFT holder bonus if applicable.

**Note:** This cashback structure is valid from November 1st, 2025.




# Generate a new ephemeral token
Source: https://docs.gnosispay.com/api-reference/endpoints/generate-a-new-ephemeral-token

https://api-pse-public.gnosispay.com/api-docs/spec.json post /api/v1/ephemeral-token
Generates a new ephemeral token for secure PCI operations.

Ephemeral tokens are single-use tokens with a short lifespan (60 seconds) that are used to authorize sensitive
PCI operations like retrieving card details or setting a PIN.

This endpoint requires mTLS (Mutual TLS) authentication using a valid client certificate.

The client certificate must be issued by a trusted Certificate Authority and contain valid
partner identifier in its subject.

## mTLS Requirements
- Certificate must be issued by a trusted Certificate Authority
- Certificate must contain a valid partner app ID in the CN (Common Name) field
- Certificate must be valid and not expired
- Certificate must be presented during the TLS handshake

Example certificate subject format:
```
CN=gp_f1a9b6c741c94510bb3b27f2e8379e29,C=US
```

## Testing the Endpoint
Due to browser limitations, this endpoint cannot be tested directly in Swagger UI. Use one of the following methods:

### Using cURL
```bash
curl -X POST --cert client.crt --key client.key https://${{AUTHENTICATED_PSE_API_URL}}/api/v1/ephemeral-token
```

**Certificate and Key Format Requirements:**
- **Certificate file (`.crt/.pem`)** and **Private key file (`.key/.pem`)**: both must be in PEM format

Example certificate format:
```
-----BEGIN CERTIFICATE-----
MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2oCiwYwDQYJKoZIhvcNAQELBQAw
... (base64 encoded certificate data) ...
-----END CERTIFICATE-----
```

Example private key format:
```
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7VJTUt9Us8cKB
... (base64 encoded private key data) ...
-----END PRIVATE KEY-----
```

**Important Notes:**
- Ensure certificate and key files have proper line endings
- Certificate and key files should be readable by the client application
- The private key must correspond to the certificate being used
- Certificate must be valid and not expired

### Using Postman
1. Go to Settings > Certificates
2. Add your client certificate and private key
3. Make sure to select the certificate for the correct host

### Using Node.js
```javascript
import https from "https";

const httpsAgent = new https.Agent({
  cert: CERT,
  key: KEY,
  rejectUnauthorized: true,
});

const req = https.request(
  {
    hostname: "api-pse.gnosispay.com",
    path: "/api/v1/ephemeral-token",
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "User-Agent": "User-Client/1.0.0",
    },
    agent: httpsAgent,
  },
  (res) => {
    let data = "";
    res.on("data", (chunk) => {
      data += chunk;
    });

    res.on("end", () => {
      console.log("Status:", res.statusCode);

      try {
        const parsedData = JSON.parse(data);
        console.log("Response:", parsedData);
      } catch {
        console.log("Raw response:", data);
      }
    });
  },
);

req.on("error", (error) => {
  console.error("Request error:", error);
});
req.end();
```




# Check IBAN Availability
Source: https://docs.gnosispay.com/api-reference/iban/check-iban-availability

https://api.gnosispay.com/api-docs/spec.json get /api/v1/ibans/available
Returns whether the user is eligible to enable an IBAN on their account.



# Create a new Monerium integration
Source: https://docs.gnosispay.com/api-reference/iban/create-a-new-monerium-integration

https://api.gnosispay.com/api-docs/spec.json post /api/v1/integrations/monerium
Creates a new Monerium integration for the authenticated user and associates it with the authenticated user's EOA address.
All operations on Monerium are done through their API, this endpoint is just a way to reuse the GP KYC to open an account on Monerium.

- If the user does not have a Monerium account, this endpoint will create a new one and associate it with the authenticated user's EOA address.
- If the user already has a Monerium account, you do not need to call this endpoint again.

Just use the Monerium API directly to request access to the user's monerium account.
Check their documentation for more information: https://monerium.dev/api-docs/v2




# Get the message that needs to be signed for IBAN activation
Source: https://docs.gnosispay.com/api-reference/iban/get-the-message-that-needs-to-be-signed-for-iban-activation

https://api.gnosispay.com/api-docs/spec.json get /api/v1/ibans/signing-message
Returns the standard message that users need to sign with their wallet to verify ownership for Monerium IBAN activation.



# Retrieve a list of Monerium IBAN orders
Source: https://docs.gnosispay.com/api-reference/iban/retrieve-a-list-of-monerium-iban-orders

https://api.gnosispay.com/api-docs/spec.json get /api/v1/ibans/orders
Returns a list of IBAN orders associated with the authenticated user.



# Retrieve IBAN details
Source: https://docs.gnosispay.com/api-reference/iban/retrieve-iban-details

https://api.gnosispay.com/api-docs/spec.json get /api/v1/ibans/details
Returns IBAN details including the IBAN number, BIC, and Status.



# API Reference Introduction
Source: https://docs.gnosispay.com/api-reference/intro

General guidelines on how to integrate with GnosisPay.

Gnosis Pay offers an HTTP JSON API, fully documented using [OpenAPI—you can find our specification here](https://api.gnosispay.com/api-docs/spec.json). This API reference is auto-generated from our OpenAPI spec, and you can also use the JSON file to generate client code in various programming languages.

Most API endpoints require authentication with a [JWT obtained via Sign-In with Ethereum (SIWE)](/auth). For your convenience, we provide a [helper app](/api-reference/auth-app) within these docs to help you generate a token and sign Safe transactions.

To make API requests using the API Reference playground, simply paste your token into the Authorization Header field.


# Answer Source of Funds questions
Source: https://docs.gnosispay.com/api-reference/kyc/answer-source-of-funds-questions

https://api.gnosispay.com/api-docs/spec.json post /api/v1/source-of-funds



# Retrieve a KYC Sharing Token for Sumsub Partners
Source: https://docs.gnosispay.com/api-reference/kyc/retrieve-a-kyc-sharing-token-for-sumsub-partners

https://api.gnosispay.com/api-docs/spec.json post /api/v1/kyc/import-partner-applicant



# Retrieve Access Token for Sumsub SDK Integration
Source: https://docs.gnosispay.com/api-reference/kyc/retrieve-access-token-for-sumsub-sdk-integration

https://api.gnosispay.com/api-docs/spec.json get /api/v1/kyc/integration/sdk
Retrieve the specification to follow with the KYC integration.



# Retrieve an OTP code to verify a Phone Number
Source: https://docs.gnosispay.com/api-reference/kyc/retrieve-an-otp-code-to-verify-a-phone-number

https://api.gnosispay.com/api-docs/spec.json post /api/v1/verification
This call replaces the existing phone number for a user if it exists, whether it's verified or not.



# Retrieve Link for Web Integration
Source: https://docs.gnosispay.com/api-reference/kyc/retrieve-link-for-web-integration

https://api.gnosispay.com/api-docs/spec.json get /api/v1/kyc/integration
Retrieve the specification to follow with the KYC integration.



# Retrieve Source of Funds questions
Source: https://docs.gnosispay.com/api-reference/kyc/retrieve-source-of-funds-questions

https://api.gnosispay.com/api-docs/spec.json get /api/v1/source-of-funds



# Verify a Phone Number (with OTP Code)
Source: https://docs.gnosispay.com/api-reference/kyc/verify-a-phone-number-with-otp-code

https://api.gnosispay.com/api-docs/spec.json post /api/v1/verification/check



# Attach a coupon to a Physical Card Order
Source: https://docs.gnosispay.com/api-reference/physical-card-order/attach-a-coupon-to-a-physical-card-order

https://api.gnosispay.com/api-docs/spec.json post /api/v1/order/{orderId}/attach-coupon
This endpoint associates a provided coupon code with an existing card order by its `orderId`. Use the `GPDOCS` coupon code to get the card for free.



# Cancel a Physical Card Order
Source: https://docs.gnosispay.com/api-reference/physical-card-order/cancel-a-physical-card-order

https://api.gnosispay.com/api-docs/spec.json post /api/v1/order/{orderId}/cancel
This endpoint transitions the card order to the cancelled state.



# Confirm the payment for a Physical Card Order
Source: https://docs.gnosispay.com/api-reference/physical-card-order/confirm-the-payment-for-a-physical-card-order

https://api.gnosispay.com/api-docs/spec.json put /api/v1/order/{orderId}/confirm-payment
This endpoint marks the Card Order with `orderId` as paid. Even if the card is free, you need to call this endpoint to confirm the payment.



# Create a Physical Card
Source: https://docs.gnosispay.com/api-reference/physical-card-order/create-a-physical-card

https://api.gnosispay.com/api-docs/spec.json post /api/v1/order/{orderId}/create-card
The last step in the physical card creation process.

**Note:** To apply a coupon code, use the `/api/v1/order/{orderId}/attach-coupon` endpoint before creating the card.

**Validation Requirements:**
- User must have completed KYC successfully
- User must have a verified phone number
- User must have name and address set
- User's country must be supported
- User must not have reached maximum active cards limit
- Safe account should be setup
- User must not have existing pending card orders
- For paid cards, a valid transaction hash is required




# Create Physical Card Order
Source: https://docs.gnosispay.com/api-reference/physical-card-order/create-physical-card-order

https://api.gnosispay.com/api-docs/spec.json post /api/v1/order/create
Orders a new physical card for the authenticated user.
This is the first step in the physical card order process, the card is not created yet.

Next are the steps to complete the order:
1. Optionally attach a coupon using `/api/v1/order/{orderId}/attach-coupon` (use the `GPDOCS` coupon code to get the card for free)
2. If not free, attach a transaction hash using `/api/v1/order/{orderId}/attach-transaction`
3. Confirm the payment using `/api/v1/order/{orderId}/confirm-payment`
4. Create the card using `/api/v1/order/{orderId}/create-card`




# List Physical Card Orders
Source: https://docs.gnosispay.com/api-reference/physical-card-order/list-physical-card-orders

https://api.gnosispay.com/api-docs/spec.json get /api/v1/order/
Retrieves all physical card orders for the authenticated user



# Register payment for a Physical Card Order
Source: https://docs.gnosispay.com/api-reference/physical-card-order/register-payment-for-a-physical-card-order

https://api.gnosispay.com/api-docs/spec.json put /api/v1/order/{orderId}/attach-transaction
This endpoint associates a provided on-chain transaction hash with an existing card order by its `orderId`. If the card is free, you can skip this step.



# Retrieve details of a Physical Card Order
Source: https://docs.gnosispay.com/api-reference/physical-card-order/retrieve-details-of-a-physical-card-order

https://api.gnosispay.com/api-docs/spec.json get /api/v1/order/{orderId}
This endpoint retrieves details of a card order by its `orderId`.



# Retrieve Rewards Information
Source: https://docs.gnosispay.com/api-reference/rewards/retrieve-rewards-information

https://api.gnosispay.com/api-docs/spec.json get /api/v1/rewards
Returns user's OG status, GNO balance of Safe, and calculated base cashback rate.
Note that the cashbackRate returned does not include the +1% bonus for OG NFT holders - to get the total cashback rate, add 1% to the cashbackRate if isOg is true.




# Add Safe Owner
Source: https://docs.gnosispay.com/api-reference/safe-management/add-safe-owner

https://api.gnosispay.com/api-docs/spec.json post /api/v1/owners
Adds a new owner to the user's Safe account.

The signature should be generated by signing the transaction data obtained from
the `/api/v1/owners/add/transaction-data` endpoint.

The operation is processed through a delay relay mechanism that executes after 3 minutes.




# Deploy and Setup a Safe
Source: https://docs.gnosispay.com/api-reference/safe-management/deploy-and-setup-a-safe

https://api.gnosispay.com/api-docs/spec.json post /api/v1/safe/deploy
Deploys and sets up the Safe account for the authenticated user.
The User needs to be KYC approved.

This endpoint replaces the `POST /api/v1/account` and related endpoints.
Using this endpoint, the user can deploy the Safe without having to sign the data.

This endpoint is idempotent: calling it again while a deployment is
already in flight for the same user will return `202` without starting
a new workflow. Use `GET /api/v1/safe/deploy` as the source of truth
for deployment status (`processing`, `ok`, `failed`, `not_deployed`).




# Get the Safe deployment status.
Source: https://docs.gnosispay.com/api-reference/safe-management/get-the-safe-deployment-status

https://api.gnosispay.com/api-docs/spec.json get /api/v1/safe/deploy
Returns the deployment status of the Safe account for the authenticated user.



# Get typed data for adding a Safe Owner
Source: https://docs.gnosispay.com/api-reference/safe-management/get-typed-data-for-adding-a-safe-owner

https://api.gnosispay.com/api-docs/spec.json get /api/v1/owners/add/transaction-data
Returns the EIP-712 typed data that needs to be signed by the user's wallet to add a new owner to the Safe.
This endpoint is used as part of a three-step process:
1. Call this endpoint to get the EIP-712 typed data
2. Sign the typed data with the user's wallet using EIP-712 signature standard
3. Submit the signature to the POST `/api/v1/owners` endpoint




# Get typed data for removing a Safe Owner
Source: https://docs.gnosispay.com/api-reference/safe-management/get-typed-data-for-removing-a-safe-owner

https://api.gnosispay.com/api-docs/spec.json get /api/v1/owners/remove/transaction-data
Returns the EIP-712 typed data that needs to be signed by the user's wallet to remove an owner from the Safe.
This endpoint is used as part of a three-step process:
1. Call this endpoint to get the EIP-712 typed data
2. Sign the typed data with the user's wallet using EIP-712 signature standard
3. Submit the signature to the DELETE `/api/v1/owners` endpoint




# List Delayed Transactions
Source: https://docs.gnosispay.com/api-reference/safe-management/list-delayed-transactions

https://api.gnosispay.com/api-docs/spec.json get /api/v1/delay-relay
Returns an array of delayed transactions associated with the authenticated user, excluding failed transactions.



# List Safe Owners
Source: https://docs.gnosispay.com/api-reference/safe-management/list-safe-owners

https://api.gnosispay.com/api-docs/spec.json get /api/v1/owners
Returns the list of addresses that are owners of the user's Safe account.
These owners have the ability to sign transactions and manage the Safe.




# Remove Safe Owner
Source: https://docs.gnosispay.com/api-reference/safe-management/remove-safe-owner

https://api.gnosispay.com/api-docs/spec.json delete /api/v1/owners
Removes an existing owner from the user's Safe account.

The signature should be generated by signing the transaction data obtained from
the `/api/v1/owners/remove/transaction-data` endpoint.

The operation is processed through a delay relay mechanism that executes after 3 minutes.




# Reset Safe Account
Source: https://docs.gnosispay.com/api-reference/safe-management/reset-safe-account

https://api.gnosispay.com/api-docs/spec.json delete /api/v1/safe/reset
Permanently deletes the Safe account for the authenticated user. This operation is irreversible and should be used with caution.

**Prerequisites for Safe Reset:**
- Safe account must exist for the user
- Safe account must not be in a properly configured state (AccountIntegrityStatus.Ok)
- Safe account must not have transactions in the delay queue (AccountIntegrityStatus.DelayQueueNotEmpty)
- User must not have any active (non-voided) cards linked to the Safe
- Safe account must have zero token balance (all tokens must be withdrawn first)

**Use Cases:**
- Reset a Safe account that failed during deployment or setup
- Clean up a Safe account that is in an inconsistent state
- Remove a Safe account before creating a new one

**Important Notes:**
- This operation permanently deletes the Safe account record from the database
- The actual Safe contract on-chain is not affected by this operation
- Users will need to deploy a new Safe account after reset




# Retrieve Safe Configuration
Source: https://docs.gnosispay.com/api-reference/safe-management/retrieve-safe-configuration

https://api.gnosispay.com/api-docs/spec.json get /api/v1/safe/config
Returns the configuration of the Safe account associated with the authenticated user, including deployment status, approvals, and account status and allowance details from the chain.



# Retrieve Safe migration status
Source: https://docs.gnosispay.com/api-reference/safe-management/retrieve-safe-migration-status

https://api.gnosispay.com/api-docs/spec.json get /api/v1/safe/migration
Returns the current safe, previous safe (if migrated), and migration status for the authenticated user.



# Set Safe Currency
Source: https://docs.gnosispay.com/api-reference/safe-management/set-safe-currency

https://api.gnosispay.com/api-docs/spec.json post /api/v1/safe/set-currency
This endpoint sets the appropriate token symbol (currency) for a user's Safe account based on their country.
It should be called after deploying a Safe account using the /api/v1/account endpoint.

The system assigns currencies based on user's country:
- UK users (GB): GBPe
- Brazil users (BR): USDCe
- Users from other countries: EURe (default)

Prerequisite: User must have completed and passed KYC verification.




# Retrieve all Terms and Conditions
Source: https://docs.gnosispay.com/api-reference/terms/retrieve-all-terms-and-conditions

https://api.gnosispay.com/api-docs/spec.json get /api/v1/terms
This endpoint provides public access to terms information including type,
current version, URL, and name.




# Dispute a Transaction
Source: https://docs.gnosispay.com/api-reference/transactions/dispute-a-transaction

https://api.gnosispay.com/api-docs/spec.json post /api/v1/transactions/{threadId}/dispute
Create a ticket to dispute a transaction. The list of available dispute reason keys can be found in the `GET /api/v1/transactions/dispute` endpoint.
If the dispute reason is `unrecognized_transaction_report_fraudulent`, the user's card will be restricted.




# List Card Transactions
Source: https://docs.gnosispay.com/api-reference/transactions/list-card-transactions

https://api.gnosispay.com/api-docs/spec.json get /api/v1/cards/transactions
Retrieves paginated transactions for all activated cards of the authenticated user.

Returns three types of transaction events:
- **Payment**: Regular card transactions (purchases, ATM withdrawals). Can appear immediately after authorization with `isPending: true`, then update when cleared.
- **Refund**: Money returned to your account (product returns, cancellations). Only appears after both authorization and clearing are processed.
- **Reversal**: Cancellation of previous transactions due to technical issues or merchant corrections. Can appear immediately after authorization-level reversals.

The final number might differ slightly, as one thread might contain multiple transactions.




# List Dispute Reasons
Source: https://docs.gnosispay.com/api-reference/transactions/list-dispute-reasons

https://api.gnosispay.com/api-docs/spec.json get /api/v1/transactions/dispute
Returns a list of available dispute reasons keys with their human-readable text. The keys need to be used in the dispute reason field when creating a dispute.



# List Transactions (without pagination)
Source: https://docs.gnosispay.com/api-reference/transactions/list-transactions-without-pagination

https://api.gnosispay.com/api-docs/spec.json get /api/v1/transactions
This endpoint is deprecated. Please use [/api/v1/cards/transactions](#/Transactions/get_api_v1_cards_transactions) instead. Retrieves transactions for all activated cards of the authenticated user




# Accept Terms and Conditions
Source: https://docs.gnosispay.com/api-reference/user/accept-terms-and-conditions

https://api.gnosispay.com/api-docs/spec.json post /api/v1/user/terms
Accept specific terms and conditions based on type and version.



# Get card public key
Source: https://docs.gnosispay.com/api-reference/user/get-card-public-key

https://api.gnosispay.com/api-docs/spec.json get /api/v1/user/card-public-key



# Retrieve Terms and Conditions Status
Source: https://docs.gnosispay.com/api-reference/user/retrieve-terms-and-conditions-status

https://api.gnosispay.com/api-docs/spec.json get /api/v1/user/terms
Returns the status of all terms and conditions, including whether the user has accepted
the latest version, when they were accepted, and links to the terms documents.




# Retrieve User profile
Source: https://docs.gnosispay.com/api-reference/user/retrieve-user-profile

https://api.gnosispay.com/api-docs/spec.json get /api/v1/user
Get the User profile information.



# Check if authenticated user is subscribed to partner webhooks
Source: https://docs.gnosispay.com/api-reference/webhooks/check-if-authenticated-user-is-subscribed-to-partner-webhooks

https://api.gnosispay.com/api-docs/spec.json get /api/v1/webhooks/subscription/{partnerId}
Allows the authenticated user to check if they are subscribed to a partner's webhook notifications.



# Retrieve Message to Sign for Webhook Subscription
Source: https://docs.gnosispay.com/api-reference/webhooks/retrieve-message-to-sign-for-webhook-subscription

https://api.gnosispay.com/api-docs/spec.json get /api/v1/webhooks/message/{partnerId}
Generates a message for the user to sign. This message must be sent on `POST /api/v1/webhooks/subscribe/{partnerId}` to subscribe to webhook notifications.



# Subscribe to Webhooks
Source: https://docs.gnosispay.com/api-reference/webhooks/subscribe-to-webhooks

https://api.gnosispay.com/api-docs/spec.json post /api/v1/webhooks/subscribe/{partnerId}
Allows a partner to receive webhook notifications for the authenticated user.



# Authentication Flow
Source: https://docs.gnosispay.com/auth

Use Sign-In with Ethereum (SIWE) to authenticate API requests.

Our authentication system uses Sign-In with Ethereum (SIWE) to generate a `jwt` to interact with our API.
This means you don't need to handle the storage of a powerful API key or spend hours configuring granular permissions.

<Info>
  **For Partners**: If you're building a partner integration, make sure to register your domains through the [Partners Dashboard](https://partners.gnosispay.com/) during signup. This ensures your domains are whitelisted for SIWE authentication and prevents authentication failures.
</Info>

## Authentication Process

<Steps>
  <Step title="Generate a Nonce to sign a SIWE Message">
    Before initiating authentication, [the application must request a nonce](/api-reference/authentication/generate-nonce).
    Your application then presents this nonce to the user for signing as part of the SIWE flow.

    ```bash cURL theme={null}
    curl -X GET /api/v1/auth/nonce
    ```
  </Step>

  <Step title="Sign the SIWE Message with your Wallet or Provider">
    Our API accepts signatures from Externally Owned Accounts (EOAs) and Smart Accounts (EIP-1271).

    <Warning>
      The signer must be an owner of a Gnosis Pay account.
      Non-registered users will receive `401 Unauthorized` on most authenticated routes
    </Warning>
  </Step>

  <Step title="Verify the Signature and get an Access Token">
    <Note>
      **JWT length validity**

      * **Default Validity**: JWT tokens are valid for the duration specified in `ttlInSeconds` during SIWE authentication
      * **Minimum Duration**: 1 hour
      * **Maximum Duration**: 24 hours
    </Note>

    After the message is signed, you need to submit both the message and the signature to [retrieve an Access Token](/api-reference/authentication/verify-siwe-signature):

    ```bash cURL theme={null}
    curl -X POST /api/v1/auth/challenge \
      -H "Content-Type: application/json" \
      -d '{
        "message": "string",
        "signature": "string",
        "ttlInSeconds": 36000
      }'
    ```
  </Step>
</Steps>

<Warning>
  **Domain Whitelisting**: Gnosis Pay validates SIWE domains against a whitelist for security.

  * **localhost**: `localhost` (with or without ports like `localhost:3000`) is automatically allowed for local development
  * **Production domains**: All production and staging domains must be registered through the [Partners Dashboard](https://partners.gnosispay.com/) during signup
  * **127.0.0.1**: Avoid using `127.0.0.1` in SIWE messages as it may cause firewall blocks and "WAFForbidden" errors

  Only whitelisted domains (plus localhost) will be accepted for SIWE authentication.
</Warning>

Upon successful verification, a `jwt` is generated.
This `jwt` must be included in the Authorization header of all subsequent HTTP requests to authenticate with the Gnosis Pay API:

```bash theme={null}
Authorization: Bearer {jwt}
```

## Details about the Access Token

A `jwt` is generated upon successful Sign-In with Ethereum (SIWE) verification and can remain valid for up to **24 hours**, depending on the **`ttlInSeconds`** parameter passed to SIWE, with a minimum validity period of 1 hour.

To enhance security and prevent replay attacks, each authentication attempt requires a new and unique nonce.

Always ensure that the `jwt` is valid before making API requests.
If an API request returns a 401 Unauthorized response due to an expired token,
your application must restart the authentication process, which requires user interaction.
This means the application must request a new nonce, prompt the user to sign the message,
and then submit the signature for verification to generate a fresh `jwt`.


# Card Order State Transitions
Source: https://docs.gnosispay.com/cards/card-order-state-transitions

Understanding the card order state transitions

Below is the complete state transition diagram and detailed explanations.

### State Transition Diagram

```mermaid theme={null}
  stateDiagram-v2
  [*] --> PENDINGTRANSACTION : Create Order

  PENDINGTRANSACTION --> READY : Pay (free or paid)
  PENDINGTRANSACTION --> TRANSACTIONCOMPLETE : Payment Complete
  PENDINGTRANSACTION --> CANCELLED : Cancel
  PENDINGTRANSACTION --> FAILEDTRANSACTION : Payment Failed

  TRANSACTIONCOMPLETE --> CONFIRMATIONREQUIRED : Request Confirmation

  CONFIRMATIONREQUIRED --> READY : Confirm Ready<br/>(SOF + Phone + Address)

  READY --> CARDCREATED : Create Card<br/>(Physical/Virtual)

  CARDCREATED --> [*] : Order Complete
  CANCELLED --> [*] : Order Cancelled
  FAILEDTRANSACTION --> [*] : Order Failed

  note right of PENDINGTRANSACTION
      Initial state when<br/>order is created
  end note

  note right of READY
      Ready for card creation<br/>All requirements met
  end note

  note right of CARDCREATED
      Card successfully created<br/>Order fulfilled
  end note
```

### Card Order States

#### Core States

**`PENDINGTRANSACTION`** - *Initial State*

* **Description**: Order created, awaiting payment or confirmation
* **Next States**: `READY`, `TRANSACTIONCOMPLETE`, `CANCELLED`, `FAILEDTRANSACTION`
* **User Actions**: Attach transaction, confirm payment, cancel order

**`TRANSACTIONCOMPLETE`** - *Payment Processed*

* **Description**: Payment transaction completed but requires additional verification
* **Next States**: `CONFIRMATIONREQUIRED`
* **System Actions**: Automatic transition when additional verification needed

**`CONFIRMATIONREQUIRED`** - *Verification Needed*

* **Description**: Additional user verification required (SOF, phone, address)
* **Next States**: `READY`
* **Requirements**: Phone verified, SOF completed, address provided

**`READY`** - *Ready for Card Creation*

* **Description**: All requirements met, ready to create physical/virtual card
* **Next States**: `CARDCREATED`
* **User Actions**: Create card with PIN (physical) or without PIN (virtual)

#### Terminal States

**`CARDCREATED`** - *Success*

* **Description**: Card successfully created and ready for use
* **Next States**: None (terminal state)
* **Note**: Virtual cards are immediately active; physical cards need activation

**`CANCELLED`** - *Cancelled*

* **Description**: Order cancelled by user or system
* **Next States**: None (terminal state)
* **Note**: Only possible from `PENDINGTRANSACTION` state

**`FAILEDTRANSACTION`** - *Payment Failed*

* **Description**: Payment processing failed
* **Next States**: None (terminal state)
* **Note**: User needs to create a new order

### Transition Rules

<Steps>
  <Step title="Pay Transition">
    `PENDINGTRANSACTION` → `READY`:

    * Free card: `totalAmountEUR === totalDiscountEUR`
    * Paid card: Valid EURe payment to correct address
    * Transaction hash validation (if required)
  </Step>

  <Step title="Request Confirmation">
    `TRANSACTIONCOMPLETE` → `CONFIRMATIONREQUIRED`:

    * Triggered when additional user verification is needed
    * System determines extra checks required
  </Step>

  <Step title="Confirm Ready">
    `CONFIRMATIONREQUIRED` → `READY`:

    * User phone verified
    * Source of Funds (SOF) completed
    * Valid shipping address (for physical cards)
  </Step>

  <Step title="Create Card">
    `READY` → `CARDCREATED`:

    * KYC approved
    * Risk score: Green or Orange
    * For physical cards: Encrypted PIN required
    * For virtual cards: No PIN needed
  </Step>

  <Step title="Cancel">
    `PENDINGTRANSACTION` → `CANCELLED`:

    * Only from `PENDINGTRANSACTION` state
    * User-initiated or admin-initiated
  </Step>
</Steps>

### Error Handling

When implementing card order, consider these scenarios:

**Invalid Transitions**
Will throw TransitionError

* Trying to cancel from READY state
* Attempting to create card from `PENDINGTRANSACTION`
* Any transition not defined in the state machine

**Common Error Scenarios**

* **Payment Issues**: Transaction hash already used, insufficient payment
* **User Requirements**: Missing KYC, unverified phone, missing address
* **System Issues**: Payment processor errors, card creation failures

### Implementation Example

```javascript theme={null}
// Check current order state before taking action
const handleOrderAction = async (order, action) => {
  switch (order.status) {
    case 'PENDINGTRANSACTION':
      if (action === 'pay') {
        await confirmPayment(order.id);
      } else if (action === 'cancel') {
        await cancelOrder(order.id);
      }
      break;

    case 'READY':
      if (action === 'createCard') {
        await createCard(order.id, { setPin: !order.virtual });
      }
      break;

    case 'CARDCREATED':
      // Order complete - handle card activation if needed
      break;

    default:
      throw new Error(`Cannot perform ${action} on order with status ${order.status}`);
  }
};
```

### Cancellable States

Orders can only be cancelled from specific states. Use the `CANCELLABLE_ORDER_STATUSES` constant:

```javascript theme={null}
const CANCELLABLE_ORDER_STATUSES = [
  'PENDINGTRANSACTION',
  'TRANSACTIONCOMPLETE',
  'CONFIRMATIONREQUIRED',
  'FAILEDTRANSACTION'
];
```

<Warning>
  **State Validation**: Always validate the current order state before attempting transitions. Invalid transitions will throw a `TransitionError` and return HTTP 422 status code.
</Warning>


# Cards Concepts
Source: https://docs.gnosispay.com/cards/concepts

Core concepts for card management, PINs, and merchant categories

Cards are their own domain, with lots of edge cases all around and a unique set of terms.
On this document, we aim to present the most common concepts related to operating cards
and what to expect of them.

This is not an extensive guide and we encourage you to use this document as a way to start
your journey. Both VISA and Mastercard have great resources and guides that you can also use.

<Note>
  For transaction-related concepts like payments, refunds, and reversals, see our dedicated
  [Card Transactions](/transactions) guide.
</Note>

## Card Lifecycle

Cards go through several states during their lifetime:

### Card States

* **Inactive**: Card created but not yet activated
* **Active**: Card activated and ready for use
* **Frozen**: Temporarily disabled (can be unfrozen)
* **Lost**: Reported as lost (requires replacement)
* **Stolen**: Reported as stolen (requires replacement)
* **Expired**: Past expiration date (requires replacement)

### Card Activation

New cards must be activated before first use. Activation typically involves:

* Verifying cardholder identity
* Setting initial PIN (if required)
* Confirming card receipt
* Enabling spending limits

### Card Management Operations

* **Freeze/Unfreeze**: Temporarily disable card usage
* **Report Lost/Stolen**: Permanently disable and request replacement
* **Update Limits**: Modify spending or withdrawal limits
* **PIN Management**: Change or reset PIN

## Disputes

Disputes are used to recover funds for captured transactions. Their main use-case is to revert fraudulent transactions
or problems with the product or service paid for. Fraud and non-fraud disputes have different requirements and rules,
and undergo through different analysis to reach a conclusion.

### Dispute Types

* **Fraud disputes**: Unauthorized transactions
* **Non-fraud disputes**: Issues with goods/services received
* **Processing errors**: Technical or merchant errors

### Dispute Process

1. **Initiation**: Cardholder reports disputed transaction
2. **Investigation**: Review transaction details and evidence
3. **Provisional Credit**: Temporary refund while investigating
4. **Resolution**: Final decision and permanent credit/debit

## Card PINs

Visa cards have 2 places to store the PIN - the first place is on the physical card chip, called the **offline PIN**, and the second is the **online PIN** that is stored in the bank's system. While these PINs usually have the same value, there can be cases where they differ, for instance when you change the card PIN.

When paying at a point of sale (in a restaurant or in a shop), only the offline PIN may be verified, while ATMs usually connect to the bank network and check the online PIN. When using the PSE to change the PIN, only the online PIN is changed. At this point, the offline PIN is **not updated** since physical access to the card is needed to change the PIN on the chip. To update the offline PIN, you need to go to an ATM and perform any operation. ATM transactions always go online to the card issuer. This allows the issuer to send an "issuer script" to your card, which updates the offline PIN stored on the chip, synchronizing it with any recent PIN changes made online (with PSE). Without this synchronization, your offline PIN might be outdated and cause issues for transactions that rely on offline verification.

## MCC: Merchant Category Code

Merchant Category Codes (MCCs) are used to classify businesses based on the types of goods or services they provide.
These codes are important as they are often used for calculating interchange fees, authorizing payments, and preventing fraud.
Additionally, specific MCCs are required for particular functionalities.


# Create Physical Cards
Source: https://docs.gnosispay.com/cards/create-physical-cards

Order physical cards for your Users.

## Create Physical Card Process

<Steps>
  <Step title="Create a Card Order">
    [This endpoint creates a new `CardOrder` with the status of `PENDINGTRANSACTION`](/api-reference/physical-card-order/create-physical-card-order):

    ```bash cURL theme={null}
    curl -X POST /api/v1/order/create
    ```

    The Card Order is created with the following data:

    * A shipping address can be specified by filling the `shippingAddress` field, see [endpoint specifications](/api-reference/physical-card-order/create-physical-card-order). If not set, the KYC address will be used for shipping.
    * The total amount to be paid is set in EURe. The amount is 30.23.
    * A coupon code can be applied to reduce the amount to be paid, either at signup or in the next step
  </Step>

  <Step title="(Optional) Attach a Coupon">
    [This endpoint attaches a coupon to the `CardOrder` with `orderId`](/api-reference/physical-card-order/attach-a-coupon-to-a-physical-card-order):

    ```bash cURL theme={null}
    curl -X POST /api/v1/order/{orderId}/attach-coupon
    ```

    The coupon needs to be valid, otherwise an error is thrown.
    If the user has a coupon code both from the signup, and from this step, the one from the signup takes precedence.
  </Step>

  <Step title="(Optional) Attach an on-chain transaction">
    <Note>
      This is only needed if the card is not free. If `CardOrder.totalAmountEUR` is the same as the `CardOrder.totalDiscountEUR` then the card is considered free.
    </Note>

    [This endpoint allows setting a transaction hash to the specified `orderId`](/api-reference/physical-card-order/register-payment-for-a-physical-card-order).

    ```bash cURL theme={null}
    curl -X PUT /api/v1/order/{orderId}/attach-transaction \
    -d '{
      "transactionHash": "0x..."
    }'
    ```

    The transaction can only be used once across all card orders.
  </Step>

  <Step title="Confirm the payment was performed">
    <Warning>
      This endpoint must be called even if the card is free. It moves the card order to the `READY` status.
    </Warning>

    [To confirm the payment call this endpoint](/api-reference/physical-card-order/confirm-the-payment-for-a-physical-card-order):

    ```bash cURL theme={null}
    curl -X PUT /api/v1/order/{orderId}/confirm-payment
    ```

    The conditions for the payment are:

    * In order to call this endpoint, the `CardOrder.status` needs to be `PENDINGTRANSACTION`.
    * If the card is not free, we check if a payment was done.
      * Token used for payment needs to be EURe `0xcB444e90D8198415266c6a2724b7900fb12FC56E`.
      * Payment was done to `0x3D4FD6a1A7a1382ae1d62C3DD7247254a0236847`.
      * The respective EURe amount was paid in that transaction hash (partial transfers are not supported).

    If all the conditions above are met, the `CardOrder.status` is set to `READY`.
  </Step>

  <Step title="Create the Physical Card">
    [Finally, you can create the Physical Card](/api-reference/physical-card-order/create-a-physical-card):

    ```bash cURL theme={null}
    curl -X POST /api/v1/order/:orderId/create-card
    ```

    When successful, this endpoint returns the `cardToken` from the newly created card.

    In order to create a `Card` out of a `CardOrder` the following conditions need to be met:

    * No cards were created out of this `orderId`.
    * User needs to have a verified phone number.
    * User needs to have a name set.
    * User needs to be from a supported country.
    * User address needs to be set.
    * User needs to have an approved KYC.
    * The risk score needs to be Green or Orange based on the user's answers to the Source of funds questionnaire.
    * User needs to have the shipping details for the physical card order set.
      * The shipping details can be different from the KYC address, as long as it is in the same country.
      * Virtual cards do not require a shipping address.
    * The embossed name for the card needs to be set.
  </Step>

  <Step title="Set the Card PIN using the Partner Secure Elements (PSE)">
    The card PIN should be set immediately after the card is created via the Partner Secure Elements (PSE).
    Use the `cardToken` returned from the previous endpoint to set the PIN.
    If a PIN is not provided upon creation, a random one will be assigned.
    Changing this randomly assigned PIN requires the user to visit an ATM. Refer to the **[card PINs section](/cards#card-pins)** to learn more about the online and offline PINs.

    For detailed instructions about how to change the PIN, please refer to the [PSE SDK documentation](/cards/pse-integration).
  </Step>
</Steps>


# Create Virtual Cards
Source: https://docs.gnosispay.com/cards/create-virtual-cards

Virtual cards work either online or tap in presence (with Apple Pay and Google Pay).

Virtual card orders have a **simplified flow** compared to physical cards, with these key differences:

* No shipping address is required
* The card is available immediately after order creation (no shipping delay)
* Virtual cards can be used for online transactions immediately
* Thanks to Google and Apple Pay (some regions are not yet available), the card can be used for in-person transactions immediately.
* No PIN is required; the user's phone number is used as second factor authentication for some online payments
* **Cards are automatically created and activated when the order is placed**

## How to create a Virtual Card

[This endpoint allows you to issue a virtual card directly](/api-reference/card-management/create-a-virtual-card):

```bash cURL theme={null}
curl -X POST /api/v1/cards/virtual
```

Virtual cards are free and activated immediately. No shipping address or payment validation required.

<Warning>
  **Automatic Card Creation**: By calling this endpoint, the virtual card is automatically created if the user's Safe account is properly configured. You do not need to call any other endpoint.
</Warning>

[The virtual card should appear immediately in the card list available with the endpoint](/api-reference/card-management/list-all-cards):

```bash cURL theme={null}
curl /api/v1/cards?status_code=1000
```

The `status_code=1000` query parameter returns only active cards.

<Note>
  Card Limits: Users can have a **maximum of 5 active cards including physical and virtual cards combined**. Active cards exclude voided, lost, and stolen cards.
</Note>


# Partner Secure Elements (PSE) Integration
Source: https://docs.gnosispay.com/cards/pse-integration

Access sensitive Card information from your client application.

## Overview

If you want to display sensitive information, such as card numbers, in your front-end, you'll need to interact with our **Partner Secure Elements (PSE)** service. The easiest way to do this is by using the [PSE SDK](https://www.npmjs.com/package/@gnosispay/pse-sdk) from Gnosis Pay.

To initialize the SDK, you'll need an `App ID` provided to you upon registration with Gnosis Pay. You'll also need an **ephemeral-token**. This ephemeral-token can be retrieved with a call to our private PSE API using mTLS authentication.

<Warning>
  **Backend Only**: An mTLS authentication can only be performed from a
  back-end. For this reason, you need a back-end responsible for retrieving the
  ephemeral-token and sending it to your front-end upon request. We'll go
  through each step in this guide.
</Warning>

Once your front-end has the ephemeral-token, it can initialize the PSE SDK and use it to display secure elements.

Here's a diagram showing each step:

```mermaid theme={null}
    sequenceDiagram
        participant FE as Your Frontend
        participant BE as Your Backend
        participant API as PSE API

        FE->>BE: Get ephemeral-token
        BE->>API: Get ephemeral-token (mTLS Certificates)
        API-->>BE: Receive ephemeral-token
        BE-->>FE: Receive ephemeral-token

        Note over FE: Initialize PSE SDK with ephemeral-token and App ID

        FE->>API: PSE SDK Requests Card Information
        API-->>FE: Display Card Information Inside an Iframe
```

Reference implementations are available for a [front-end](https://github.com/gnosispay/ui) and a [back-end](https://github.com/gnosispay/ui/tree/main/pse-backend-demo).

***

## Secure Connection Using mTLS Authentication

**Mutual TLS (mTLS)** is a type of authentication in which two parties in a connection authenticate each other using the TLS protocol. Your back-end will establish an mTLS authentication with the Gnosis Pay private PSE API to receive an ephemeral-token.

### How to Generate mTLS Certificates

After signing up through the [Partners Dashboard](https://partners.gnosispay.com/), you will receive an `App ID` instantly, which will be used in the certificate generation below. You must first create a private key and then generate a Certificate Signing Request (CSR) using the `App ID` as follows:

```graphql theme={null}
# APP_ID is a string starting with `gp_` that you have received from Gnosis Pay
export APP_ID="gp_woop_123"

# Create a private key (NEVER share with anyone)
openssl ecparam -name prime256v1 -genkey -noout -out "${APP_ID}.key.pem"

# Create the CSR (OK to share)
openssl req -new -sha256 -key "${APP_ID}.key.pem" -out "${APP_ID}.csr.pem" -subj "/CN=${APP_ID}"
```

You can now share the `${APP_ID}.csr.pem` file with the Gnosis Pay team. **DO NOT EVER** share the `.key.pem` file with **ANYONE**.

Once we receive your Certificate Signing Request, we will sign it and send you back the signed certificates. These signed certificates, along with your private key, are used to establish the connection with the PSE API.

### How to Establish an mTLS Authentication (in Node.js)

You should securely store the certificates in your environment along with your private key.

Your environment should expose the certificates and private key, for example:

```rust theme={null}
SIGNED_CERTIFICATES="-----BEGIN CERTIFICATE-----
ABCQz ....
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
DEFC7 ....
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
GHICc ....
-----END CERTIFICATE-----"

PRIVATE_KEY="-----BEGIN EC PRIVATE KEY-----
ABCD....
-----END EC PRIVATE KEY-----"
```

Here's a Node.js implementation to request the ephemeral-token in two different ways:

<CodeGroup>
  ```js Using Axios theme={null}
  const httpsAgent = new https.Agent({
    cert: process.env.SIGNED_CERTIFICATES,
    key: process.env.PRIVATE_KEY,
    rejectUnauthorized: true, // Ensure SSL verification
  });

  const ephemeralTokenRequest = await axios({
    httpsAgent: httpsAgent,
    method: "POST",
    url: `https://api-pse.gnosispay.com/api/v1/ephemeral-token`,
    headers: { "Content-Type": "application/json" },
    // Axios adds the user-agent automatically
  });
  ```

  ```js Using https.request theme={null}
  import https from "https";

  const httpsAgent = new https.Agent({
    cert: CERT,
    key: KEY,
    rejectUnauthorized: true,
  });

  const req = https.request(
    {
      hostname: "api-pse.gnosispay.com",
      path: "/api/v1/ephemeral-token",
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "User-Agent": "User-Client/1.0.0",
      },
      agent: httpsAgent,
    },
    (res) => {
      let data = "";
      res.on("data", (chunk) => {
        data += chunk;
      });

      res.on("end", () => {
        console.log("Status:", res.statusCode);

        try {
          const parsedData = JSON.parse(data);
          console.log("Response:", parsedData);
        } catch {
          console.log("Raw response:", data);
        }
      });
    }
  );

  req.on("error", (error) => {
    console.error("Request error:", error);
  });
  req.end();
  ```
</CodeGroup>

Please refer to our [API documentation](/api-reference/endpoints/generate-a-new-ephemeral-token) on the PSE service for more information about the specific endpoint.

<Note>
  The ephemeral-token, as its name suggests, is valid for a very short time
  frame. It is advised to generate a new one for every usage of the SDK.
</Note>

***

## How to Use the PSE SDK

The PSE SDK will help you display sensitive information. It injects secure iframes into your front-end and exposes callbacks to interact with it. Refer to the [PSE SDK documentation](https://www.npmjs.com/package/@gnosispay/pse-sdk) for instructions and examples.

## How to Customize the Style of Secure Elements in the iframe

For security reasons, the only way to apply custom styling to iframe elements is to prepare and share a **CSS file** with the Gnosis Pay team. This file, named `<partner_name>.css`, will be incorporated into the iframe.

Standard styling is applied to the iframe elements by default. You can override the style of these classes and IDs as needed. Here are some of them:

#### Card Data

* `.pse-container` - A shared class for all iframe containers.
* `#pse-card-data-container` - The main container for displaying card data.
* `.pse-card-field` - The container for each card data field (card number, expiry date, security code).
* `.pse-card-label` - Labels for each field.
* `.pse-card-value` - The container for the actual card data values.

#### Set PIN Form

* `.pse-container` - A shared class for all iframe containers.
* `#pse-set-pin-form` - The main form container.
* `#pse-set-pin-success-container` - The success state container.
* `.pse-set-pin-container` - The base container class.
* `.pse-set-pin-button` - The base class for all buttons.
* `#pse-continue-pin-button` - The continue button.
* `#pse-done-button` - The done button.

***

### Styling Guide

Here is a suggested workflow to customize the styling:

1. In your front-end, load the element you wish to customize (e.g., the card data).
2. Locate the custom CSS file with your name in either the "**Style Editor**" in Firefox or the "**Sources**" panel on Chrome/Brave. In the example below, the file is `gnosis_pay_ui.css`.
3. Apply your desired styling. The changes will be reflected in your interface immediately.
4. Save the file and send it to Gnosis Pay for application in production.

Here is an example of overriding the `.pse-card-field` class in Firefox:

<img alt="custom css" />

## React Native Integration

If you'd like to integrate the PSE SDK into a React Native application, you can use the [React Native PSE SDK](https://www.npmjs.com/package/@gnosispay/pse-react-native) package to help integrating the WebView piece.

However, as the PSE requires hosting on your domain, you will still need to host the PSE Frame on your backend, on your domain.

This frame can be as simple as an HTML page that invokes the PSE JS SDK.

In our reference implementation repository, next to the examples of implementing backend endpoint for ephemeral token generation, you can
find [an example of such page](https://github.com/gnosispay/ui/blob/main/pse-backend-demo/src/static/native-webview.html) returned by the same backend that generates the ephemeral token.

Note that this page should be responsible for fetching the ephemeral token from your backend, and passing it to the PSE JS SDK.

You will then pass this URL to the React Native WebView component, through the `webViewUrl` prop, together with other parameters that you can find in the [React Native PSE SDK documentation](https://www.npmjs.com/package/@gnosispay/pse-react-native).


# About GP Safe
Source: https://docs.gnosispay.com/gp-onchain/about-GP-safe

Gnosis Pay's on-chain infrastructure is built on top of the [Safe protocol](https://safe.global), providing a secure and programmable foundation for digital payments. Each user gets a unique Safe account that acts as their on-chain wallet, with additional modules that enable spending limits, time delays, and delegated spending capabilities.

The Gnosis Pay Safe consists of a core Safe account with three main modules attached:

1. **Core Safe Account**: The base Safe that holds funds and manages ownership
2. **Delay Module**: Controls transaction timing and provides security delays
3. **Roles Module**: Manages spending permissions and allowance limits
4. **Bouncer Module**: Handles account access validation and security

### Gnosis Pay Safe Setup Process

To understand how a Gnosis Pay Safe differs from a standard Safe, let's examine the [account setup flow](https://github.com/gnosispay/account-kit/blob/main/src/entrypoints/accounts-actions/accountSetup.ts#L88) that transforms a basic 1/1 Safe into a fully configured Gnosis Pay Safe Account:

<Steps>
  <Step title="Safe Configuration">
    * **Ownership Transfer**: Swaps the Safe owner to an inaccessible address (`0x0000000000000000000000000000000000000002`)
    * **Module Enablement**: Enables both the Roles and Delay modules on the Safe
  </Step>

  <Step title="Delay Module Setup">
    * **Deployment**: Creates a new Delay module instance for the account
    * **Cooldown Configuration**: Sets the transaction delay period (typically 3 minutes)
    * **Expiration Setting**: Configures how long queued transactions remain valid
    * **Owner Access**: Grants the initial Safe owner (the owner before the ownership transfer) access to the delay module
  </Step>

  <Step title="Roles Module Setup">
    * **Deployment**: Creates a new Roles module instance for the account
    * **Allowance Configuration**: Sets up spending limits with:
      * Initial balance amount
      * Maximum balance cap
      * Refill amount per period
      * Time period for refills
    * **Role Assignment**: Grants spending permissions to designated spender addresses
    * **Target Scoping**: Restricts spending to specific token contracts
    * **Function Scoping**: Limits operations to ERC20 transfer functions only
    * **Ownership Transfer**: Transfers control to the Bouncer module
  </Step>

  <Step title="Bouncer Module">
    * **Deployment**: Creates the final security layer
    * **Access Control**: Manages who can interact with the account
  </Step>
</Steps>

### Spending Control Flow

The spending process follows this pattern:

1. **Spender Request**: A designated spender requests a transaction
2. **Allowance Check**: The Roles module verifies spending limits
3. **Delay Enforcement**: If limits allow, the transaction enters the delay queue
4. **Time Delay**: The transaction waits for the configured cooldown period
5. **Execution**: After the delay, the transaction can be executed
6. **Balance Update**: The allowance balance is updated accordingly


# Change GP Safe daily spending limit
Source: https://docs.gnosispay.com/gp-onchain/daily-limit

Manage daily spending limits for Gnosis Pay Safe accounts

The daily spending limit feature allows partners to manage daily spending limits for Gnosis Pay Safe accounts.

All transactions are gasless, enabling users to perform these operations completely free of charge.

## Overview

The daily spending limit update process involves the following steps:

1. **Fetch EIP-712 Typed Data** - Get the EIP-712 typed data for wallet signing
2. **Sign and Submit** - Sign the EIP-712 data and submit the update
3. **Monitor Update** - Wait for the delay relay to process the change and check the new limit

<Warning>
  * The signing wallet must be one of the Gnosis Pay Safe signers (EOA or smart contract wallet)
  * For smart contract wallets, signatures are verified using ERC-1271 standard
  * Updates are processed after a 3-minute delay as transactions are going through the Gnosis Pay delay relay
</Warning>

## Daily Limit Update Process

<Steps>
  <Step title="Fetch EIP-712 Typed Data for Signing">
    [Get the EIP-712 typed data that needs to be signed by the user's wallet](/api-reference/account-management/get-eip-712-typed-data-for-setting-daily-limit):

    ```bash cURL theme={null}
    curl -X GET \
     /api/v1/accounts/daily-limit/transaction-data?newLimit=${newLimit}
    ```

    The response contains EIP-712 typed data with `domain`, `types`, `primaryType`, and `message` fields that need to be signed by the user's wallet using the EIP-712 standard.
  </Step>

  <Step title="Sign and Submit EIP-712 Data">
    <Warning>
      **Safe Activation Required**: This step only works when the Gnosis Pay Safe account has been fully activated and its modules are deployed. If you receive an error during submission, ensure that the Safe account activation process has been completed first.

      For more information about Safe account setup and module deployment, see the [Safe Management API documentation](/api-reference/safe-management/deploy-and-setup-a-safe).
    </Warning>

    The EIP-712 typed data from Step 1 must be signed by the user's wallet using the EIP-712 signature standard.

    <Note>
      **Wallet Requirements:**

      * The wallet must be a signer of the Gnosis Pay Safe account
      * For **EOA wallets**: Standard EIP-712 signature is used
      * For **smart contract wallets**: ERC-1271 signature verification is used, and you must include the `smartWalletAddress` field in the request body
    </Note>

    Once signed, [submit the transaction to update the daily limit](/api-reference/account-management/set-new-daily-spending-limit):

    ```bash cURL theme={null}
    # For EOA wallets
    curl -X PUT /api/v1/accounts/daily-limit \
     -d '{
      "newLimit": 1500,
      "signature": "0x...",
      "message": {
        "salt": "0x...",
        "data": "0x..."
      }
    }'

    # For smart contract wallets (include smartWalletAddress)
    curl -X PUT /api/v1/accounts/daily-limit \
     -d '{
      "newLimit": 1500,
      "signature": "0x...",
      "message": {
        "salt": "0x...",
        "data": "0x..."
      },
      "smartWalletAddress": "0x..."
    }'
    ```
  </Step>

  <Step title="Monitor the Transaction Execution">
    The daily limit change is processed through a delay relay mechanism that executes after 3 minutes.

    You can monitor the transaction status using the [delay-relay monitoring endpoint](/api-reference/safe-management/list-delayed-transactions)
    or by checking your Safe's transaction history.

    Additionally, you can also [poll the following endpoint to check when the new limit becomes active](/api-reference/account-management/get-current-daily-spending-limit):

    ```bash cURL theme={null}
    curl -X GET /api/v1/accounts/daily-limit
    ```
  </Step>
</Steps>

## Complete Implementation Example

The following example demonstrates the complete flow:

```typescript theme={null}

const newDailyLimit = 1337;

/**
 * Step 1: Fetch EIP-712 typed data for signing
 */
const response = await fetch(
  `https://api.gnosispay.com/api/v1/accounts/daily-limit/transaction-data?newLimit=${newDailyLimit}`
);
const { data: typedData } = await response.json();

/**
 * Step 2: Sign the EIP-712 typed data
 */
const signature = await walletClient.signTypedData({
  ...typedData,
  domain: {
    ...typedData.domain,
    verifyingContract: typedData.domain.verifyingContract as `0x${string}`,
  },
});

/**
 * Step 3: Submit the signed data
 */
const submitResponse = await fetch("https://api.gnosispay.com/api/v1/accounts/daily-limit", {
  method: "PUT",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    newLimit: newDailyLimit,
    signature,
    message: typedData.message,
    // Include smartWalletAddress if using a smart contract wallet
    // smartWalletAddress: "0x...",
  }),
});

const { data: updateResult } = await submitResponse.json();

/**
 * Step 4: Monitor for the updated limit
 */
console.log(`Daily limit update submitted with ID: ${updateResult.id}`);
console.log(`Status: ${updateResult.status}`);
console.log("Limit change will be processed after the 3-minute delay period");

// Optional: Poll for the updated limit
const pollForUpdate = async () => {
  const checkResponse = await fetch(
    "https://api.gnosispay.com/api/v1/accounts/daily-limit"
  );
  const { data: { dailyLimit: updatedLimit } } = await checkResponse.json();

  if (updatedLimit === newDailyLimit) {
    console.log(`Limit successfully updated to: ${updatedLimit}`);
    return true;
  }

  console.log(`Waiting for update... Current: ${updatedLimit}, Target: ${newDailyLimit}`);
  return false;
};

// Poll every 30 seconds until the update is complete
const interval = setInterval(async () => {
  if (await pollForUpdate()) {
    clearInterval(interval);
  }
}, 30000);
```


# Overview
Source: https://docs.gnosispay.com/gp-onchain/overview

Understanding the on-chain integration options for Gnosis Pay, including the Account Kit SDK and direct contract integration approaches.

## Account Kit

We provide the Account Kit as a way to accelerate on-chain integration for the TypeScript/JavaScript ecosystem. This SDK abstracts away the complexity of our multi-module Safe architecture, making it easier for developers to integrate with Gnosis Pay's on-chain infrastructure directly.

Installing instructions and comprehensive examples are available in the [Account Kit repository](https://github.com/gnosispay/account-kit). The SDK is open source and actively maintained by the Gnosis Pay team.

All examples in this section of the documentation assume you are using the Account Kit SDK.

## Direct Integration without Account Kit

For other programming languages, you can use their own cryptocurrency libraries (e.g., go-ethereum for Go, web3.py for Python, and so on) and integrate directly with the contracts. However, this approach requires additional steps since the Account Kit relies on TypeScript/JavaScript projects from Gnosis such as `@gnosis.pm/safe-contracts`, `@gnosis.pm/zodiac`, and related dependencies.

Integrating directly means you'll need to explore the Account Kit source code and its dependencies to understand:

* **Contract Function Calls**: Which specific functions are being called on the Safe, Delay, Roles, and Bouncer modules
* **Payload Encoding**: How transaction data is encoded and structured for each operation
* **Module Interactions**: The sequence and coordination between different modules
* **Parameter Validation**: What parameters are required and how they're validated

This reverse-engineering approach is entirely doable for teams with strong smart contract integration experience, but it requires significant additional development time compared to using the Account Kit directly.


# Sign Messages with GP Safe
Source: https://docs.gnosispay.com/gp-onchain/sign-message

Learn how to sign messages using your GP Safe account with the delay module for enhanced security.

Unlike traditional EOA (Externally Owned Account) message signing, GP Safe message signing goes through the delay module.

<Note>
  Message signing with GP Safe requires the account to be fully configured with the delay module enabled. If you haven't set up your Safe account yet, see the [Safe Account Configuration](/onboarding-flow#4-safe-account-configuration) section first.
</Note>

## Message Signing Process

GP Safe message signing follows the same two-phase pattern as other delayed operations:

1. **Enqueue Phase**: Submit the message signing request to the delay queue
2. **Dispatch Phase**: Execute the message signing after the delay period expires

[You can find a complete working example here.](https://github.com/gnosispay/account-kit/blob/main/examples/src/sign-safe-message/index.ts)

<Steps>
  <Step title="Prepare the Message">
    First, prepare the message you want to sign.

    This can be any string, such as:

    ```typescript theme={null}
    const message = "Hello, this is a message to be signed by my GP Safe!";
    ```

    Or structured data that needs to be signed by your GP Safe account.
  </Step>

  <Step title="Enqueue the Message Signing Request">
    Use the `populateSignMessageEnqueue` function to create a transaction that submits your message signing request to the delay queue.

    ```typescript theme={null}
    import { populateSignMessageEnqueue } from "@gnosispay/account-kit";

    const owner: Signer = {}; // Your wallet signer
    const account = "0x..."; // Your GP Safe address
    const chainId = 100; // Gnosis Chain

    const enqueueTx = await populateSignMessageEnqueue(
      { account, chainId },
      message,
      // EIP-712 signature callback
      ({ domain, primaryType, types, message }) =>
        owner.signTypedData(domain, primaryType, types, message)
    );

    // Send the enqueueTx using your wallet
    ```

    <Warning>
      This transaction will be queued in the delay module and cannot be executed immediately. The delay period (typically 3 minutes) must pass before the message can be signed.
    </Warning>
  </Step>

  <Step title="Wait for the Delay Period">
    The message signing request is now in the delay queue. You must wait for the configured cooldown period to expire before proceeding.

    <Info>
      The default delay period is 3 minutes (180 seconds). This provides time for you to review and potentially cancel the operation if needed.
    </Info>

    You can check the delay queue status using the `accountQuery` function from `@gnosispay/account-kit`.
  </Step>

  <Step title="Dispatch the Message Signing">
    Once the delay period has expired, use the `populateSignMessageDispatch` function to execute the queued message signing operation.

    ```typescript theme={null}
    import { populateSignMessageDispatch } from "@gnosispay/account-kit";

    const dispatchTx = populateSignMessageDispatch(
      { account },
      message
    );

    // Send the dispatchTx using your wallet
    ```

    <Note>
      Unlike the enqueue transaction, the dispatch transaction doesn't require a signature since it's executing a previously authorized operation.
    </Note>
  </Step>
</Steps>


# Third-Party Bridges
Source: https://docs.gnosispay.com/gp-onchain/third-party-bridges



Gnosis Pay partners can select and integrate bridge aggregators based on their specific infrastructure requirements and target chain support. The following recommended solutions ensure optimal cross-chain functionality for end users.

### Recommended Bridge Aggregators

<CardGroup>
  <Card title="NEAR Intents" icon="link" href="https://docs.near-intents.org">
    Intent-based bridging with deep liquidity for Gnosis Chain, supporting EURe and GBPe. Converts Bitcoin and non-EVM assets to Gnosis Chain in a single transaction.
  </Card>

  <Card title="Bungee Exchange" icon="bridge" href="https://docs.bungee.exchange/bungee-api/">
    Cross-chain bridge aggregator offering best-price, auto-routed swaps across multiple blockchains.
  </Card>

  <Card title="LiFi Protocol" icon="bridge" href="https://docs.li.fi/introduction/introduction">
    Cross-chain liquidity aggregation protocol enabling seamless token transfers across multiple chains and bridges.
  </Card>

  <Card title="CoW Swap" icon="cow" href="https://docs.cow.fi/">
    Native Gnosis Chain protocol offering MEV-protected, gasless bridging from Ethereum.
  </Card>

  <Card title="deBridge" icon="rainbow" href="https://docs.debridge.com/">
    Handles complex cross-chain routes like Solana USDC → Gnosis with custom message passing.
  </Card>
</CardGroup>


# Withdraw funds from GP Safe
Source: https://docs.gnosispay.com/gp-onchain/withdraw-funds-from-safe

How to send funds from the Gnosis Pay Safe to your EOA or somewhere else.

The withdrawal feature allows partners to withdraw tokens from Gnosis Pay Safe accounts to any external address **on the Gnosis Chain**.
All transactions are gasless, enabling users to perform these operations completely free of charge.

The withdrawal process involves the following steps:

1. **Fetch Transaction Data** - Get the EIP-712 typed data for signing
2. **Sign and Submit** - Sign the transaction and submit the withdrawal
3. **Monitor Execution** - Wait for the delay relay to process the withdrawal

<Warning>
  Please remember the following:

  * The signing wallet must be one of the Gnosis Pay Safe signers (EOA or smart contract wallet)
  * For smart contract wallets, signatures are verified using ERC-1271 standard
  * Withdrawals are processed after a 3-minute delay as transactions are going through the Gnosis Pay delay relay
  * Cards are temporarily frozen for 3 minutes during withdrawal processing as a security measure
</Warning>

## Withdrawal Process

<Steps>
  <Step title="Fetch Transaction Data for Signing">
    Get the EIP-712 typed data that needs to be signed by the user's wallet [(spec)](/api-reference/account-management/retrieve-transaction-data-for-withdrawing-from-safe):

    ```bash cURL theme={null}
    curl -X GET \
    /api/v1/accounts/withdraw/transaction-data?tokenAddress=${tokenAddress}&to=${toAddress}&amount=${amount}
    ```

    The response contains EIP-712 typed data that needs to be signed by the user's wallet.
  </Step>

  <Step title="Sign the EIP-712 Typed Data">
    The EIP-712 typed data from Step 1 must be signed by the user's wallet using the EIP-712 signature standard.

    <Note>
      **Wallet Requirements:**

      * The wallet must be a signer of the Gnosis Pay Safe account
      * For **EOA wallets**: Standard EIP-712 signature is used
      * For **smart contract wallets**: ERC-1271 signature verification is used, and you must include the `smartWalletAddress` field in the request body
    </Note>
  </Step>

  <Step title="Submit Transaction">
    Once signed, [submit the transaction to execute the withdrawal](/api-reference/account-management/withdraw-from-safe-with-signature):

    ```bash cURL theme={null}
    # For EOA wallets
    curl -X POST \
    /api/v1/accounts/withdraw \
    -H "Content-Type: application/json" \
    -d '{
      "tokenAddress": "0x123456....",
      "to": "0x78910...",
      "amount": "1000000000000000000",
      "signature": "0x1234567890abcdef...",
      "message": {
        "salt": "0x1234567890...abcdef",
        "data": "0x123456...00de0b6b3a7640000"
      }
    }'

    # For smart contract wallets (include smartWalletAddress)
    curl -X POST \
    /api/v1/accounts/withdraw \
    -H "Content-Type: application/json" \
    -d '{
      "tokenAddress": "0x123456....",
      "to": "0x78910...",
      "amount": "1000000000000000000",
      "signature": "0x1234567890abcdef...",
      "message": {
        "salt": "0x1234567890...abcdef",
        "data": "0x123456...00de0b6b3a7640000"
      },
      "smartWalletAddress": "0x..."
    }'
    ```
  </Step>

  <Step title="Monitor the Execution">
    The withdrawal is processed through a **delay relay mechanism** that executes after 3 minutes.

    You can monitor the transaction status using the [delay-relay monitoring endpoints](/api-reference/safe-management/list-delayed-transactions) or by checking your Safe's transaction history.
  </Step>
</Steps>

## Complete Implementation Example

The following example demonstrates the complete flow:

```typescript theme={null}
const tokenAddress = "0x..."; // Token contract address
const toAddress = "0x..."; // Destination address
const amount = "1000000000000000000"; // Amount in token base units

/**
 * Step 1: Fetch transaction data for signing
 */
const response = await fetch(
  `https://api.gnosispay.com/api/v1/accounts/withdraw/transaction-data?tokenAddress=${tokenAddress}&to=${toAddress}&amount=${amount}`
);
const { data: typedData } = await response.json();

/**
 * Step 2: Sign and submit the transaction
 */
const signature = await walletClient.signTypedData({
  ...typedData,
  domain: {
    ...typedData.domain,
    verifyingContract: typedData.domain.verifyingContract as `0x${string}`,
  },
});

const submitResponse = await fetch("https://api.gnosispay.com/api/v1/accounts/withdraw", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    tokenAddress,
    to: toAddress,
    amount,
    signature,
    message: typedData.message,
    // Include smartWalletAddress if using a smart contract wallet
    // smartWalletAddress: "0x...",
  }),
});

const { data: transactionResult } = await submitResponse.json();

/**
 * Step 3: Monitor execution (optional)
 */
console.log(`Withdrawal submitted with ID: ${transactionResult.id}`);
console.log(`Status: ${transactionResult.status}`);
console.log("Transaction will be processed after the 3-minute delay period");
```

## Security Considerations

* Make sure the user is aware this transfer is on the Gnosis Chain
* Remember that transactions cannot be reversed once executed
* Cards are temporarily frozen during the withdrawal process as a security measure

## Token Support

This feature supports withdrawing any ERC-20 token that exists in the Safe account. Make sure to:

* Use the correct token contract address
* Specify the amount in the token's base units (considering decimals)
* Ensure sufficient token balance in the Safe account


# Introduction
Source: https://docs.gnosispay.com/index

Welcome to GnosisPay Documentation

This documentation is designed to help developers and businesses leverage our APIs
to enable seamless card issuance, management, and user experiences for their customers.

With Gnosis Pay, you can offer your users a simple way to interact with crypto payments in the real world while enjoying
the security of self-custodial wallets. By following the steps in this guide, you can ship stablecoin program for users and allow them to spend crypto.

<Card title="Get Started Today" icon="rocket" href="https://my.gnosispay.com/">
  Get a Gnosis Pay account today by signing in to the Gnosis Pay webapp and start spending crypto in the real world.
</Card>

## Gnosis Pay Functionality

Gnosis Pay's first product is Gnosis Card: a stablecoin based visa debit card,
enabling users to spend their digital assets in the traditional economy using the Gnosis Pay network.

<CardGroup>
  <Card title="⚡ Instant Spending" icon="bolt">
    Easily spend crypto like you spend cash.
  </Card>

  <Card title="🌍 Global Acceptance" icon="globe">
    Accepted at 80+ million Visa merchants worldwide.
  </Card>

  <Card title="🔐 Self-Custody" icon="shield-check" href="/gp-onchain/about-GP-safe">
    Take control of your money through your SAFE account. You own your keys, you own your crypto.
  </Card>

  <Card title="💰 DeFi Protocol Integration" icon="coins">
    Add savings and investment features by connecting to DeFi protocols through plug-and-play integrations.
  </Card>

  <Card title="💰 Up to 5% Cashback" icon="coins">
    Earn up to 5% cashback on eligible transactions based on the amount of GNO you hold in your wallet.
  </Card>

  <Card title="🏦 On/Off Ramp Integrations" icon="building-columns" href="/on-off-ramps/index">
    On and Off ramp integrations are available with our integrated ramp partners such as Noah, Monerium and Avenia.
  </Card>
</CardGroup>


# Integrating Gnosis Pay APIs
Source: https://docs.gnosispay.com/integration-model

Whether you’re building as a developer or looking to launch a whitelisted branded solution, Gnosis Pay is designed to be flexible and accessible for all developers and businesses.

## Partnership Integration

Partners can integrate APIs and provide users with branded cards, custom user experiences, fee rebates, or co-marketing opportunities — you can sign up through our [Partners Dashboard](https://partners.gnosispay.com/).

<Warning>
  **Domain Whitelisting Required**: During partner signup, you must provide all production and staging domains where your application will be hosted. These domains are whitelisted for SIWE (Sign-In with Ethereum) authentication and CORS.

  * **localhost**: Automatically allowed for local development (e.g., `localhost:3000`)
  * **Production/Staging**: All non-localhost domains must be registered during signup
  * Applications running on non-whitelisted domains will face authentication failures
</Warning>

<img alt="Partnership API Flow - Start building and testing with Gnosis Pay APIs" />

**Who it's for:** Any partner ready to move beyond experimentation and operate a live program.

<CardGroup>
  <Card title="Key Credentials" icon="key" href="/integration-model#getting-your-partnerid-and-app-id">
    * **Partner ID** → Required for webhooks, attribution, and tracking
    * **App ID** → Required for Partner Secure Element (PSE) access
  </Card>

  <Card title="Advanced Features" icon="star">
    * Branded cards and custom experiences
    * Multi-market support
    * BIN sponsorship
    * Compliance oversight
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Dedicated Support" icon="headset">
    Direct access to Gnosis Pay team for technical guidance and business support.
  </Card>

  <Card title="Full Observability" icon="chart-bar">
    Complete integration into your systems with webhooks and analytics.
  </Card>
</CardGroup>

## **Getting Your PartnerID and APP\_ID**

Through our self-service [Partners Dashboard](https://partners.gnosispay.com/), partners can:

* **PartnerID**: A unique identifier for partner organization within the Gnosis Pay ecosystem, enabling us to track user acquisition and attribute activity to integration.
* **APP\_ID**: An application-specific identifier that allows partners to authenticate with the PSE (Partner Secure Elements) and establish secure mTLS connection authentication between partner and Gnosis Pay.
  <img alt="Partners Dashboard - Self-service partner registration and management" />

<Info>
  To get your PartnerID and APP\_ID through the Partners Dashboard:

  1. Sign up at [partners.gnosispay.com](https://partners.gnosispay.com/)
  2. Include your company details and app domains (required for CORS whitelisting)
  3. Get your PartnerID and APP\_ID instantly upon registration
  4. Handle PSE integration setup, CSR signature, and webhook configuration directly through the dashboard

  **Critical**: You must include all your production and staging domains during signup. While localhost is automatically allowed for development, all other domains must be whitelisted for both CORS and SIWE authentication. Missing domains will cause authentication failures and API access issues.
</Info>


# IBAN Integration
Source: https://docs.gnosispay.com/on-off-ramps/iban-integration

IBAN cash-in to the Gnosis Pay Account via Monerium

We offer IBAN cash-in to the Gnosis Pay Account via Monerium for users in Europe (EU) and Switzerland.

Monerium's IBAN integration enables direct connection between the owner of the GP Safe (which is the authenticated account address for SIWE) and Monerium.

* By calling the integrations endpoint (see below), it shares the user's KYC with Monerium.

* You can use [Monerium API](https://monerium.dev/api-docs/v2) to authenticate with SIWE and perform actions enabled by the Monerium API

* This API operates independently of the GP Safe and does not involve signatures on the delay module.

## Check Availability

[First you need to check if the user is eligible to have an IBAN](/api-reference/iban/check-iban-availability):

```bash cURL theme={null}
curl -X GET /api/v1/ibans/available
```

If you receive a `"available": false`, the flow ends here.

<Warning>
  Requirements that the Gnosis Pay user must have:

  * Valid date of birth
  * An active EURe Safe Account
  * KYC verified and approved
  * Residency in a supported country
  * First and last name defined (or name)
  * Valid location fields filled in (address1, postalCode, city and country, none of these fields can be missing)
  * Nationality from a supported country ([see allowed and restricted nationalities](https://help.gnosispay.com/hc/en-us/articles/39558629298708-Eligible-Nationalities-for-the-Gnosis-Pay-IBAN-Feature))
</Warning>

## Enabling the IBAN Integration

<Steps>
  <Step title="Signing the Monerium message">
    Monerium requires a specific message to be signed by the user's wallet to prove the ownership of the wallet.
    [Use this endpoint to get the exact message that needs to be signed](/api-reference/iban/get-the-message-that-needs-to-be-signed-for-iban-activation):

    ```bash cURL theme={null}
    curl -X GET /api/v1/ibans/signing-message
    ```

    <Warning>
      We cannot request new IBANs nor transfer existing IBANs until the message signature is completed. This signature is a mandatory requirement from Monerium to verify ownership of the address.
    </Warning>
  </Step>

  <Step title="Sign the Message with the User's Wallet">
    Use the message string returned from [step 1](#signing-the-monerium-message) to generate a signature with the user's wallet.

    To request signature from the user's wallet, you can follow this [demo signature implementation](#message-signing-example-with-viem).
  </Step>

  <Step title="Request the IBAN from Monerium">
    [Make a POST request to this endpoint to request IBAN integration for Gnosis Pay user](https://docs.gnosispay.com/api-reference/iban/create-a-new-monerium-integration):

    ```bash cURL theme={null}
    curl --request POST \
      --url https://api.gnosispay.com/api/v1/integrations/monerium \
      --header 'Authorization: Bearer <token>' \
      --header 'Content-Type: application/json' \
      --data '{
      "signature": "<string>"
    }'
    ```

    If the request is successful, you will receive a response with the IBAN details.
    This endpoint effectively:

    * shares the user's KYC info with Monerium
    * creates an IBAN linked to the user's account

    <Warning>
      Monerium only allows the user to have one single account with them. If a Monerium account **already exists**, then there is **no need** to call this endpoint. In such cases, users can grant access to their existing Monerium account using the Monerium API directly.
    </Warning>
  </Step>

  <Step title="Get the IBAN number, BIC, Status and Connected Blockchain Address where funds are sent">
    To retrieve IBAN details including the IBAN number, BIC code, status, and connected account address, you can get them with the `bankingDetails` field from:

    ```bash cURL theme={null}
    curl -X GET /api/v1/user
    ```
  </Step>

  <Step title="Using the Monerium API">
    Follow the guide available at [https://monerium.dev/docs/welcome](https://monerium.dev/docs/welcome)
    To authenticate with their API, you can then use the method described in [https://monerium.dev/api-docs/v2#tag/auth](https://monerium.dev/api-docs/v2#tag/auth) *using the SIWE* flow.

    Once authenticated, you can manage IBANs, create instructions to transfer funds from one account to another, etc.
  </Step>
</Steps>

<Warning>
  For detailed error status codes and examples, please refer to the API Reference documentation [here for IBAN integration](https://docs.gnosispay.com/api-reference/iban/create-a-new-monerium-integration).

  The Gnosis Pay API serves as a wrapper for Monerium IBAN integration. Therefore, any issues related to Monerium integration should be addressed directly between your products and Monerium.
</Warning>

## Message Signing Example with Viem

This is an example script to generate a signature from an EOA wallet address that is an owner of GP Safe and will be linked to Monerium profile.

### Example Usage

```typescript theme={null}
import { createWalletClient, http } from 'viem';
import { gnosis } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

// Initialize wallet client with private key
const account = privateKeyToAccount('0x...' as `0x${string}`);
const walletClient = createWalletClient({
  account,
  chain: gnosis,
  transport: http()
});

// Get the message to sign from the API
const message = "I hereby declare that I am the address owner.";

// Sign the message directly with EOA
const signature = await walletClient.signMessage({
  message
});

console.log('Signature:', signature);
console.log('Signer address:', account.address);
```

<Info>
  Note:

  * The message can be fetched from the API using `GET /api/v1/ibans/signing-message`
  * The signature can be submitted to prove ownership
  * Make sure to use the correct chainId (100 for Gnosis Chain)
</Info>


# On/Off Ramp Integrations
Source: https://docs.gnosispay.com/on-off-ramps/index

Complete guide to fiat-to-crypto conversions with Gnosis Pay's integrated ramp partners

# On/Off Ramp Integrations

Convert between fiat currencies and stablecoins seamlessly with Gnosis Pay's integrated ramp partners.

<Warning>
  **No Double KYC Required**

  On/Off ramp integrations don't require users to complete another KYC process with Gnosis Pay - they can use their existing verification from our integrated partners.
</Warning>

<Info>
  **Important Partnership Requirements**

  Please be aware of the following integration requirements:

  -**Direct Provider Relationships**: The wallet/platform must establish a direct contractual relationship with the ramp provider (e.g., Noah, Monerium, Avenia) and integrate directly with their APIs. Gnosis Pay will only facilitate the KYC process by sharing the KYC collected data via Sumsub.

  * **Mandatory usage of Sumsub**: It is mandatory to use Sumsub instance to avail these integrations.

  For detailed KYC sharing implementation, please refer to our [KYC Sharing Integration Guide](on-off-ramps/kyc-sharing).
</Info>

## Available Integrations

<CardGroup>
  <Card title="💶 EUR Integration" icon="euro-sign" href="on-off-ramps/iban-integration">
    **EUR to EUR.e via Monerium**

    Full SEPA integration with IBAN support for European users.
  </Card>

  <Card title="💵 USD Integration" icon="dollar-sign" href="https://docs.noah.com/">
    **USD to USDC.e via Noah**

    Fast and reliable USD conversion for North American markets.
  </Card>

  <Card title="🇧🇷 BRL Integration" icon="brazilian-real-sign" href="https://integration-guide.avenia.io/">
    **BRL to BRLA via Avenia**

    Brazilian Real support specifically designed for LatAm markets.
  </Card>
</CardGroup>


# KYC sharing for GP Partners
Source: https://docs.gnosispay.com/on-off-ramps/kyc-sharing

This guide explains how to share existing Gnosis Pay KYC data with GP Partners using Sumsub's reusable token system.

## KYC Sharing Partners

KYC Sharing allows users who have already completed verification with Gnosis Pay to re-use their KYC data with partner platforms, eliminating the need for duplicate verification processes. KYC sharing is currently only available through **Sumsub** and requires a formal contract between three parties: Gnosis Pay, Sumsub, and partner platform.

<Warning>
  **Important Limitations**

  * **One-Way Sharing**: We only support **Gnosis Pay → Partner Platform** sharing. KYC data cannot be shared from partner platforms back to Gnosis Pay.
  * **Approval Not Guaranteed**: Since every company has different KYC requirements and risk policies, some Gnosis Pay approved KYCs may be rejected at the destination platform.
</Warning>

## How to get reusable token for KYC Sharing Partners

The following partners currently support KYC data sharing:

| Partner | Sumsub Client ID      |
| ------- | --------------------- |
| Noah    | `noah.com_112876`     |
| BRLA    | `brla.digital_101963` |

<Steps>
  <Step title="Get Partner's Sumsub Client ID">
    For existing partners available for KYC sharing, use one of the Client IDs from the table above. For partners not listed in the table, contact the Partner team to obtain their SumSub Client ID.
  </Step>

  <Step title="Share KYC Data">
    <p>
      Once the Sumsub Client ID has been obtained, generate a reusable token using the Gnosis Pay API.
    </p>

    ```bash cURL theme={null}
    curl --request POST \
      --url https://api.gnosispay.com/api/v1/kyc/import-partner-applicant \
      --header 'Authorization: Bearer <token>' \
      --header 'Content-Type: application/json' \
      --data '{
      "forClientId": "noah.com_112876",
      "ttlInSecs": 600
    }'
    ```
  </Step>

  <Step title="Get applicant data from Sumsub">
    <p>
      Share this token to Sumsub's API to re-use the KYC and get data for users. To learn more about how to use Sumsub's API, visit their documentation [here](https://docs.sumsub.com/docs/reusable-kyc).
    </p>

    ```bash cURL theme={null}
    curl --request POST \
         --url https://api.sumsub.com/resources/api/reusableIdentity/reuse
    ```
  </Step>
</Steps>


# Onboard Users to Gnosis Pay
Source: https://docs.gnosispay.com/onboarding-flow

How to onboard new Users to Gnosis Pay.

Welcome! This guide will walk you through the journey to implement the complete onboarding of a user, from the first time they connect their wallet, to the point where they can order a card (physical or virtual) and start using it.

If you want to see how it all comes together, check out our open-source [Gnosis Pay UI](https://github.com/gnosispay/ui) for a reference implementation.

Let's jump right in!

## 1. Authentication

First things first: your users need to authenticate with our API.
This is covered in detail in the [Authentication Flow](/auth) section.
Once they're authenticated, you'll get a `jwt`, you'll need it for all the next steps.

## 2. User Registration

Now that you've got your `jwt` token, it's time to register your user in the Gnosis Pay system.

<Note>
  There are 2 ways to know whether they are already registered or not:

  * **Check the JWT:** If the decoded JWT has a `userId`, your user is already registered.
  * **Or, call the user endpoint:** Try [`GET /api/v1/user`](/api-reference/user/get-the-user-profile). If you get a `401 Unauthorized Error`, the user isn't registered yet.
</Note>

<Steps>
  <Step title="Signup with email">
    You can register a user with their `email` and `partnerId`, [see api documentation](/api-reference/authentication/create-a-new-user).

    <Note>
      The `partnerId` is a unique identifier for your app that you can get instantly from the [Partners Dashboard](https://partners.gnosispay.com/). This is the only place where you need to include it in the request.
    </Note>

    If you have a `referralCouponCode`, you can include it here too.

    ```bash cURL theme={null}
    curl -X POST /api/v1/auth/signup \
    -d '{
      "authEmail": "string",
      "partnerId": "string",
      "referralCouponCode": "string" (optional)
    }'
    ```
  </Step>

  <Step title="Accept Terms of Service (ToS)">
    At this point, the user is registered in the Gnosis Pay system and has an associated user id.
    Users need to accept our terms of service and those from our partners. To streamline the process, you can do this step together with the previous one.

    We recommend having a mapping in your app, between the ToS id and their title and urls, so you can display the title and link out for users to read the full text. Make sure they check a box to accept before moving on!

    <Info>
      This endpoint can only be called once the user is registered. Hence the proposed mapping.
    </Info>

    Get the terms for the user [(spec)](/api-reference/user/retrieve-terms-and-conditions-status):

    ```bash cURL theme={null}
    curl -X GET /api/v1/user/terms
    ```

    We recommend you link each ID received on this endpoint with a title in your app:

    ```javascript theme={null}
    const tosToTitle = {
      "general-tos": "Gnosis Pay Terms of Service",
      "card-monavate-tos": "Cardholder Terms of Service",
      "cashback-tos": "Cashback Terms of Service",
      "privacy-policy": "Gnosis Pay Privacy and Cookies Policy"
    }
    ```

    Once the user has reviewed and accepted the ToS, you can call the endpoint to accept each ToS that the user hadn't accepted yet [(spec)](/api-reference/user/accept-terms-and-conditions):

    ```bash cURL theme={null}
    curl -X POST /api/v1/user/terms \
    -d '{
      "terms": "string", // e.g. "general-tos"
      "version": "string" // e.g. "TOS_GENERAL_VERSION_1"
    }'
    ```
  </Step>
</Steps>

## 3. KYC Process

To order a card, your users will need to go through a KYC process with our partner Sumsub. The whole KYC flow happens in a Sumsub iframe, and in the background, the Gnosis Pay API keeps you updated on your user's `kycStatus` (check it with [`GET /api/v1/user`](/api-reference/user/retrieve-user-profile)

Here are the different KYC statuses you might see, and what they mean for your user:

| **KYC Status**          | **Description**                                                       | **What your user should do** |
| ----------------------- | --------------------------------------------------------------------- | ---------------------------- |
| `notStarted`            | No KYC process started                                                | Start KYC                    |
| `documentsRequested`    | Applicant must upload documents. Status moves to `pending` when done. | Upload documents             |
| `pending`               | Awaiting verification processing                                      | Nothing—just wait!           |
| `processing`            | Profile is being processed                                            | Nothing—system is checking   |
| `approved`              | All verification checks passed                                        | Nothing—KYC is complete      |
| `resubmissionRequested` | Some checks failed; user can re-submit required steps                 | Re-submit documents          |
| `rejected`              | Final rejection; user cannot try again                                | Nothing (final rejection)    |
| `requiresAction`        | Manual check required by our team                                     | Wait or contact support      |

<Note>
  You should start the KYC process if your user is registered and their `kycStatus` is `notStarted` or `documentsRequested`.
</Note>

<Steps>
  <Step title="Get the Sumsub iframe URL or SDK token">
    By default, each user gets a unique URL for their KYC process.
    Get it with [(spec)](/api-reference/kyc/retrieve-link-for-web-integration):

    ```bash cURL theme={null}
    curl -X GET /api/v1/kyc/integration
    ```

    For mobile integrations, you can use the Sumsub Mobile SDK.
    To instantiate their SDK you need an access token that you can get from [(spec)](/api-reference/kyc/retrieve-access-token-for-sumsub-sdk-integration):

    ```bash cURL theme={null}
    curl -X GET /api/v1/kyc/integration/sdk
    ```
  </Step>

  <Step title="Monitor KYC Status">
    While the whole KYC flow happens in an iframe, it is advised to constantly monitor the `kycStatus` from the user endpoint, and act if users are in certain states.

    Provide a way to contact your support if the `kycStatus` is:

    * `requiresAction`
    * `rejected`

    If the status is one of the following, there's nothing to do on your side:

    * `pending`
    * `processing`
    * `resubmissionRequested`

    Finally, if the status is `approved`, you can move on to the next step.
  </Step>

  <Step title="Source of funds questionnaire">
    For regulatory reasons, users need to answer a couple of questions regarding the source of funds for their card.

    <Note>
      Users should be ready for this step if:

      * they are registered (a `userId` is present in the JWT)
      * their `kycStatus` is `approved`
      * the field `isSourceOfFundsAnswered` on the user endpoint response is `false`
    </Note>

    You can get the list of questions and possible answers at this endpoint [(spec)](/api-reference/kyc/retrieve-source-of-funds-questions):

    ```bash cURL theme={null}
    curl -X GET /api/v1/source-of-funds
    ```

    Show these questions to your user and collect their answers. You'll need to send all the answers together in one go [(spec)](/api-reference/kyc/answer-source-of-funds-questions):

    ```bash cURL theme={null}
    curl -X POST /api/v1/source-of-funds \
    -d '[
      {
        question: "string",
        answer: "string"
      },
      ...
    ]'
    ```

    Don't forget to include the question title with each answer. If you want to see how this looks in practice, check out [Gnosis Pay UI](https://github.com/gnosispay/ui).
  </Step>

  <Step title="Phone Verification with OTP">
    Last but not least, your users need to verify their mobile phone. Just like with email, they'll enter their phone number, get a one-time password (OTP), and we'll verify it.

    <Note>
      This step is needed if:

      * The user is registered (`userId` in JWT)
      * `kycStatus` is `approved`
      * `isPhoneValidated` is `false` in the user endpoint response
    </Note>

    Validate the phone number by first requesting an OTP [(spec)](/api-reference/kyc/retrieve-an-otp-code-to-verify-a-phone-number):

    ```bash cURL theme={null}
    curl -X POST /api/v1/verification \
    -d '{
      "phoneNumber": "string"
    }'
    ```

    This will send a code to the user's phone number, which in turn needs to be passed on to the check endpoint [(spec)](/api-reference/kyc/verify-a-phone-number-with-otp-code):

    ```bash cURL theme={null}
    curl -X POST /api/v1/verification/check \
    -d '{
      "code": "string"
    }'
    ```

    Once that's done, `isPhoneValidated` will be `true`.
  </Step>
</Steps>

<Note>
  User's safe is ready for configuration if:

  * They are registered (`userId` in JWT)
  * `kycStatus` is `approved`
  * `isSourceOfFundsAnswered` is `true`
  * `isPhoneValidated` is `true`
  * `safeWallet` is an empty array in the user endpoint response
</Note>

## 4. Safe Account Configuration

Gnosis Pay uses Safe accounts for on-chain transactions. This endpoint deploys GP Safe with currency and setup delay and roles modules for the GP Safe.

The currency is automatically assigned based on the user's country:

* UK users (GB): GBPe
* Brazil users (BR): USDCe
* Users from other countries: EURe (default)

<Note>
  Before this, note that the field `accountStatus` is a number that is not `0` in the response from [`GET /api/v1/safe-config`](/api-reference/safe-management/retrieve-safe-configuration).
  `accountStatus: 0` would mean that the Safe modules are already deployed.
</Note>

```bash cURL theme={null}
curl --request POST \
  --url https://api.gnosispay.com/api/v1/safe/deploy \
  --header 'Authorization: Bearer <token>'
```

<Note>
  If safe deployment request is successful, it will return as "accepted" from endpoint. From here it can take up to 1 minute for safe deployment and module setup.
</Note>

## 5. Monitor Safe Deployment Status

After initiating the GP Safe deployment, monitor the deployment progress using the [v1/safe/deploy](https://docs.gnosispay.com/api-reference/safe-management/get-the-safe-deployment-status) endpoint:

```bash cURL theme={null}
curl --request GET \
  --url https://api.gnosispay.com/api/v1/safe/deploy \
  --header 'Authorization: Bearer <token>'
```

### Verify safe configuration post deployment

Once deployment is complete, verify the Safe is fully configured by checking the account status:

```bash cURL theme={null}
curl --request GET \
  --url https://api.gnosispay.com/api/v1/safe-config \
  --header 'Authorization: Bearer <token>'
```

<Note>
  When `accountStatus` is **0**, the GP Safe is fully configured and ready for use.
</Note>

### Using Account-Kit for Integrity Status

Gnosis Pay Account-Kit library [`@gnosispay/account-kit`](https://github.com/gnosispay/account-kit) can provide a handy `AccountIntegrityStatus` enum.

* `AccountIntegrityStatus.Ok`, which is `0`, means that the Safe modules are already deployed.
* `AccountIntegrityStatus.DelayQueueNotEmpty`, which is `7`, means the module is deployed correctly, but the Safe has a pending transaction, which could happen later on.

If your interface is verifying the Safe modules deployment, both these statuses should be considered as valid.


# Card Transactions Overview
Source: https://docs.gnosispay.com/transactions/index

Comprehensive guide to understanding card transaction types, lifecycle, and integration patterns

Card transactions in Gnosis Pay follow the standard payment card industry lifecycle but with unique behaviors for different transaction kinds. This guide will help you understand how transactions work, when they appear in the API, and how to handle them in your integration.

## Transaction Kinds

The Gnosis Pay API returns three distinct types of transaction events, each with different behaviors and timing:

### Payment

Regular card transactions including purchases, ATM withdrawals, and other card usage.

**Key Characteristics:**

* **Immediate visibility**: Appears in the API immediately after authorization
* **Status tracking**: Has a `status` field indicating approval, decline reasons, or reversals
* **Pending behavior**: Shows `isPending: true` when authorized but not yet settled
* **Settlement timing**: Usually settles within 24 hours, but can take up to a month for certain merchants (hotels, car rentals)

**Common scenarios:**

* Point-of-sale purchases
* ATM cash withdrawals
* Online purchases
* Hotel pre-authorizations

### Refund

Money being returned to the cardholder's account, typically from product returns or service cancellations.

**Key Characteristics:**

* **Delayed visibility**: Only appears after both authorization AND clearing are processed
* **No status field**: Unlike payments, refunds don't have approval/decline status
* **Amount fields**: Includes `refundAmount` and `refundCurrency` fields
* **Pending behavior**: Can still show `isPending: true` if additional clearing steps are required

**Common scenarios:**

* Product returns to merchants
* Service cancellations
* Merchant-initiated refunds
* Dispute resolutions

### Reversal

Cancellation or reversal of previous transactions, often due to technical issues or merchant corrections.

**Key Characteristics:**

* **Variable timing**: Can appear immediately (authorization-level) or after clearing
* **Amount fields**: Includes `reversalAmount` and `reversalCurrency` fields
* **Quick processing**: Usually processed faster than refunds
* **No status field**: Similar to refunds, no approval/decline status

**Common scenarios:**

* Duplicate transaction corrections
* Technical payment processing errors
* Merchant-initiated transaction cancellations
* Partial transaction reversals

## Transaction Lifecycle

Understanding the transaction lifecycle is crucial for proper integration:

### Authorization Phase

1. **Card Usage**: Customer uses card at merchant
2. **Authorization Request**: Merchant requests payment authorization
3. **Real-time Processing**: Gnosis Pay validates funds, limits, and fraud checks
4. **Response**: Authorization approved or declined
5. **API Visibility**:
   * **Payments**: Immediately visible with `isPending: true`
   * **Refunds**: Not yet visible (requires clearing)
   * **Reversals**: May be visible if authorization-level reversal

### Clearing Phase

1. **Settlement Processing**: Usually within 24 hours (can be longer for certain MCCs)
2. **Final Amount**: May differ from authorization amount
3. **API Updates**:
   * **Payments**: `isPending` becomes `false`, `clearedAt` is set
   * **Refunds**: Now become visible in the API
   * **Reversals**: Update with final amounts and timing

## Integration Best Practices

### Handling Different Transaction Kinds

```javascript theme={null}
// Example: Processing different transaction types
transactions.forEach(transaction => {
  switch (transaction.kind) {
    case 'Payment':
      if (transaction.isPending) {
        // Handle pending payment
        console.log(`Pending payment: ${transaction.billingAmount}`);
        // Show as "Processing" in UI
      } else {
        // Handle completed payment
        console.log(`Completed payment: ${transaction.status}`);
      }
      break;

    case 'Refund':
      // Refunds are typically not pending when they appear
      console.log(`Refund received: ${transaction.refundAmount}`);
      // Update account balance, notify user
      break;

    case 'Reversal':
      // Handle transaction reversal
      console.log(`Transaction reversed: ${transaction.reversalAmount}`);
      // Reverse previous transaction effects
      break;
  }
});
```

### Monitoring Transaction Status

```javascript theme={null}
// Example: Monitoring pending transactions
const monitorPendingTransactions = async () => {
  const response = await fetch('/api/v1/cards/transactions');
  const data = await response.json();

  const pendingTransactions = data.results.filter(t => t.isPending);

  if (pendingTransactions.length > 0) {
    console.log(`${pendingTransactions.length} transactions pending settlement`);
    // Schedule next check or set up webhooks for updates
  }
};
```

### Error Handling

Different transaction kinds may have different error scenarios:

* **Payments**: Can be declined for various reasons (insufficient funds, incorrect PIN, etc.)
* **Refunds**: Usually appear only when successfully processed
* **Reversals**: Indicate correction of previous errors

## Common Integration Patterns

### Real-time Balance Updates

* **Payments**: Money is immediately deducted from user account and moved to hold account on chain when `isPending: true`
* **Refunds**: Add to balance when transaction appears (usually already cleared)
* **Reversals**: Adjust balance based on reversal type and amount

### User Notifications

* **Payments**: Notify immediately for both pending and completed
* **Refunds**: Notify when refund appears (money is being returned)
* **Reversals**: Notify about transaction corrections

### Transaction History Display

* Show transaction kind clearly in the UI
* Use `isPending` status for appropriate visual indicators
* Handle currency conversions (billing vs transaction currency)
* Display appropriate amounts based on transaction kind

## Next Steps

* [Transaction Lifecycle Details](/transactions/lifecycle) - Deep dive into authorization and clearing
* [API Integration Guide](/transactions/integration-guide) - Complete integration examples
* [API Reference](/api-reference/transactions/list-card-transactions) - Full API documentation


# Transaction Integration Guide
Source: https://docs.gnosispay.com/transactions/integration-guide

Complete examples and best practices for integrating with Gnosis Pay transaction APIs

This guide provides comprehensive examples and patterns for integrating with Gnosis Pay's transaction APIs, covering all three transaction kinds and their unique behaviors.

## Basic Integration Setup

### Authentication and API Setup

<CodeGroup>
  ```javascript JavaScript theme={null}
  const GNOSIS_PAY_API = 'https://api.gnosispay.com';

  class GnosisPayClient {
    constructor(authToken) {
      this.authToken = authToken;
    }

    async getTransactions(params = {}) {
      const queryParams = new URLSearchParams(params);
      const response = await fetch(
        `${GNOSIS_PAY_API}/api/v1/cards/transactions?${queryParams}`,
        {
          headers: {
            'Authorization': `Bearer ${this.authToken}`,
            'Content-Type': 'application/json'
          }
        }
      );

      if (!response.ok) {
        throw new Error(`API Error: ${response.status}`);
      }

      return response.json();
    }
  }
  ```

  ```python Python theme={null}
  import requests
  from typing import Dict, Any, Optional

  class GnosisPayClient:
      def __init__(self, auth_token: str):
          self.auth_token = auth_token
          self.base_url = "https://api.gnosispay.com"

      def get_transactions(self, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
          headers = {
              "Authorization": f"Bearer {self.auth_token}",
              "Content-Type": "application/json"
          }

          response = requests.get(
              f"{self.base_url}/api/v1/cards/transactions",
              headers=headers,
              params=params or {}
          )

          response.raise_for_status()
          return response.json()
  ```

  ```curl cURL theme={null}
  # Get all transactions
  curl -X GET "https://api.gnosispay.com/api/v1/cards/transactions" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Content-Type: application/json"

  # Get transactions with filters
  curl -X GET "https://api.gnosispay.com/api/v1/cards/transactions?limit=50&after=2024-01-01T00:00:00Z" \
    -H "Authorization: Bearer YOUR_JWT_TOKEN" \
    -H "Content-Type: application/json"
  ```
</CodeGroup>

## Handling Different Transaction Kinds

### Transaction Processing Logic

<CodeGroup>
  ```javascript JavaScript theme={null}
  class TransactionProcessor {
    processTransactions(transactions) {
      const processed = {
        payments: { pending: [], completed: [] },
        refunds: [],
        reversals: []
      };

      transactions.forEach(transaction => {
        switch (transaction.kind) {
          case 'Payment':
            this.processPayment(transaction, processed);
            break;
          case 'Refund':
            this.processRefund(transaction, processed);
            break;
          case 'Reversal':
            this.processReversal(transaction, processed);
            break;
          default:
            console.warn('Unknown transaction kind:', transaction.kind);
        }
      });

      return processed;
    }

    processPayment(payment, processed) {
      if (payment.isPending) {
        processed.payments.pending.push({
          ...payment,
          displayStatus: 'Processing',
          balanceImpact: -parseInt(payment.billingAmount), // Already deducted
          canCancel: this.canCancelPayment(payment)
        });
      } else {
        processed.payments.completed.push({
          ...payment,
          displayStatus: this.getPaymentDisplayStatus(payment),
          balanceImpact: 0, // Already accounted for when pending
          settlementDate: payment.clearedAt
        });
      }
    }

    processRefund(refund, processed) {
      processed.refunds.push({
        ...refund,
        displayStatus: 'Refund Processed',
        balanceImpact: parseInt(refund.refundAmount), // Money returned
        refundDate: refund.clearedAt,
        originalTransaction: this.findOriginalTransaction(refund)
      });
    }

    processReversal(reversal, processed) {
      processed.reversals.push({
        ...reversal,
        displayStatus: 'Transaction Reversed',
        balanceImpact: parseInt(reversal.reversalAmount), // Money returned
        reversalDate: reversal.clearedAt,
        reversalReason: this.determineReversalReason(reversal)
      });
    }

    getPaymentDisplayStatus(payment) {
      switch (payment.status) {
        case 'Approved': return 'Completed';
        case 'IncorrectPin': return 'Failed - Incorrect PIN';
        case 'InsufficientFunds': return 'Failed - Insufficient Funds';
        case 'Reversal': return 'Reversed';
        case 'PartialReversal': return 'Partially Reversed';
        default: return 'Completed';
      }
    }
  }
  ```

  ```python Python theme={null}
  from dataclasses import dataclass
  from typing import List, Dict, Any
  from datetime import datetime

  @dataclass
  class ProcessedTransaction:
      original: Dict[str, Any]
      display_status: str
      balance_impact: int
      additional_info: Dict[str, Any]

  class TransactionProcessor:
      def process_transactions(self, transactions: List[Dict[str, Any]]) -> Dict[str, List]:
          processed = {
              "payments": {"pending": [], "completed": []},
              "refunds": [],
              "reversals": []
          }

          for transaction in transactions:
              kind = transaction.get("kind")

              if kind == "Payment":
                  self._process_payment(transaction, processed)
              elif kind == "Refund":
                  self._process_refund(transaction, processed)
              elif kind == "Reversal":
                  self._process_reversal(transaction, processed)
              else:
                  print(f"Warning: Unknown transaction kind: {kind}")

          return processed

      def _process_payment(self, payment: Dict[str, Any], processed: Dict):
          if payment.get("isPending"):
              processed["payments"]["pending"].append(
                  ProcessedTransaction(
                      original=payment,
                      display_status="Processing",
                      balance_impact=-int(payment["billingAmount"]),
                      additional_info={
                          "can_cancel": self._can_cancel_payment(payment),
                          "estimated_settlement": self._estimate_settlement_time(payment)
                      }
                  )
              )
          else:
              processed["payments"]["completed"].append(
                  ProcessedTransaction(
                      original=payment,
                      display_status=self._get_payment_display_status(payment),
                      balance_impact=0,  # Already accounted for when pending
                      additional_info={
                          "settlement_date": payment.get("clearedAt")
                      }
                  )
              )

      def _get_payment_display_status(self, payment: Dict[str, Any]) -> str:
          status_map = {
              "Approved": "Completed",
              "IncorrectPin": "Failed - Incorrect PIN",
              "InsufficientFunds": "Failed - Insufficient Funds",
              "Reversal": "Reversed",
              "PartialReversal": "Partially Reversed"
          }
          return status_map.get(payment.get("status"), "Completed")
  ```
</CodeGroup>

## Next Steps

* [Transaction Lifecycle](/transactions/lifecycle) - Understand the detailed flow
* [API Reference](/api-reference/transactions/list-card-transactions) - Complete API documentation
* [Transaction Overview](/transactions) - Back to main guide


# Transaction Lifecycle
Source: https://docs.gnosispay.com/transactions/lifecycle

Deep dive into the authorization and clearing process for card transactions

Understanding the transaction lifecycle is essential for building robust integrations with Gnosis Pay. This guide explains the detailed flow from card usage to final settlement.

## Overview

Card transactions follow a two-phase process:

1. **Authorization Phase**: Real-time approval/decline of the transaction
2. **Clearing Phase**: Final settlement and fund transfer (usually 24-48 hours later)

Different transaction kinds have different behaviors in each phase.

## Authorization Phase

### Payment Authorization

When a customer uses their Gnosis Pay card:

<Steps>
  <Step title="Card Presentation">
    Customer presents card at merchant (physical swipe/insert or online entry)
  </Step>

  <Step title="Authorization Request">
    Merchant's payment processor sends authorization request to Gnosis Pay
  </Step>

  <Step title="Real-time Validation">
    Gnosis Pay performs multiple checks:

    * Available balance verification
    * Card status (active, not frozen)
    * Spending limits compliance
    * Anti-fraud analysis
    * AML screening
  </Step>

  <Step title="Authorization Response">
    Gnosis Pay responds with approval or decline
  </Step>

  <Step title="Fund Deduction">
    If approved, money is immediately deducted from user account and moved to hold account on chain
  </Step>

  <Step title="API Visibility">
    Transaction appears immediately in `/api/v1/cards/transactions` with:

    * `kind: "Payment"`
    * `isPending: true`
    * `clearedAt: null`
    * `status: "Approved"` (or decline reason)
  </Step>
</Steps>

### Refund Authorization

Refunds have a different authorization flow:

<Steps>
  <Step title="Merchant Initiation">
    Merchant initiates refund (product return, service cancellation)
  </Step>

  <Step title="Refund Authorization">
    Merchant sends refund authorization request
  </Step>

  <Step title="Authorization Processing">
    Gnosis Pay validates the refund request
  </Step>

  <Step title="No Immediate API Visibility">
    **Important**: Refund does NOT appear in API yet - requires clearing
  </Step>
</Steps>

### Reversal Authorization

Reversals can happen at the authorization level:

<Steps>
  <Step title="Error Detection">
    System or merchant detects transaction error
  </Step>

  <Step title="Reversal Request">
    Immediate reversal request sent
  </Step>

  <Step title="Authorization Reversal">
    Original authorization is reversed
  </Step>

  <Step title="API Visibility">
    May appear immediately as reversal or update original payment status
  </Step>
</Steps>

## Clearing Phase

The clearing phase typically occurs 24-48 hours after authorization, but timing varies by merchant type.

### Standard Clearing Timeline

* **Most merchants**: 24-48 hours
* **Hotels**: Can be up to 30 days (for incidentals)
* **Car rentals**: Up to 30 days
* **Airlines**: Usually 24-48 hours
* **Gas stations**: Often same day

### Payment Clearing

<Steps>
  <Step title="Clearing Initiation">
    Merchant submits clearing record (usually batch processed overnight)
  </Step>

  <Step title="Amount Reconciliation">
    Clearing amount may differ from authorization:

    * **Exact match**: Most common scenario
    * **Partial capture**: Lower amount (unused authorization released)
    * **Over capture**: Higher amount (allowed for specific MCCs like hotels)
  </Step>

  <Step title="Final Settlement">
    Money is transferred from hold account on chain to merchant
  </Step>

  <Step title="API Update">
    Transaction updates in API:

    * `isPending: false`
    * `clearedAt: "2024-01-15T02:30:00Z"`
    * Amounts may be updated if different from authorization
  </Step>
</Steps>

### Refund Clearing

Refunds require both authorization AND clearing to appear:

<Steps>
  <Step title="Credit Voucher Processing">
    Merchant submits credit voucher (BaseII transaction code "06")
  </Step>

  <Step title="Refund Validation">
    System validates refund against original transaction
  </Step>

  <Step title="Fund Credit">
    Funds are credited back to cardholder account
  </Step>

  <Step title="API Appearance">
    Refund now appears in API:

    * `kind: "Refund"`
    * `isPending: false` (usually)
    * `clearedAt: "2024-01-15T08:20:00Z"`
    * `refundAmount` and `refundCurrency` fields
  </Step>
</Steps>

## Edge Cases and Special Scenarios

### Partial Authorizations and Captures

Some merchants may:

* **Partial capture**: Capture less than authorized amount
* **Multi capture**: Multiple captures on single authorization
* **Incremental authorization**: Additional authorizations (hotels for incidentals)

### Force Captures

Rare but possible scenarios:

* **Offline transactions**: POS terminals without internet (airlines)
* **Force capture**: Capture on previously declined authorization

### Authorization Expiry

If not captured within time limits:

* Authorization expires (typically 7-30 days)
* Money is returned from hold account back to user account on chain
* Transaction may disappear from API or show as expired

## Webhook Integration

For real-time updates, consider implementing webhooks to be notified when:

* Pending payments are settled
* Refunds are processed
* Reversals occur

## Troubleshooting Common Issues

### Missing Transactions

* **Payments not appearing**: Check authorization was approved
* **Refunds not appearing**: Ensure both authorization and clearing completed
* **Delayed settlements**: Some MCCs have extended clearing times

### Status Confusion

* **isPending behavior**: Different meanings for different transaction kinds
* **Timing expectations**: Clearing can take hours to days depending on merchant

## Next Steps

* [Integration Guide](/transactions/integration-guide) - Complete implementation examples
* [API Reference](/api-reference/transactions/list-card-transactions) - Full API documentation
* [Transaction Overview](/transactions) - Back to main transactions guide


# Events
Source: https://docs.gnosispay.com/webhooks/events



## KYC Events

### kyc.phone-validation.changed

Triggered when a user's phone validation status changes.

**Event Type**: `kyc.phone-validation.changed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "kyc.phone-validation.changed";
    data: {
      /** Unique user identifier */
      id: string;
      /** User email address */
      email: string;
      /** User phone number */
      phone: string;
      /** User first name */
      firstName: string;
      /** User last name */
      lastName: string;
      /** Primary address line */
      address1: string;
      /** Secondary address line */
      address2: string;
      /** City */
      city: string;
      /** Postal/ZIP code */
      postalCode: string;
      /** State/Province */
      state: string;
      /** Country */
      country: string;
      /** Nationality country */
      nationalityCountry: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Wallet address */
        address: string;
      }[];
      /** User's safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string;
      }[];
      /** KYC verification status */
      kycStatus: "notStarted" | "documentsRequested" | "pending" | "processing" | "approved" | "resubmissionRequested" | "rejected" | "requiresAction";
      /** Available features for the user */
      availableFeatures: {
        /** Whether Monerium IBAN is available */
        moneriumIban: boolean;
      };
      /** User's cards */
      cards: {
        /** Card ID */
        id: string;
        /** Card token */
        cardToken: string;
        /** Last four digits of card */
        lastFourDigits: string;
        /** Name embossed on card */
        embossedName: string;
        /** Card activation timestamp */
        activatedAt: string;
        /** Whether card is virtual */
        virtual: boolean;
      }[];
      /** User's banking details */
      bankingDetails: {
        /** Monerium IBAN */
        moneriumIban: string;
        /** Monerium BIC */
        moneriumBic: string;
        /** Monerium IBAN status */
        moneriumIbanStatus: string;
        /** Banking address */
        address: string;
      };
      /** Whether source of funds question was answered */
      isSourceOfFundsAnswered: boolean;
      /** Whether phone number is validated */
      isPhoneValidated: boolean;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "kyc.phone-validation.changed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a user's phone validation status changes."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "kyc.phone-validation.changed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique user identifier"
                },
                "email": {
                  "type": "string",
                  "nullable": true,
                  "description": "User email address"
                },
                "phone": {
                  "type": "string",
                  "nullable": true,
                  "description": "User phone number"
                },
                "firstName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User first name"
                },
                "lastName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User last name"
                },
                "address1": {
                  "type": "string",
                  "nullable": true,
                  "description": "Primary address line"
                },
                "address2": {
                  "type": "string",
                  "nullable": true,
                  "description": "Secondary address line"
                },
                "city": {
                  "type": "string",
                  "nullable": true,
                  "description": "City"
                },
                "postalCode": {
                  "type": "string",
                  "nullable": true,
                  "description": "Postal/ZIP code"
                },
                "state": {
                  "type": "string",
                  "nullable": true,
                  "description": "State/Province"
                },
                "country": {
                  "type": "string",
                  "nullable": true,
                  "description": "Country"
                },
                "nationalityCountry": {
                  "type": "string",
                  "nullable": true,
                  "description": "Nationality country"
                },
                "signInWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  },
                  "description": "User's sign-in wallet addresses"
                },
                "safeWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "description": "Blockchain chain ID"
                      }
                    },
                    "required": [
                      "address",
                      "chainId"
                    ]
                  },
                  "description": "User's safe wallet addresses"
                },
                "kycStatus": {
                  "type": "string",
                  "enum": [
                    "notStarted",
                    "documentsRequested",
                    "pending",
                    "processing",
                    "approved",
                    "resubmissionRequested",
                    "rejected",
                    "requiresAction"
                  ],
                  "description": "KYC verification status",
                  "example": "approved"
                },
                "availableFeatures": {
                  "type": "object",
                  "properties": {
                    "moneriumIban": {
                      "type": "boolean",
                      "description": "Whether Monerium IBAN is available"
                    }
                  },
                  "required": [
                    "moneriumIban"
                  ],
                  "description": "Available features for the user"
                },
                "cards": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Card ID"
                      },
                      "cardToken": {
                        "type": "string",
                        "description": "Card token"
                      },
                      "lastFourDigits": {
                        "type": "string",
                        "description": "Last four digits of card"
                      },
                      "embossedName": {
                        "type": "string",
                        "nullable": true,
                        "description": "Name embossed on card"
                      },
                      "activatedAt": {
                        "type": "string",
                        "nullable": true,
                        "description": "Card activation timestamp"
                      },
                      "virtual": {
                        "type": "boolean",
                        "description": "Whether card is virtual"
                      }
                    },
                    "required": [
                      "id",
                      "cardToken",
                      "lastFourDigits",
                      "embossedName",
                      "activatedAt",
                      "virtual"
                    ]
                  },
                  "description": "User's cards"
                },
                "bankingDetails": {
                  "type": "object",
                  "nullable": true,
                  "properties": {
                    "moneriumIban": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN"
                    },
                    "moneriumBic": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium BIC"
                    },
                    "moneriumIbanStatus": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN status"
                    },
                    "address": {
                      "type": "string",
                      "nullable": true,
                      "description": "Banking address"
                    }
                  },
                  "required": [
                    "moneriumIban",
                    "moneriumBic",
                    "moneriumIbanStatus",
                    "address"
                  ],
                  "description": "User's banking details"
                },
                "isSourceOfFundsAnswered": {
                  "type": "boolean",
                  "description": "Whether source of funds question was answered"
                },
                "isPhoneValidated": {
                  "type": "boolean",
                  "description": "Whether phone number is validated"
                }
              },
              "required": [
                "id",
                "email",
                "phone",
                "firstName",
                "lastName",
                "address1",
                "address2",
                "city",
                "postalCode",
                "state",
                "country",
                "nationalityCountry",
                "signInWallets",
                "safeWallets",
                "kycStatus",
                "availableFeatures",
                "cards",
                "bankingDetails",
                "isSourceOfFundsAnswered",
                "isPhoneValidated"
              ],
              "description": "User data structure",
              "example": {
                "id": "user_123",
                "email": "user@example.com",
                "phone": "+1234567890",
                "firstName": "John",
                "lastName": "Doe",
                "address1": "123 Main Street",
                "address2": "Apt 4B",
                "city": "New York",
                "postalCode": "10001",
                "state": "NY",
                "country": "US",
                "nationalityCountry": "US",
                "signInWallets": [
                  {
                    "address": "0x1234567890abcdef1234567890abcdef12345678"
                  }
                ],
                "safeWallets": [
                  {
                    "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                    "chainId": "100"
                  }
                ],
                "kycStatus": "approved",
                "availableFeatures": {
                  "moneriumIban": true
                },
                "cards": [
                  {
                    "id": "card_123",
                    "cardToken": "card_token_456",
                    "lastFourDigits": "1234",
                    "embossedName": "John Doe",
                    "activatedAt": "2024-01-15T10:30:00Z",
                    "virtual": false
                  }
                ],
                "bankingDetails": {
                  "moneriumIban": "GB82WEST12345698765432",
                  "moneriumBic": "WESTGB22",
                  "moneriumIbanStatus": "ASSIGNED",
                  "address": "123 Main Street, New York, NY 10001"
                },
                "isSourceOfFundsAnswered": true,
                "isPhoneValidated": true
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a user's phone validation status changes.",
          "example": {
            "eventType": "kyc.phone-validation.changed",
            "data": {
              "id": "user_123",
              "email": "user@example.com",
              "phone": "+1234567890",
              "firstName": "John",
              "lastName": "Doe",
              "address1": "123 Main Street",
              "address2": "Apt 4B",
              "city": "New York",
              "postalCode": "10001",
              "state": "NY",
              "country": "US",
              "nationalityCountry": "US",
              "signInWallets": [
                {
                  "address": "0x1234567890abcdef1234567890abcdef12345678"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100"
                }
              ],
              "kycStatus": "approved",
              "availableFeatures": {
                "moneriumIban": true
              },
              "cards": [
                {
                  "id": "card_123",
                  "cardToken": "card_token_456",
                  "lastFourDigits": "1234",
                  "embossedName": "John Doe",
                  "activatedAt": "2024-01-15T10:30:00Z",
                  "virtual": false
                }
              ],
              "bankingDetails": {
                "moneriumIban": "GB82WEST12345698765432",
                "moneriumBic": "WESTGB22",
                "moneriumIbanStatus": "ASSIGNED",
                "address": "123 Main Street, New York, NY 10001"
              },
              "isSourceOfFundsAnswered": true,
              "isPhoneValidated": true
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "kyc.phone-validation.changed",
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "phone": "+1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "postalCode": "10001",
    "state": "NY",
    "country": "US",
    "nationalityCountry": "US",
    "signInWallets": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ],
    "kycStatus": "approved",
    "availableFeatures": {
      "moneriumIban": true
    },
    "cards": [
      {
        "id": "card_123",
        "cardToken": "card_token_456",
        "lastFourDigits": "1234",
        "embossedName": "John Doe",
        "activatedAt": "2024-01-15T10:30:00Z",
        "virtual": false
      }
    ],
    "bankingDetails": {
      "moneriumIban": "GB82WEST12345698765432",
      "moneriumBic": "WESTGB22",
      "moneriumIbanStatus": "ASSIGNED",
      "address": "123 Main Street, New York, NY 10001"
    },
    "isSourceOfFundsAnswered": true,
    "isPhoneValidated": true
  }
}
```

### kyc.source-of-funds.changed

Triggered when a user's source of funds information changes.

**Event Type**: `kyc.source-of-funds.changed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "kyc.source-of-funds.changed";
    data: {
      /** Unique user identifier */
      id: string;
      /** User email address */
      email: string;
      /** User phone number */
      phone: string;
      /** User first name */
      firstName: string;
      /** User last name */
      lastName: string;
      /** Primary address line */
      address1: string;
      /** Secondary address line */
      address2: string;
      /** City */
      city: string;
      /** Postal/ZIP code */
      postalCode: string;
      /** State/Province */
      state: string;
      /** Country */
      country: string;
      /** Nationality country */
      nationalityCountry: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Wallet address */
        address: string;
      }[];
      /** User's safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string;
      }[];
      /** KYC verification status */
      kycStatus: "notStarted" | "documentsRequested" | "pending" | "processing" | "approved" | "resubmissionRequested" | "rejected" | "requiresAction";
      /** Available features for the user */
      availableFeatures: {
        /** Whether Monerium IBAN is available */
        moneriumIban: boolean;
      };
      /** User's cards */
      cards: {
        /** Card ID */
        id: string;
        /** Card token */
        cardToken: string;
        /** Last four digits of card */
        lastFourDigits: string;
        /** Name embossed on card */
        embossedName: string;
        /** Card activation timestamp */
        activatedAt: string;
        /** Whether card is virtual */
        virtual: boolean;
      }[];
      /** User's banking details */
      bankingDetails: {
        /** Monerium IBAN */
        moneriumIban: string;
        /** Monerium BIC */
        moneriumBic: string;
        /** Monerium IBAN status */
        moneriumIbanStatus: string;
        /** Banking address */
        address: string;
      };
      /** Whether source of funds question was answered */
      isSourceOfFundsAnswered: boolean;
      /** Whether phone number is validated */
      isPhoneValidated: boolean;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "kyc.source-of-funds.changed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a user's source of funds information changes."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "kyc.source-of-funds.changed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique user identifier"
                },
                "email": {
                  "type": "string",
                  "nullable": true,
                  "description": "User email address"
                },
                "phone": {
                  "type": "string",
                  "nullable": true,
                  "description": "User phone number"
                },
                "firstName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User first name"
                },
                "lastName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User last name"
                },
                "address1": {
                  "type": "string",
                  "nullable": true,
                  "description": "Primary address line"
                },
                "address2": {
                  "type": "string",
                  "nullable": true,
                  "description": "Secondary address line"
                },
                "city": {
                  "type": "string",
                  "nullable": true,
                  "description": "City"
                },
                "postalCode": {
                  "type": "string",
                  "nullable": true,
                  "description": "Postal/ZIP code"
                },
                "state": {
                  "type": "string",
                  "nullable": true,
                  "description": "State/Province"
                },
                "country": {
                  "type": "string",
                  "nullable": true,
                  "description": "Country"
                },
                "nationalityCountry": {
                  "type": "string",
                  "nullable": true,
                  "description": "Nationality country"
                },
                "signInWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  },
                  "description": "User's sign-in wallet addresses"
                },
                "safeWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "description": "Blockchain chain ID"
                      }
                    },
                    "required": [
                      "address",
                      "chainId"
                    ]
                  },
                  "description": "User's safe wallet addresses"
                },
                "kycStatus": {
                  "type": "string",
                  "enum": [
                    "notStarted",
                    "documentsRequested",
                    "pending",
                    "processing",
                    "approved",
                    "resubmissionRequested",
                    "rejected",
                    "requiresAction"
                  ],
                  "description": "KYC verification status",
                  "example": "approved"
                },
                "availableFeatures": {
                  "type": "object",
                  "properties": {
                    "moneriumIban": {
                      "type": "boolean",
                      "description": "Whether Monerium IBAN is available"
                    }
                  },
                  "required": [
                    "moneriumIban"
                  ],
                  "description": "Available features for the user"
                },
                "cards": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Card ID"
                      },
                      "cardToken": {
                        "type": "string",
                        "description": "Card token"
                      },
                      "lastFourDigits": {
                        "type": "string",
                        "description": "Last four digits of card"
                      },
                      "embossedName": {
                        "type": "string",
                        "nullable": true,
                        "description": "Name embossed on card"
                      },
                      "activatedAt": {
                        "type": "string",
                        "nullable": true,
                        "description": "Card activation timestamp"
                      },
                      "virtual": {
                        "type": "boolean",
                        "description": "Whether card is virtual"
                      }
                    },
                    "required": [
                      "id",
                      "cardToken",
                      "lastFourDigits",
                      "embossedName",
                      "activatedAt",
                      "virtual"
                    ]
                  },
                  "description": "User's cards"
                },
                "bankingDetails": {
                  "type": "object",
                  "nullable": true,
                  "properties": {
                    "moneriumIban": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN"
                    },
                    "moneriumBic": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium BIC"
                    },
                    "moneriumIbanStatus": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN status"
                    },
                    "address": {
                      "type": "string",
                      "nullable": true,
                      "description": "Banking address"
                    }
                  },
                  "required": [
                    "moneriumIban",
                    "moneriumBic",
                    "moneriumIbanStatus",
                    "address"
                  ],
                  "description": "User's banking details"
                },
                "isSourceOfFundsAnswered": {
                  "type": "boolean",
                  "description": "Whether source of funds question was answered"
                },
                "isPhoneValidated": {
                  "type": "boolean",
                  "description": "Whether phone number is validated"
                }
              },
              "required": [
                "id",
                "email",
                "phone",
                "firstName",
                "lastName",
                "address1",
                "address2",
                "city",
                "postalCode",
                "state",
                "country",
                "nationalityCountry",
                "signInWallets",
                "safeWallets",
                "kycStatus",
                "availableFeatures",
                "cards",
                "bankingDetails",
                "isSourceOfFundsAnswered",
                "isPhoneValidated"
              ],
              "description": "User data structure",
              "example": {
                "id": "user_123",
                "email": "user@example.com",
                "phone": "+1234567890",
                "firstName": "John",
                "lastName": "Doe",
                "address1": "123 Main Street",
                "address2": "Apt 4B",
                "city": "New York",
                "postalCode": "10001",
                "state": "NY",
                "country": "US",
                "nationalityCountry": "US",
                "signInWallets": [
                  {
                    "address": "0x1234567890abcdef1234567890abcdef12345678"
                  }
                ],
                "safeWallets": [
                  {
                    "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                    "chainId": "100"
                  }
                ],
                "kycStatus": "approved",
                "availableFeatures": {
                  "moneriumIban": true
                },
                "cards": [
                  {
                    "id": "card_123",
                    "cardToken": "card_token_456",
                    "lastFourDigits": "1234",
                    "embossedName": "John Doe",
                    "activatedAt": "2024-01-15T10:30:00Z",
                    "virtual": false
                  }
                ],
                "bankingDetails": {
                  "moneriumIban": "GB82WEST12345698765432",
                  "moneriumBic": "WESTGB22",
                  "moneriumIbanStatus": "ASSIGNED",
                  "address": "123 Main Street, New York, NY 10001"
                },
                "isSourceOfFundsAnswered": true,
                "isPhoneValidated": true
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a user's source of funds information changes.",
          "example": {
            "eventType": "kyc.source-of-funds.changed",
            "data": {
              "id": "user_123",
              "email": "user@example.com",
              "phone": "+1234567890",
              "firstName": "John",
              "lastName": "Doe",
              "address1": "123 Main Street",
              "address2": "Apt 4B",
              "city": "New York",
              "postalCode": "10001",
              "state": "NY",
              "country": "US",
              "nationalityCountry": "US",
              "signInWallets": [
                {
                  "address": "0x1234567890abcdef1234567890abcdef12345678"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100"
                }
              ],
              "kycStatus": "approved",
              "availableFeatures": {
                "moneriumIban": true
              },
              "cards": [
                {
                  "id": "card_123",
                  "cardToken": "card_token_456",
                  "lastFourDigits": "1234",
                  "embossedName": "John Doe",
                  "activatedAt": "2024-01-15T10:30:00Z",
                  "virtual": false
                }
              ],
              "bankingDetails": {
                "moneriumIban": "GB82WEST12345698765432",
                "moneriumBic": "WESTGB22",
                "moneriumIbanStatus": "ASSIGNED",
                "address": "123 Main Street, New York, NY 10001"
              },
              "isSourceOfFundsAnswered": true,
              "isPhoneValidated": true
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "kyc.source-of-funds.changed",
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "phone": "+1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "postalCode": "10001",
    "state": "NY",
    "country": "US",
    "nationalityCountry": "US",
    "signInWallets": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ],
    "kycStatus": "approved",
    "availableFeatures": {
      "moneriumIban": true
    },
    "cards": [
      {
        "id": "card_123",
        "cardToken": "card_token_456",
        "lastFourDigits": "1234",
        "embossedName": "John Doe",
        "activatedAt": "2024-01-15T10:30:00Z",
        "virtual": false
      }
    ],
    "bankingDetails": {
      "moneriumIban": "GB82WEST12345698765432",
      "moneriumBic": "WESTGB22",
      "moneriumIbanStatus": "ASSIGNED",
      "address": "123 Main Street, New York, NY 10001"
    },
    "isSourceOfFundsAnswered": true,
    "isPhoneValidated": true
  }
}
```

### kyc.status.changed

Triggered when a user's KYC status changes.

**Event Type**: `kyc.status.changed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "kyc.status.changed";
    data: {
      /** Unique user identifier */
      id: string;
      /** User email address */
      email: string;
      /** User phone number */
      phone: string;
      /** User first name */
      firstName: string;
      /** User last name */
      lastName: string;
      /** Primary address line */
      address1: string;
      /** Secondary address line */
      address2: string;
      /** City */
      city: string;
      /** Postal/ZIP code */
      postalCode: string;
      /** State/Province */
      state: string;
      /** Country */
      country: string;
      /** Nationality country */
      nationalityCountry: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Wallet address */
        address: string;
      }[];
      /** User's safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string;
      }[];
      /** KYC verification status */
      kycStatus: "notStarted" | "documentsRequested" | "pending" | "processing" | "approved" | "resubmissionRequested" | "rejected" | "requiresAction";
      /** Available features for the user */
      availableFeatures: {
        /** Whether Monerium IBAN is available */
        moneriumIban: boolean;
      };
      /** User's cards */
      cards: {
        /** Card ID */
        id: string;
        /** Card token */
        cardToken: string;
        /** Last four digits of card */
        lastFourDigits: string;
        /** Name embossed on card */
        embossedName: string;
        /** Card activation timestamp */
        activatedAt: string;
        /** Whether card is virtual */
        virtual: boolean;
      }[];
      /** User's banking details */
      bankingDetails: {
        /** Monerium IBAN */
        moneriumIban: string;
        /** Monerium BIC */
        moneriumBic: string;
        /** Monerium IBAN status */
        moneriumIbanStatus: string;
        /** Banking address */
        address: string;
      };
      /** Whether source of funds question was answered */
      isSourceOfFundsAnswered: boolean;
      /** Whether phone number is validated */
      isPhoneValidated: boolean;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "kyc.status.changed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a user's KYC status changes."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "kyc.status.changed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique user identifier"
                },
                "email": {
                  "type": "string",
                  "nullable": true,
                  "description": "User email address"
                },
                "phone": {
                  "type": "string",
                  "nullable": true,
                  "description": "User phone number"
                },
                "firstName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User first name"
                },
                "lastName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User last name"
                },
                "address1": {
                  "type": "string",
                  "nullable": true,
                  "description": "Primary address line"
                },
                "address2": {
                  "type": "string",
                  "nullable": true,
                  "description": "Secondary address line"
                },
                "city": {
                  "type": "string",
                  "nullable": true,
                  "description": "City"
                },
                "postalCode": {
                  "type": "string",
                  "nullable": true,
                  "description": "Postal/ZIP code"
                },
                "state": {
                  "type": "string",
                  "nullable": true,
                  "description": "State/Province"
                },
                "country": {
                  "type": "string",
                  "nullable": true,
                  "description": "Country"
                },
                "nationalityCountry": {
                  "type": "string",
                  "nullable": true,
                  "description": "Nationality country"
                },
                "signInWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  },
                  "description": "User's sign-in wallet addresses"
                },
                "safeWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "description": "Blockchain chain ID"
                      }
                    },
                    "required": [
                      "address",
                      "chainId"
                    ]
                  },
                  "description": "User's safe wallet addresses"
                },
                "kycStatus": {
                  "type": "string",
                  "enum": [
                    "notStarted",
                    "documentsRequested",
                    "pending",
                    "processing",
                    "approved",
                    "resubmissionRequested",
                    "rejected",
                    "requiresAction"
                  ],
                  "description": "KYC verification status",
                  "example": "approved"
                },
                "availableFeatures": {
                  "type": "object",
                  "properties": {
                    "moneriumIban": {
                      "type": "boolean",
                      "description": "Whether Monerium IBAN is available"
                    }
                  },
                  "required": [
                    "moneriumIban"
                  ],
                  "description": "Available features for the user"
                },
                "cards": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Card ID"
                      },
                      "cardToken": {
                        "type": "string",
                        "description": "Card token"
                      },
                      "lastFourDigits": {
                        "type": "string",
                        "description": "Last four digits of card"
                      },
                      "embossedName": {
                        "type": "string",
                        "nullable": true,
                        "description": "Name embossed on card"
                      },
                      "activatedAt": {
                        "type": "string",
                        "nullable": true,
                        "description": "Card activation timestamp"
                      },
                      "virtual": {
                        "type": "boolean",
                        "description": "Whether card is virtual"
                      }
                    },
                    "required": [
                      "id",
                      "cardToken",
                      "lastFourDigits",
                      "embossedName",
                      "activatedAt",
                      "virtual"
                    ]
                  },
                  "description": "User's cards"
                },
                "bankingDetails": {
                  "type": "object",
                  "nullable": true,
                  "properties": {
                    "moneriumIban": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN"
                    },
                    "moneriumBic": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium BIC"
                    },
                    "moneriumIbanStatus": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN status"
                    },
                    "address": {
                      "type": "string",
                      "nullable": true,
                      "description": "Banking address"
                    }
                  },
                  "required": [
                    "moneriumIban",
                    "moneriumBic",
                    "moneriumIbanStatus",
                    "address"
                  ],
                  "description": "User's banking details"
                },
                "isSourceOfFundsAnswered": {
                  "type": "boolean",
                  "description": "Whether source of funds question was answered"
                },
                "isPhoneValidated": {
                  "type": "boolean",
                  "description": "Whether phone number is validated"
                }
              },
              "required": [
                "id",
                "email",
                "phone",
                "firstName",
                "lastName",
                "address1",
                "address2",
                "city",
                "postalCode",
                "state",
                "country",
                "nationalityCountry",
                "signInWallets",
                "safeWallets",
                "kycStatus",
                "availableFeatures",
                "cards",
                "bankingDetails",
                "isSourceOfFundsAnswered",
                "isPhoneValidated"
              ],
              "description": "User data structure",
              "example": {
                "id": "user_123",
                "email": "user@example.com",
                "phone": "+1234567890",
                "firstName": "John",
                "lastName": "Doe",
                "address1": "123 Main Street",
                "address2": "Apt 4B",
                "city": "New York",
                "postalCode": "10001",
                "state": "NY",
                "country": "US",
                "nationalityCountry": "US",
                "signInWallets": [
                  {
                    "address": "0x1234567890abcdef1234567890abcdef12345678"
                  }
                ],
                "safeWallets": [
                  {
                    "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                    "chainId": "100"
                  }
                ],
                "kycStatus": "approved",
                "availableFeatures": {
                  "moneriumIban": true
                },
                "cards": [
                  {
                    "id": "card_123",
                    "cardToken": "card_token_456",
                    "lastFourDigits": "1234",
                    "embossedName": "John Doe",
                    "activatedAt": "2024-01-15T10:30:00Z",
                    "virtual": false
                  }
                ],
                "bankingDetails": {
                  "moneriumIban": "GB82WEST12345698765432",
                  "moneriumBic": "WESTGB22",
                  "moneriumIbanStatus": "ASSIGNED",
                  "address": "123 Main Street, New York, NY 10001"
                },
                "isSourceOfFundsAnswered": true,
                "isPhoneValidated": true
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a user's KYC status changes.",
          "example": {
            "eventType": "kyc.status.changed",
            "data": {
              "id": "user_123",
              "email": "user@example.com",
              "phone": "+1234567890",
              "firstName": "John",
              "lastName": "Doe",
              "address1": "123 Main Street",
              "address2": "Apt 4B",
              "city": "New York",
              "postalCode": "10001",
              "state": "NY",
              "country": "US",
              "nationalityCountry": "US",
              "signInWallets": [
                {
                  "address": "0x1234567890abcdef1234567890abcdef12345678"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100"
                }
              ],
              "kycStatus": "approved",
              "availableFeatures": {
                "moneriumIban": true
              },
              "cards": [
                {
                  "id": "card_123",
                  "cardToken": "card_token_456",
                  "lastFourDigits": "1234",
                  "embossedName": "John Doe",
                  "activatedAt": "2024-01-15T10:30:00Z",
                  "virtual": false
                }
              ],
              "bankingDetails": {
                "moneriumIban": "GB82WEST12345698765432",
                "moneriumBic": "WESTGB22",
                "moneriumIbanStatus": "ASSIGNED",
                "address": "123 Main Street, New York, NY 10001"
              },
              "isSourceOfFundsAnswered": true,
              "isPhoneValidated": true
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "kyc.status.changed",
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "phone": "+1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "postalCode": "10001",
    "state": "NY",
    "country": "US",
    "nationalityCountry": "US",
    "signInWallets": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ],
    "kycStatus": "approved",
    "availableFeatures": {
      "moneriumIban": true
    },
    "cards": [
      {
        "id": "card_123",
        "cardToken": "card_token_456",
        "lastFourDigits": "1234",
        "embossedName": "John Doe",
        "activatedAt": "2024-01-15T10:30:00Z",
        "virtual": false
      }
    ],
    "bankingDetails": {
      "moneriumIban": "GB82WEST12345698765432",
      "moneriumBic": "WESTGB22",
      "moneriumIbanStatus": "ASSIGNED",
      "address": "123 Main Street, New York, NY 10001"
    },
    "isSourceOfFundsAnswered": true,
    "isPhoneValidated": true
  }
}
```

## User Lifecycle Events

### user.created

Triggered when a new user account is created in the Gnosis Pay system.

**Event Type**: `user.created`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "user.created";
    data: {
      /** Unique user identifier */
      id: string;
      /** User email address */
      email: string;
      /** User phone number */
      phone: string;
      /** User first name */
      firstName: string;
      /** User last name */
      lastName: string;
      /** Primary address line */
      address1: string;
      /** Secondary address line */
      address2: string;
      /** City */
      city: string;
      /** Postal/ZIP code */
      postalCode: string;
      /** State/Province */
      state: string;
      /** Country */
      country: string;
      /** Nationality country */
      nationalityCountry: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Wallet address */
        address: string;
      }[];
      /** User's safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string;
      }[];
      /** KYC verification status */
      kycStatus: "notStarted" | "documentsRequested" | "pending" | "processing" | "approved" | "resubmissionRequested" | "rejected" | "requiresAction";
      /** Available features for the user */
      availableFeatures: {
        /** Whether Monerium IBAN is available */
        moneriumIban: boolean;
      };
      /** User's cards */
      cards: {
        /** Card ID */
        id: string;
        /** Card token */
        cardToken: string;
        /** Last four digits of card */
        lastFourDigits: string;
        /** Name embossed on card */
        embossedName: string;
        /** Card activation timestamp */
        activatedAt: string;
        /** Whether card is virtual */
        virtual: boolean;
      }[];
      /** User's banking details */
      bankingDetails: {
        /** Monerium IBAN */
        moneriumIban: string;
        /** Monerium BIC */
        moneriumBic: string;
        /** Monerium IBAN status */
        moneriumIbanStatus: string;
        /** Banking address */
        address: string;
      };
      /** Whether source of funds question was answered */
      isSourceOfFundsAnswered: boolean;
      /** Whether phone number is validated */
      isPhoneValidated: boolean;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "user.created Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a new user account is created in the Gnosis Pay system."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "user.created"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique user identifier"
                },
                "email": {
                  "type": "string",
                  "nullable": true,
                  "description": "User email address"
                },
                "phone": {
                  "type": "string",
                  "nullable": true,
                  "description": "User phone number"
                },
                "firstName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User first name"
                },
                "lastName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User last name"
                },
                "address1": {
                  "type": "string",
                  "nullable": true,
                  "description": "Primary address line"
                },
                "address2": {
                  "type": "string",
                  "nullable": true,
                  "description": "Secondary address line"
                },
                "city": {
                  "type": "string",
                  "nullable": true,
                  "description": "City"
                },
                "postalCode": {
                  "type": "string",
                  "nullable": true,
                  "description": "Postal/ZIP code"
                },
                "state": {
                  "type": "string",
                  "nullable": true,
                  "description": "State/Province"
                },
                "country": {
                  "type": "string",
                  "nullable": true,
                  "description": "Country"
                },
                "nationalityCountry": {
                  "type": "string",
                  "nullable": true,
                  "description": "Nationality country"
                },
                "signInWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  },
                  "description": "User's sign-in wallet addresses"
                },
                "safeWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "description": "Blockchain chain ID"
                      }
                    },
                    "required": [
                      "address",
                      "chainId"
                    ]
                  },
                  "description": "User's safe wallet addresses"
                },
                "kycStatus": {
                  "type": "string",
                  "enum": [
                    "notStarted",
                    "documentsRequested",
                    "pending",
                    "processing",
                    "approved",
                    "resubmissionRequested",
                    "rejected",
                    "requiresAction"
                  ],
                  "description": "KYC verification status",
                  "example": "approved"
                },
                "availableFeatures": {
                  "type": "object",
                  "properties": {
                    "moneriumIban": {
                      "type": "boolean",
                      "description": "Whether Monerium IBAN is available"
                    }
                  },
                  "required": [
                    "moneriumIban"
                  ],
                  "description": "Available features for the user"
                },
                "cards": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Card ID"
                      },
                      "cardToken": {
                        "type": "string",
                        "description": "Card token"
                      },
                      "lastFourDigits": {
                        "type": "string",
                        "description": "Last four digits of card"
                      },
                      "embossedName": {
                        "type": "string",
                        "nullable": true,
                        "description": "Name embossed on card"
                      },
                      "activatedAt": {
                        "type": "string",
                        "nullable": true,
                        "description": "Card activation timestamp"
                      },
                      "virtual": {
                        "type": "boolean",
                        "description": "Whether card is virtual"
                      }
                    },
                    "required": [
                      "id",
                      "cardToken",
                      "lastFourDigits",
                      "embossedName",
                      "activatedAt",
                      "virtual"
                    ]
                  },
                  "description": "User's cards"
                },
                "bankingDetails": {
                  "type": "object",
                  "nullable": true,
                  "properties": {
                    "moneriumIban": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN"
                    },
                    "moneriumBic": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium BIC"
                    },
                    "moneriumIbanStatus": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN status"
                    },
                    "address": {
                      "type": "string",
                      "nullable": true,
                      "description": "Banking address"
                    }
                  },
                  "required": [
                    "moneriumIban",
                    "moneriumBic",
                    "moneriumIbanStatus",
                    "address"
                  ],
                  "description": "User's banking details"
                },
                "isSourceOfFundsAnswered": {
                  "type": "boolean",
                  "description": "Whether source of funds question was answered"
                },
                "isPhoneValidated": {
                  "type": "boolean",
                  "description": "Whether phone number is validated"
                }
              },
              "required": [
                "id",
                "email",
                "phone",
                "firstName",
                "lastName",
                "address1",
                "address2",
                "city",
                "postalCode",
                "state",
                "country",
                "nationalityCountry",
                "signInWallets",
                "safeWallets",
                "kycStatus",
                "availableFeatures",
                "cards",
                "bankingDetails",
                "isSourceOfFundsAnswered",
                "isPhoneValidated"
              ],
              "description": "User data structure",
              "example": {
                "id": "user_123",
                "email": "user@example.com",
                "phone": "+1234567890",
                "firstName": "John",
                "lastName": "Doe",
                "address1": "123 Main Street",
                "address2": "Apt 4B",
                "city": "New York",
                "postalCode": "10001",
                "state": "NY",
                "country": "US",
                "nationalityCountry": "US",
                "signInWallets": [
                  {
                    "address": "0x1234567890abcdef1234567890abcdef12345678"
                  }
                ],
                "safeWallets": [
                  {
                    "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                    "chainId": "100"
                  }
                ],
                "kycStatus": "approved",
                "availableFeatures": {
                  "moneriumIban": true
                },
                "cards": [
                  {
                    "id": "card_123",
                    "cardToken": "card_token_456",
                    "lastFourDigits": "1234",
                    "embossedName": "John Doe",
                    "activatedAt": "2024-01-15T10:30:00Z",
                    "virtual": false
                  }
                ],
                "bankingDetails": {
                  "moneriumIban": "GB82WEST12345698765432",
                  "moneriumBic": "WESTGB22",
                  "moneriumIbanStatus": "ASSIGNED",
                  "address": "123 Main Street, New York, NY 10001"
                },
                "isSourceOfFundsAnswered": true,
                "isPhoneValidated": true
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a new user account is created in the Gnosis Pay system.",
          "example": {
            "eventType": "user.created",
            "data": {
              "id": "user_123",
              "email": "user@example.com",
              "phone": "+1234567890",
              "firstName": "John",
              "lastName": "Doe",
              "address1": "123 Main Street",
              "address2": "Apt 4B",
              "city": "New York",
              "postalCode": "10001",
              "state": "NY",
              "country": "US",
              "nationalityCountry": "US",
              "signInWallets": [
                {
                  "address": "0x1234567890abcdef1234567890abcdef12345678"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100"
                }
              ],
              "kycStatus": "approved",
              "availableFeatures": {
                "moneriumIban": true
              },
              "cards": [
                {
                  "id": "card_123",
                  "cardToken": "card_token_456",
                  "lastFourDigits": "1234",
                  "embossedName": "John Doe",
                  "activatedAt": "2024-01-15T10:30:00Z",
                  "virtual": false
                }
              ],
              "bankingDetails": {
                "moneriumIban": "GB82WEST12345698765432",
                "moneriumBic": "WESTGB22",
                "moneriumIbanStatus": "ASSIGNED",
                "address": "123 Main Street, New York, NY 10001"
              },
              "isSourceOfFundsAnswered": true,
              "isPhoneValidated": true
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "user.created",
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "phone": "+1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "postalCode": "10001",
    "state": "NY",
    "country": "US",
    "nationalityCountry": "US",
    "signInWallets": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ],
    "kycStatus": "approved",
    "availableFeatures": {
      "moneriumIban": true
    },
    "cards": [
      {
        "id": "card_123",
        "cardToken": "card_token_456",
        "lastFourDigits": "1234",
        "embossedName": "John Doe",
        "activatedAt": "2024-01-15T10:30:00Z",
        "virtual": false
      }
    ],
    "bankingDetails": {
      "moneriumIban": "GB82WEST12345698765432",
      "moneriumBic": "WESTGB22",
      "moneriumIbanStatus": "ASSIGNED",
      "address": "123 Main Street, New York, NY 10001"
    },
    "isSourceOfFundsAnswered": true,
    "isPhoneValidated": true
  }
}
```

### user.tos.accepted

Triggered when a user accepts the Terms of Service.

**Event Type**: `user.tos.accepted`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "user.tos.accepted";
    data: {
      /** Unique user identifier */
      id: string;
      /** User email address */
      email: string;
      /** User phone number */
      phone: string;
      /** User first name */
      firstName: string;
      /** User last name */
      lastName: string;
      /** Primary address line */
      address1: string;
      /** Secondary address line */
      address2: string;
      /** City */
      city: string;
      /** Postal/ZIP code */
      postalCode: string;
      /** State/Province */
      state: string;
      /** Country */
      country: string;
      /** Nationality country */
      nationalityCountry: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Wallet address */
        address: string;
      }[];
      /** User's safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string;
      }[];
      /** KYC verification status */
      kycStatus: "notStarted" | "documentsRequested" | "pending" | "processing" | "approved" | "resubmissionRequested" | "rejected" | "requiresAction";
      /** Available features for the user */
      availableFeatures: {
        /** Whether Monerium IBAN is available */
        moneriumIban: boolean;
      };
      /** User's cards */
      cards: {
        /** Card ID */
        id: string;
        /** Card token */
        cardToken: string;
        /** Last four digits of card */
        lastFourDigits: string;
        /** Name embossed on card */
        embossedName: string;
        /** Card activation timestamp */
        activatedAt: string;
        /** Whether card is virtual */
        virtual: boolean;
      }[];
      /** User's banking details */
      bankingDetails: {
        /** Monerium IBAN */
        moneriumIban: string;
        /** Monerium BIC */
        moneriumBic: string;
        /** Monerium IBAN status */
        moneriumIbanStatus: string;
        /** Banking address */
        address: string;
      };
      /** Whether source of funds question was answered */
      isSourceOfFundsAnswered: boolean;
      /** Whether phone number is validated */
      isPhoneValidated: boolean;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "user.tos.accepted Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a user accepts the Terms of Service."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "user.tos.accepted"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Unique user identifier"
                },
                "email": {
                  "type": "string",
                  "nullable": true,
                  "description": "User email address"
                },
                "phone": {
                  "type": "string",
                  "nullable": true,
                  "description": "User phone number"
                },
                "firstName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User first name"
                },
                "lastName": {
                  "type": "string",
                  "nullable": true,
                  "description": "User last name"
                },
                "address1": {
                  "type": "string",
                  "nullable": true,
                  "description": "Primary address line"
                },
                "address2": {
                  "type": "string",
                  "nullable": true,
                  "description": "Secondary address line"
                },
                "city": {
                  "type": "string",
                  "nullable": true,
                  "description": "City"
                },
                "postalCode": {
                  "type": "string",
                  "nullable": true,
                  "description": "Postal/ZIP code"
                },
                "state": {
                  "type": "string",
                  "nullable": true,
                  "description": "State/Province"
                },
                "country": {
                  "type": "string",
                  "nullable": true,
                  "description": "Country"
                },
                "nationalityCountry": {
                  "type": "string",
                  "nullable": true,
                  "description": "Nationality country"
                },
                "signInWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  },
                  "description": "User's sign-in wallet addresses"
                },
                "safeWallets": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "description": "Blockchain chain ID"
                      }
                    },
                    "required": [
                      "address",
                      "chainId"
                    ]
                  },
                  "description": "User's safe wallet addresses"
                },
                "kycStatus": {
                  "type": "string",
                  "enum": [
                    "notStarted",
                    "documentsRequested",
                    "pending",
                    "processing",
                    "approved",
                    "resubmissionRequested",
                    "rejected",
                    "requiresAction"
                  ],
                  "description": "KYC verification status",
                  "example": "approved"
                },
                "availableFeatures": {
                  "type": "object",
                  "properties": {
                    "moneriumIban": {
                      "type": "boolean",
                      "description": "Whether Monerium IBAN is available"
                    }
                  },
                  "required": [
                    "moneriumIban"
                  ],
                  "description": "Available features for the user"
                },
                "cards": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "Card ID"
                      },
                      "cardToken": {
                        "type": "string",
                        "description": "Card token"
                      },
                      "lastFourDigits": {
                        "type": "string",
                        "description": "Last four digits of card"
                      },
                      "embossedName": {
                        "type": "string",
                        "nullable": true,
                        "description": "Name embossed on card"
                      },
                      "activatedAt": {
                        "type": "string",
                        "nullable": true,
                        "description": "Card activation timestamp"
                      },
                      "virtual": {
                        "type": "boolean",
                        "description": "Whether card is virtual"
                      }
                    },
                    "required": [
                      "id",
                      "cardToken",
                      "lastFourDigits",
                      "embossedName",
                      "activatedAt",
                      "virtual"
                    ]
                  },
                  "description": "User's cards"
                },
                "bankingDetails": {
                  "type": "object",
                  "nullable": true,
                  "properties": {
                    "moneriumIban": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN"
                    },
                    "moneriumBic": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium BIC"
                    },
                    "moneriumIbanStatus": {
                      "type": "string",
                      "nullable": true,
                      "description": "Monerium IBAN status"
                    },
                    "address": {
                      "type": "string",
                      "nullable": true,
                      "description": "Banking address"
                    }
                  },
                  "required": [
                    "moneriumIban",
                    "moneriumBic",
                    "moneriumIbanStatus",
                    "address"
                  ],
                  "description": "User's banking details"
                },
                "isSourceOfFundsAnswered": {
                  "type": "boolean",
                  "description": "Whether source of funds question was answered"
                },
                "isPhoneValidated": {
                  "type": "boolean",
                  "description": "Whether phone number is validated"
                }
              },
              "required": [
                "id",
                "email",
                "phone",
                "firstName",
                "lastName",
                "address1",
                "address2",
                "city",
                "postalCode",
                "state",
                "country",
                "nationalityCountry",
                "signInWallets",
                "safeWallets",
                "kycStatus",
                "availableFeatures",
                "cards",
                "bankingDetails",
                "isSourceOfFundsAnswered",
                "isPhoneValidated"
              ],
              "description": "User data structure",
              "example": {
                "id": "user_123",
                "email": "user@example.com",
                "phone": "+1234567890",
                "firstName": "John",
                "lastName": "Doe",
                "address1": "123 Main Street",
                "address2": "Apt 4B",
                "city": "New York",
                "postalCode": "10001",
                "state": "NY",
                "country": "US",
                "nationalityCountry": "US",
                "signInWallets": [
                  {
                    "address": "0x1234567890abcdef1234567890abcdef12345678"
                  }
                ],
                "safeWallets": [
                  {
                    "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                    "chainId": "100"
                  }
                ],
                "kycStatus": "approved",
                "availableFeatures": {
                  "moneriumIban": true
                },
                "cards": [
                  {
                    "id": "card_123",
                    "cardToken": "card_token_456",
                    "lastFourDigits": "1234",
                    "embossedName": "John Doe",
                    "activatedAt": "2024-01-15T10:30:00Z",
                    "virtual": false
                  }
                ],
                "bankingDetails": {
                  "moneriumIban": "GB82WEST12345698765432",
                  "moneriumBic": "WESTGB22",
                  "moneriumIbanStatus": "ASSIGNED",
                  "address": "123 Main Street, New York, NY 10001"
                },
                "isSourceOfFundsAnswered": true,
                "isPhoneValidated": true
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a user accepts the Terms of Service.",
          "example": {
            "eventType": "user.tos.accepted",
            "data": {
              "id": "user_123",
              "email": "user@example.com",
              "phone": "+1234567890",
              "firstName": "John",
              "lastName": "Doe",
              "address1": "123 Main Street",
              "address2": "Apt 4B",
              "city": "New York",
              "postalCode": "10001",
              "state": "NY",
              "country": "US",
              "nationalityCountry": "US",
              "signInWallets": [
                {
                  "address": "0x1234567890abcdef1234567890abcdef12345678"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100"
                }
              ],
              "kycStatus": "approved",
              "availableFeatures": {
                "moneriumIban": true
              },
              "cards": [
                {
                  "id": "card_123",
                  "cardToken": "card_token_456",
                  "lastFourDigits": "1234",
                  "embossedName": "John Doe",
                  "activatedAt": "2024-01-15T10:30:00Z",
                  "virtual": false
                }
              ],
              "bankingDetails": {
                "moneriumIban": "GB82WEST12345698765432",
                "moneriumBic": "WESTGB22",
                "moneriumIbanStatus": "ASSIGNED",
                "address": "123 Main Street, New York, NY 10001"
              },
              "isSourceOfFundsAnswered": true,
              "isPhoneValidated": true
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "user.tos.accepted",
  "data": {
    "id": "user_123",
    "email": "user@example.com",
    "phone": "+1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "postalCode": "10001",
    "state": "NY",
    "country": "US",
    "nationalityCountry": "US",
    "signInWallets": [
      {
        "address": "0x1234567890abcdef1234567890abcdef12345678"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ],
    "kycStatus": "approved",
    "availableFeatures": {
      "moneriumIban": true
    },
    "cards": [
      {
        "id": "card_123",
        "cardToken": "card_token_456",
        "lastFourDigits": "1234",
        "embossedName": "John Doe",
        "activatedAt": "2024-01-15T10:30:00Z",
        "virtual": false
      }
    ],
    "bankingDetails": {
      "moneriumIban": "GB82WEST12345698765432",
      "moneriumBic": "WESTGB22",
      "moneriumIbanStatus": "ASSIGNED",
      "address": "123 Main Street, New York, NY 10001"
    },
    "isSourceOfFundsAnswered": true,
    "isPhoneValidated": true
  }
}
```

## Card Events

### card.status.changed

Triggered when a card's status changes.

**Event Type**: `card.status.changed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "card.status.changed";
    data: {
      /** User ID */
      userId: string;
      /** Card token */
      cardToken: string;
      /** Previous card status */
      oldStatus: string;
      /** New card status */
      newStatus: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "card.status.changed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a card's status changes."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "card.status.changed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "cardToken": {
                  "type": "string",
                  "description": "Card token"
                },
                "oldStatus": {
                  "type": "string",
                  "description": "Previous card status"
                },
                "newStatus": {
                  "type": "string",
                  "description": "New card status"
                }
              },
              "required": [
                "userId",
                "cardToken",
                "oldStatus",
                "newStatus"
              ],
              "description": "Card status change data",
              "example": {
                "userId": "user_123",
                "cardToken": "card_123",
                "oldStatus": "inactive",
                "newStatus": "active"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a card's status changes.",
          "example": {
            "eventType": "card.status.changed",
            "data": {
              "userId": "user_123",
              "cardToken": "card_123",
              "oldStatus": "inactive",
              "newStatus": "active"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "card.status.changed",
  "data": {
    "userId": "user_123",
    "cardToken": "card_123",
    "oldStatus": "inactive",
    "newStatus": "active"
  }
}
```

### card.transaction.cleared

Triggered when a new card transaction is cleared.

**Event Type**: `card.transaction.cleared`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "card.transaction.cleared";
    data: {
      /** User ID */
      userId: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Sign-in wallet address */
        address: string;
      }[];
      /** User's Safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string | null;
        /** Token symbol */
        tokenSymbol: string | null;
        /** Creation timestamp */
        createdAt: string;
      }[];
      /** Card transaction event */
      event: {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Payment";
        status: "Approved" | "IncorrectPin" | "InsufficientFunds" | "ExceedsApprovalAmountLimit" | "InvalidAmount" | "PinEntryTriesExceeded" | "IncorrectSecurityCode" | "Reversal" | "PartialReversal" | "Other";
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Refund";
        refundAmount: string;
        refundCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Reversal";
        reversalAmount: string;
        reversalCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      };
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "card.transaction.cleared Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a new card transaction is cleared."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "card.transaction.cleared"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "signInWallets": {
                  "type": "array",
                  "description": "User's sign-in wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Sign-in wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  }
                },
                "event": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Payment"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "Approved",
                            "IncorrectPin",
                            "InsufficientFunds",
                            "ExceedsApprovalAmountLimit",
                            "InvalidAmount",
                            "PinEntryTriesExceeded",
                            "IncorrectSecurityCode",
                            "Reversal",
                            "PartialReversal",
                            "Other"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "status"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Refund"
                          ]
                        },
                        "refundAmount": {
                          "type": "string"
                        },
                        "refundCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "refundAmount",
                        "refundCurrency"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Reversal"
                          ]
                        },
                        "reversalAmount": {
                          "type": "string"
                        },
                        "reversalCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "reversalAmount",
                        "reversalCurrency"
                      ]
                    }
                  ],
                  "example": {
                    "event": {
                      "kind": "Payment",
                      "threadId": "thread_123456789",
                      "createdAt": "2024-01-15T10:30:00.000Z",
                      "clearedAt": "2024-01-15T10:35:00.000Z",
                      "isPending": false,
                      "country": {
                        "name": "United States",
                        "numeric": "840",
                        "alpha2": "US",
                        "alpha3": "USA"
                      },
                      "mcc": "5411",
                      "merchant": {
                        "name": "Grocery Store Inc",
                        "city": "New York",
                        "country": {
                          "name": "United States",
                          "numeric": "840",
                          "alpha2": "US",
                          "alpha3": "USA"
                        }
                      },
                      "billingAmount": "5000",
                      "billingCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionAmount": "5000",
                      "transactionCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionType": "purchase",
                      "cardToken": "card_token_abc123",
                      "impactsCashback": true,
                      "status": "Approved",
                      "transactions": [
                        {
                          "status": "ExecSuccess",
                          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                          "value": "5000000000000000000",
                          "data": "0x",
                          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                        }
                      ]
                    }
                  },
                  "description": "Card transaction event"
                },
                "safeWallets": {
                  "type": "array",
                  "description": "User's Safe wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "nullable": true,
                        "description": "Blockchain chain ID"
                      },
                      "tokenSymbol": {
                        "type": "string",
                        "nullable": true,
                        "description": "Token symbol"
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Creation timestamp"
                      }
                    },
                    "required": [
                      "address",
                      "createdAt"
                    ]
                  }
                }
              },
              "required": [
                "userId",
                "signInWallets",
                "event",
                "safeWallets"
              ]
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a new card transaction is cleared.",
          "example": {
            "eventType": "card.transaction.cleared",
            "data": {
              "userId": "user_123",
              "signInWallets": [
                {
                  "address": "0x1234567890123456789012345678901234567890"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100",
                  "tokenSymbol": "EURe",
                  "createdAt": "2024-01-15T10:00:00.000Z"
                }
              ],
              "event": {
                "kind": "Payment",
                "threadId": "thread_123456789",
                "createdAt": "2024-01-15T10:30:00.000Z",
                "clearedAt": "2024-01-15T10:35:00.000Z",
                "isPending": false,
                "country": {
                  "name": "United States",
                  "numeric": "840",
                  "alpha2": "US",
                  "alpha3": "USA"
                },
                "mcc": "5411",
                "merchant": {
                  "name": "Grocery Store Inc",
                  "city": "New York",
                  "country": {
                    "name": "United States",
                    "numeric": "840",
                    "alpha2": "US",
                    "alpha3": "USA"
                  }
                },
                "billingAmount": "5000",
                "billingCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionAmount": "5000",
                "transactionCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionType": "purchase",
                "cardToken": "card_token_abc123",
                "impactsCashback": true,
                "status": "Approved",
                "transactions": [
                  {
                    "status": "ExecSuccess",
                    "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                    "value": "5000000000000000000",
                    "data": "0x",
                    "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "card.transaction.cleared",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100",
        "tokenSymbol": "EURe",
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "event": {
      "kind": "Payment",
      "threadId": "thread_123456789",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clearedAt": "2024-01-15T10:35:00.000Z",
      "isPending": false,
      "country": {
        "name": "United States",
        "numeric": "840",
        "alpha2": "US",
        "alpha3": "USA"
      },
      "mcc": "5411",
      "merchant": {
        "name": "Grocery Store Inc",
        "city": "New York",
        "country": {
          "name": "United States",
          "numeric": "840",
          "alpha2": "US",
          "alpha3": "USA"
        }
      },
      "billingAmount": "5000",
      "billingCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionAmount": "5000",
      "transactionCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionType": "purchase",
      "cardToken": "card_token_abc123",
      "impactsCashback": true,
      "status": "Approved",
      "transactions": [
        {
          "status": "ExecSuccess",
          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
          "value": "5000000000000000000",
          "data": "0x",
          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        }
      ]
    }
  }
}
```

### card.transaction.created

Triggered when a new card transaction is created.

**Event Type**: `card.transaction.created`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "card.transaction.created";
    data: {
      /** User ID */
      userId: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Sign-in wallet address */
        address: string;
      }[];
      /** User's Safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string | null;
        /** Token symbol */
        tokenSymbol: string | null;
        /** Creation timestamp */
        createdAt: string;
      }[];
      /** Card transaction event */
      event: {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Payment";
        status: "Approved" | "IncorrectPin" | "InsufficientFunds" | "ExceedsApprovalAmountLimit" | "InvalidAmount" | "PinEntryTriesExceeded" | "IncorrectSecurityCode" | "Reversal" | "PartialReversal" | "Other";
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Refund";
        refundAmount: string;
        refundCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Reversal";
        reversalAmount: string;
        reversalCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      };
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "card.transaction.created Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a new card transaction is created."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "card.transaction.created"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "signInWallets": {
                  "type": "array",
                  "description": "User's sign-in wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Sign-in wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  }
                },
                "event": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Payment"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "Approved",
                            "IncorrectPin",
                            "InsufficientFunds",
                            "ExceedsApprovalAmountLimit",
                            "InvalidAmount",
                            "PinEntryTriesExceeded",
                            "IncorrectSecurityCode",
                            "Reversal",
                            "PartialReversal",
                            "Other"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "status"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Refund"
                          ]
                        },
                        "refundAmount": {
                          "type": "string"
                        },
                        "refundCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "refundAmount",
                        "refundCurrency"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Reversal"
                          ]
                        },
                        "reversalAmount": {
                          "type": "string"
                        },
                        "reversalCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "reversalAmount",
                        "reversalCurrency"
                      ]
                    }
                  ],
                  "example": {
                    "event": {
                      "kind": "Payment",
                      "threadId": "thread_123456789",
                      "createdAt": "2024-01-15T10:30:00.000Z",
                      "clearedAt": "2024-01-15T10:35:00.000Z",
                      "isPending": false,
                      "country": {
                        "name": "United States",
                        "numeric": "840",
                        "alpha2": "US",
                        "alpha3": "USA"
                      },
                      "mcc": "5411",
                      "merchant": {
                        "name": "Grocery Store Inc",
                        "city": "New York",
                        "country": {
                          "name": "United States",
                          "numeric": "840",
                          "alpha2": "US",
                          "alpha3": "USA"
                        }
                      },
                      "billingAmount": "5000",
                      "billingCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionAmount": "5000",
                      "transactionCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionType": "purchase",
                      "cardToken": "card_token_abc123",
                      "impactsCashback": true,
                      "status": "Approved",
                      "transactions": [
                        {
                          "status": "ExecSuccess",
                          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                          "value": "5000000000000000000",
                          "data": "0x",
                          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                        }
                      ]
                    }
                  },
                  "description": "Card transaction event"
                },
                "safeWallets": {
                  "type": "array",
                  "description": "User's Safe wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "nullable": true,
                        "description": "Blockchain chain ID"
                      },
                      "tokenSymbol": {
                        "type": "string",
                        "nullable": true,
                        "description": "Token symbol"
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Creation timestamp"
                      }
                    },
                    "required": [
                      "address",
                      "createdAt"
                    ]
                  }
                }
              },
              "required": [
                "userId",
                "signInWallets",
                "event",
                "safeWallets"
              ]
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a new card transaction is created.",
          "example": {
            "eventType": "card.transaction.created",
            "data": {
              "userId": "user_123",
              "signInWallets": [
                {
                  "address": "0x1234567890123456789012345678901234567890"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100",
                  "tokenSymbol": "EURe",
                  "createdAt": "2024-01-15T10:00:00.000Z"
                }
              ],
              "event": {
                "kind": "Payment",
                "threadId": "thread_123456789",
                "createdAt": "2024-01-15T10:30:00.000Z",
                "clearedAt": "2024-01-15T10:35:00.000Z",
                "isPending": false,
                "country": {
                  "name": "United States",
                  "numeric": "840",
                  "alpha2": "US",
                  "alpha3": "USA"
                },
                "mcc": "5411",
                "merchant": {
                  "name": "Grocery Store Inc",
                  "city": "New York",
                  "country": {
                    "name": "United States",
                    "numeric": "840",
                    "alpha2": "US",
                    "alpha3": "USA"
                  }
                },
                "billingAmount": "5000",
                "billingCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionAmount": "5000",
                "transactionCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionType": "purchase",
                "cardToken": "card_token_abc123",
                "impactsCashback": true,
                "status": "Approved",
                "transactions": [
                  {
                    "status": "ExecSuccess",
                    "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                    "value": "5000000000000000000",
                    "data": "0x",
                    "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "card.transaction.created",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100",
        "tokenSymbol": "EURe",
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "event": {
      "kind": "Payment",
      "threadId": "thread_123456789",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clearedAt": "2024-01-15T10:35:00.000Z",
      "isPending": false,
      "country": {
        "name": "United States",
        "numeric": "840",
        "alpha2": "US",
        "alpha3": "USA"
      },
      "mcc": "5411",
      "merchant": {
        "name": "Grocery Store Inc",
        "city": "New York",
        "country": {
          "name": "United States",
          "numeric": "840",
          "alpha2": "US",
          "alpha3": "USA"
        }
      },
      "billingAmount": "5000",
      "billingCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionAmount": "5000",
      "transactionCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionType": "purchase",
      "cardToken": "card_token_abc123",
      "impactsCashback": true,
      "status": "Approved",
      "transactions": [
        {
          "status": "ExecSuccess",
          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
          "value": "5000000000000000000",
          "data": "0x",
          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        }
      ]
    }
  }
}
```

### card.transaction.confirmed

Triggered when a blockchain transaction is confirmed.

**Event Type**: `card.transaction.confirmed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "card.transaction.confirmed";
    data: {
      /** User ID */
      userId: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Sign-in wallet address */
        address: string;
      }[];
      /** User's Safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string | null;
        /** Token symbol */
        tokenSymbol: string | null;
        /** Creation timestamp */
        createdAt: string;
      }[];
      /** Card transaction event */
      event: {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Payment";
        status: "Approved" | "IncorrectPin" | "InsufficientFunds" | "ExceedsApprovalAmountLimit" | "InvalidAmount" | "PinEntryTriesExceeded" | "IncorrectSecurityCode" | "Reversal" | "PartialReversal" | "Other";
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Refund";
        refundAmount: string;
        refundCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Reversal";
        reversalAmount: string;
        reversalCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      };
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "card.transaction.confirmed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when the transaction hash becomes available after broadcast."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "card.transaction.confirmed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "signInWallets": {
                  "type": "array",
                  "description": "User's sign-in wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Sign-in wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  }
                },
                "event": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Payment"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "Approved",
                            "IncorrectPin",
                            "InsufficientFunds",
                            "ExceedsApprovalAmountLimit",
                            "InvalidAmount",
                            "PinEntryTriesExceeded",
                            "IncorrectSecurityCode",
                            "Reversal",
                            "PartialReversal",
                            "Other"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "status"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Refund"
                          ]
                        },
                        "refundAmount": {
                          "type": "string"
                        },
                        "refundCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "refundAmount",
                        "refundCurrency"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Reversal"
                          ]
                        },
                        "reversalAmount": {
                          "type": "string"
                        },
                        "reversalCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "reversalAmount",
                        "reversalCurrency"
                      ]
                    }
                  ],
                  "example": {
                    "event": {
                      "kind": "Payment",
                      "threadId": "thread_123456789",
                      "createdAt": "2024-01-15T10:30:00.000Z",
                      "clearedAt": "2024-01-15T10:35:00.000Z",
                      "isPending": false,
                      "country": {
                        "name": "United States",
                        "numeric": "840",
                        "alpha2": "US",
                        "alpha3": "USA"
                      },
                      "mcc": "5411",
                      "merchant": {
                        "name": "Grocery Store Inc",
                        "city": "New York",
                        "country": {
                          "name": "United States",
                          "numeric": "840",
                          "alpha2": "US",
                          "alpha3": "USA"
                        }
                      },
                      "billingAmount": "5000",
                      "billingCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionAmount": "5000",
                      "transactionCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionType": "purchase",
                      "cardToken": "card_token_abc123",
                      "impactsCashback": true,
                      "status": "Approved",
                      "transactions": [
                        {
                          "status": "ExecSuccess",
                          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                          "value": "5000000000000000000",
                          "data": "0x",
                          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                        }
                      ]
                    }
                  },
                  "description": "Card transaction event"
                },
                "safeWallets": {
                  "type": "array",
                  "description": "User's Safe wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "nullable": true,
                        "description": "Blockchain chain ID"
                      },
                      "tokenSymbol": {
                        "type": "string",
                        "nullable": true,
                        "description": "Token symbol"
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Creation timestamp"
                      }
                    },
                    "required": [
                      "address",
                      "createdAt"
                    ]
                  }
                }
              },
              "required": [
                "userId",
                "signInWallets",
                "event",
                "safeWallets"
              ]
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when the transaction hash becomes available after broadcast.",
          "example": {
            "eventType": "card.transaction.confirmed",
            "data": {
              "userId": "user_123",
              "signInWallets": [
                {
                  "address": "0x1234567890123456789012345678901234567890"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100",
                  "tokenSymbol": "EURe",
                  "createdAt": "2024-01-15T10:00:00.000Z"
                }
              ],
              "event": {
                "kind": "Payment",
                "threadId": "thread_123456789",
                "createdAt": "2024-01-15T10:30:00.000Z",
                "clearedAt": "2024-01-15T10:35:00.000Z",
                "isPending": false,
                "country": {
                  "name": "United States",
                  "numeric": "840",
                  "alpha2": "US",
                  "alpha3": "USA"
                },
                "mcc": "5411",
                "merchant": {
                  "name": "Grocery Store Inc",
                  "city": "New York",
                  "country": {
                    "name": "United States",
                    "numeric": "840",
                    "alpha2": "US",
                    "alpha3": "USA"
                  }
                },
                "billingAmount": "5000",
                "billingCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionAmount": "5000",
                "transactionCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionType": "purchase",
                "cardToken": "card_token_abc123",
                "impactsCashback": true,
                "status": "Approved",
                "transactions": [
                  {
                    "status": "ExecSuccess",
                    "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                    "value": "5000000000000000000",
                    "data": "0x",
                    "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "card.transaction.confirmed",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100",
        "tokenSymbol": "EURe",
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "event": {
      "kind": "Payment",
      "threadId": "thread_123456789",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clearedAt": "2024-01-15T10:35:00.000Z",
      "isPending": false,
      "country": {
        "name": "United States",
        "numeric": "840",
        "alpha2": "US",
        "alpha3": "USA"
      },
      "mcc": "5411",
      "merchant": {
        "name": "Grocery Store Inc",
        "city": "New York",
        "country": {
          "name": "United States",
          "numeric": "840",
          "alpha2": "US",
          "alpha3": "USA"
        }
      },
      "billingAmount": "5000",
      "billingCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionAmount": "5000",
      "transactionCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionType": "purchase",
      "cardToken": "card_token_abc123",
      "impactsCashback": true,
      "status": "Approved",
      "transactions": [
        {
          "status": "ExecSuccess",
          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
          "value": "5000000000000000000",
          "data": "0x",
          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        }
      ]
    }
  }
}
```

### card.transaction.failed

Triggered when a blockchain transaction fails.

**Event Type**: `card.transaction.failed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "card.transaction.failed";
    data: {
      /** User ID */
      userId: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Sign-in wallet address */
        address: string;
      }[];
      /** User's Safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string | null;
        /** Token symbol */
        tokenSymbol: string | null;
        /** Creation timestamp */
        createdAt: string;
      }[];
      /** Card transaction event */
      event: {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Payment";
        status: "Approved" | "IncorrectPin" | "InsufficientFunds" | "ExceedsApprovalAmountLimit" | "InvalidAmount" | "PinEntryTriesExceeded" | "IncorrectSecurityCode" | "Reversal" | "PartialReversal" | "Other";
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Refund";
        refundAmount: string;
        refundCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Reversal";
        reversalAmount: string;
        reversalCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      };
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "card.transaction.failed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when the transaction hash becomes available after broadcast."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "card.transaction.failed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "signInWallets": {
                  "type": "array",
                  "description": "User's sign-in wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Sign-in wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  }
                },
                "event": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Payment"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "Approved",
                            "IncorrectPin",
                            "InsufficientFunds",
                            "ExceedsApprovalAmountLimit",
                            "InvalidAmount",
                            "PinEntryTriesExceeded",
                            "IncorrectSecurityCode",
                            "Reversal",
                            "PartialReversal",
                            "Other"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "status"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Refund"
                          ]
                        },
                        "refundAmount": {
                          "type": "string"
                        },
                        "refundCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "refundAmount",
                        "refundCurrency"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Reversal"
                          ]
                        },
                        "reversalAmount": {
                          "type": "string"
                        },
                        "reversalCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "reversalAmount",
                        "reversalCurrency"
                      ]
                    }
                  ],
                  "example": {
                    "event": {
                      "kind": "Payment",
                      "threadId": "thread_123456789",
                      "createdAt": "2024-01-15T10:30:00.000Z",
                      "clearedAt": "2024-01-15T10:35:00.000Z",
                      "isPending": false,
                      "country": {
                        "name": "United States",
                        "numeric": "840",
                        "alpha2": "US",
                        "alpha3": "USA"
                      },
                      "mcc": "5411",
                      "merchant": {
                        "name": "Grocery Store Inc",
                        "city": "New York",
                        "country": {
                          "name": "United States",
                          "numeric": "840",
                          "alpha2": "US",
                          "alpha3": "USA"
                        }
                      },
                      "billingAmount": "5000",
                      "billingCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionAmount": "5000",
                      "transactionCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionType": "purchase",
                      "cardToken": "card_token_abc123",
                      "impactsCashback": true,
                      "status": "Approved",
                      "transactions": [
                        {
                          "status": "ExecSuccess",
                          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                          "value": "5000000000000000000",
                          "data": "0x",
                          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                        }
                      ]
                    }
                  },
                  "description": "Card transaction event"
                },
                "safeWallets": {
                  "type": "array",
                  "description": "User's Safe wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "nullable": true,
                        "description": "Blockchain chain ID"
                      },
                      "tokenSymbol": {
                        "type": "string",
                        "nullable": true,
                        "description": "Token symbol"
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Creation timestamp"
                      }
                    },
                    "required": [
                      "address",
                      "createdAt"
                    ]
                  }
                }
              },
              "required": [
                "userId",
                "signInWallets",
                "event",
                "safeWallets"
              ]
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when the transaction hash becomes available after broadcast.",
          "example": {
            "eventType": "card.transaction.failed",
            "data": {
              "userId": "user_123",
              "signInWallets": [
                {
                  "address": "0x1234567890123456789012345678901234567890"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100",
                  "tokenSymbol": "EURe",
                  "createdAt": "2024-01-15T10:00:00.000Z"
                }
              ],
              "event": {
                "kind": "Payment",
                "threadId": "thread_123456789",
                "createdAt": "2024-01-15T10:30:00.000Z",
                "clearedAt": "2024-01-15T10:35:00.000Z",
                "isPending": false,
                "country": {
                  "name": "United States",
                  "numeric": "840",
                  "alpha2": "US",
                  "alpha3": "USA"
                },
                "mcc": "5411",
                "merchant": {
                  "name": "Grocery Store Inc",
                  "city": "New York",
                  "country": {
                    "name": "United States",
                    "numeric": "840",
                    "alpha2": "US",
                    "alpha3": "USA"
                  }
                },
                "billingAmount": "5000",
                "billingCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionAmount": "5000",
                "transactionCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionType": "purchase",
                "cardToken": "card_token_abc123",
                "impactsCashback": true,
                "status": "Approved",
                "transactions": [
                  {
                    "status": "ExecSuccess",
                    "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                    "value": "5000000000000000000",
                    "data": "0x",
                    "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "card.transaction.failed",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100",
        "tokenSymbol": "EURe",
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "event": {
      "kind": "Payment",
      "threadId": "thread_123456789",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clearedAt": "2024-01-15T10:35:00.000Z",
      "isPending": false,
      "country": {
        "name": "United States",
        "numeric": "840",
        "alpha2": "US",
        "alpha3": "USA"
      },
      "mcc": "5411",
      "merchant": {
        "name": "Grocery Store Inc",
        "city": "New York",
        "country": {
          "name": "United States",
          "numeric": "840",
          "alpha2": "US",
          "alpha3": "USA"
        }
      },
      "billingAmount": "5000",
      "billingCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionAmount": "5000",
      "transactionCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionType": "purchase",
      "cardToken": "card_token_abc123",
      "impactsCashback": true,
      "status": "Approved",
      "transactions": [
        {
          "status": "ExecSuccess",
          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
          "value": "5000000000000000000",
          "data": "0x",
          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        }
      ]
    }
  }
}
```

### card.transaction.reversed

Triggered when a reversal event is detected during clearing.

**Event Type**: `card.transaction.reversed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "card.transaction.reversed";
    data: {
      /** User ID */
      userId: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Sign-in wallet address */
        address: string;
      }[];
      /** User's Safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string | null;
        /** Token symbol */
        tokenSymbol: string | null;
        /** Creation timestamp */
        createdAt: string;
      }[];
      /** Card transaction event */
      event: {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Payment";
        status: "Approved" | "IncorrectPin" | "InsufficientFunds" | "ExceedsApprovalAmountLimit" | "InvalidAmount" | "PinEntryTriesExceeded" | "IncorrectSecurityCode" | "Reversal" | "PartialReversal" | "Other";
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Refund";
        refundAmount: string;
        refundCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Reversal";
        reversalAmount: string;
        reversalCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      };
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "card.transaction.reversed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when the transaction hash becomes available after broadcast."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "card.transaction.reversed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "signInWallets": {
                  "type": "array",
                  "description": "User's sign-in wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Sign-in wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  }
                },
                "event": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Payment"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "Approved",
                            "IncorrectPin",
                            "InsufficientFunds",
                            "ExceedsApprovalAmountLimit",
                            "InvalidAmount",
                            "PinEntryTriesExceeded",
                            "IncorrectSecurityCode",
                            "Reversal",
                            "PartialReversal",
                            "Other"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "status"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Refund"
                          ]
                        },
                        "refundAmount": {
                          "type": "string"
                        },
                        "refundCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "refundAmount",
                        "refundCurrency"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Reversal"
                          ]
                        },
                        "reversalAmount": {
                          "type": "string"
                        },
                        "reversalCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "reversalAmount",
                        "reversalCurrency"
                      ]
                    }
                  ],
                  "example": {
                    "event": {
                      "kind": "Payment",
                      "threadId": "thread_123456789",
                      "createdAt": "2024-01-15T10:30:00.000Z",
                      "clearedAt": "2024-01-15T10:35:00.000Z",
                      "isPending": false,
                      "country": {
                        "name": "United States",
                        "numeric": "840",
                        "alpha2": "US",
                        "alpha3": "USA"
                      },
                      "mcc": "5411",
                      "merchant": {
                        "name": "Grocery Store Inc",
                        "city": "New York",
                        "country": {
                          "name": "United States",
                          "numeric": "840",
                          "alpha2": "US",
                          "alpha3": "USA"
                        }
                      },
                      "billingAmount": "5000",
                      "billingCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionAmount": "5000",
                      "transactionCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionType": "purchase",
                      "cardToken": "card_token_abc123",
                      "impactsCashback": true,
                      "status": "Approved",
                      "transactions": [
                        {
                          "status": "ExecSuccess",
                          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                          "value": "5000000000000000000",
                          "data": "0x",
                          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                        }
                      ]
                    }
                  },
                  "description": "Card transaction event"
                },
                "safeWallets": {
                  "type": "array",
                  "description": "User's Safe wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "nullable": true,
                        "description": "Blockchain chain ID"
                      },
                      "tokenSymbol": {
                        "type": "string",
                        "nullable": true,
                        "description": "Token symbol"
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Creation timestamp"
                      }
                    },
                    "required": [
                      "address",
                      "createdAt"
                    ]
                  }
                }
              },
              "required": [
                "userId",
                "signInWallets",
                "event",
                "safeWallets"
              ]
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when the transaction hash becomes available after broadcast.",
          "example": {
            "eventType": "card.transaction.reversed",
            "data": {
              "userId": "user_123",
              "signInWallets": [
                {
                  "address": "0x1234567890123456789012345678901234567890"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100",
                  "tokenSymbol": "EURe",
                  "createdAt": "2024-01-15T10:00:00.000Z"
                }
              ],
              "event": {
                "kind": "Payment",
                "threadId": "thread_123456789",
                "createdAt": "2024-01-15T10:30:00.000Z",
                "clearedAt": "2024-01-15T10:35:00.000Z",
                "isPending": false,
                "country": {
                  "name": "United States",
                  "numeric": "840",
                  "alpha2": "US",
                  "alpha3": "USA"
                },
                "mcc": "5411",
                "merchant": {
                  "name": "Grocery Store Inc",
                  "city": "New York",
                  "country": {
                    "name": "United States",
                    "numeric": "840",
                    "alpha2": "US",
                    "alpha3": "USA"
                  }
                },
                "billingAmount": "5000",
                "billingCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionAmount": "5000",
                "transactionCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionType": "purchase",
                "cardToken": "card_token_abc123",
                "impactsCashback": true,
                "status": "Approved",
                "transactions": [
                  {
                    "status": "ExecSuccess",
                    "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                    "value": "5000000000000000000",
                    "data": "0x",
                    "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "card.transaction.reversed",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100",
        "tokenSymbol": "EURe",
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "event": {
      "kind": "Payment",
      "threadId": "thread_123456789",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clearedAt": "2024-01-15T10:35:00.000Z",
      "isPending": false,
      "country": {
        "name": "United States",
        "numeric": "840",
        "alpha2": "US",
        "alpha3": "USA"
      },
      "mcc": "5411",
      "merchant": {
        "name": "Grocery Store Inc",
        "city": "New York",
        "country": {
          "name": "United States",
          "numeric": "840",
          "alpha2": "US",
          "alpha3": "USA"
        }
      },
      "billingAmount": "5000",
      "billingCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionAmount": "5000",
      "transactionCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionType": "purchase",
      "cardToken": "card_token_abc123",
      "impactsCashback": true,
      "status": "Approved",
      "transactions": [
        {
          "status": "ExecSuccess",
          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
          "value": "5000000000000000000",
          "data": "0x",
          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        }
      ]
    }
  }
}
```

### card.transaction.refunded

Triggered when a refund event is detected during clearing.

**Event Type**: `card.transaction.refunded`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "card.transaction.refunded";
    data: {
      /** User ID */
      userId: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Sign-in wallet address */
        address: string;
      }[];
      /** User's Safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string | null;
        /** Token symbol */
        tokenSymbol: string | null;
        /** Creation timestamp */
        createdAt: string;
      }[];
      /** Card transaction event */
      event: {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Payment";
        status: "Approved" | "IncorrectPin" | "InsufficientFunds" | "ExceedsApprovalAmountLimit" | "InvalidAmount" | "PinEntryTriesExceeded" | "IncorrectSecurityCode" | "Reversal" | "PartialReversal" | "Other";
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Refund";
        refundAmount: string;
        refundCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Reversal";
        reversalAmount: string;
        reversalCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      };
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "card.transaction.refunded Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when the transaction hash becomes available after broadcast."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "card.transaction.refunded"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "signInWallets": {
                  "type": "array",
                  "description": "User's sign-in wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Sign-in wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  }
                },
                "event": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Payment"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "Approved",
                            "IncorrectPin",
                            "InsufficientFunds",
                            "ExceedsApprovalAmountLimit",
                            "InvalidAmount",
                            "PinEntryTriesExceeded",
                            "IncorrectSecurityCode",
                            "Reversal",
                            "PartialReversal",
                            "Other"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "status"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Refund"
                          ]
                        },
                        "refundAmount": {
                          "type": "string"
                        },
                        "refundCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "refundAmount",
                        "refundCurrency"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Reversal"
                          ]
                        },
                        "reversalAmount": {
                          "type": "string"
                        },
                        "reversalCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "reversalAmount",
                        "reversalCurrency"
                      ]
                    }
                  ],
                  "example": {
                    "event": {
                      "kind": "Payment",
                      "threadId": "thread_123456789",
                      "createdAt": "2024-01-15T10:30:00.000Z",
                      "clearedAt": "2024-01-15T10:35:00.000Z",
                      "isPending": false,
                      "country": {
                        "name": "United States",
                        "numeric": "840",
                        "alpha2": "US",
                        "alpha3": "USA"
                      },
                      "mcc": "5411",
                      "merchant": {
                        "name": "Grocery Store Inc",
                        "city": "New York",
                        "country": {
                          "name": "United States",
                          "numeric": "840",
                          "alpha2": "US",
                          "alpha3": "USA"
                        }
                      },
                      "billingAmount": "5000",
                      "billingCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionAmount": "5000",
                      "transactionCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionType": "purchase",
                      "cardToken": "card_token_abc123",
                      "impactsCashback": true,
                      "status": "Approved",
                      "transactions": [
                        {
                          "status": "ExecSuccess",
                          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                          "value": "5000000000000000000",
                          "data": "0x",
                          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                        }
                      ]
                    }
                  },
                  "description": "Card transaction event"
                },
                "safeWallets": {
                  "type": "array",
                  "description": "User's Safe wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "nullable": true,
                        "description": "Blockchain chain ID"
                      },
                      "tokenSymbol": {
                        "type": "string",
                        "nullable": true,
                        "description": "Token symbol"
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Creation timestamp"
                      }
                    },
                    "required": [
                      "address",
                      "createdAt"
                    ]
                  }
                }
              },
              "required": [
                "userId",
                "signInWallets",
                "event",
                "safeWallets"
              ]
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when the transaction hash becomes available after broadcast.",
          "example": {
            "eventType": "card.transaction.refunded",
            "data": {
              "userId": "user_123",
              "signInWallets": [
                {
                  "address": "0x1234567890123456789012345678901234567890"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100",
                  "tokenSymbol": "EURe",
                  "createdAt": "2024-01-15T10:00:00.000Z"
                }
              ],
              "event": {
                "kind": "Payment",
                "threadId": "thread_123456789",
                "createdAt": "2024-01-15T10:30:00.000Z",
                "clearedAt": "2024-01-15T10:35:00.000Z",
                "isPending": false,
                "country": {
                  "name": "United States",
                  "numeric": "840",
                  "alpha2": "US",
                  "alpha3": "USA"
                },
                "mcc": "5411",
                "merchant": {
                  "name": "Grocery Store Inc",
                  "city": "New York",
                  "country": {
                    "name": "United States",
                    "numeric": "840",
                    "alpha2": "US",
                    "alpha3": "USA"
                  }
                },
                "billingAmount": "5000",
                "billingCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionAmount": "5000",
                "transactionCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionType": "purchase",
                "cardToken": "card_token_abc123",
                "impactsCashback": true,
                "status": "Approved",
                "transactions": [
                  {
                    "status": "ExecSuccess",
                    "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                    "value": "5000000000000000000",
                    "data": "0x",
                    "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "card.transaction.refunded",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100",
        "tokenSymbol": "EURe",
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "event": {
      "kind": "Payment",
      "threadId": "thread_123456789",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clearedAt": "2024-01-15T10:35:00.000Z",
      "isPending": false,
      "country": {
        "name": "United States",
        "numeric": "840",
        "alpha2": "US",
        "alpha3": "USA"
      },
      "mcc": "5411",
      "merchant": {
        "name": "Grocery Store Inc",
        "city": "New York",
        "country": {
          "name": "United States",
          "numeric": "840",
          "alpha2": "US",
          "alpha3": "USA"
        }
      },
      "billingAmount": "5000",
      "billingCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionAmount": "5000",
      "transactionCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionType": "purchase",
      "cardToken": "card_token_abc123",
      "impactsCashback": true,
      "status": "Approved",
      "transactions": [
        {
          "status": "ExecSuccess",
          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
          "value": "5000000000000000000",
          "data": "0x",
          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        }
      ]
    }
  }
}
```

### card.transaction.declined

Triggered when an authorization record is created with a declined response.

**Event Type**: `card.transaction.declined`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "card.transaction.declined";
    data: {
      /** User ID */
      userId: string;
      /** User's sign-in wallet addresses */
      signInWallets: {
        /** Sign-in wallet address */
        address: string;
      }[];
      /** User's Safe wallet addresses */
      safeWallets: {
        /** Safe wallet address */
        address: string;
        /** Blockchain chain ID */
        chainId: string | null;
        /** Token symbol */
        tokenSymbol: string | null;
        /** Creation timestamp */
        createdAt: string;
      }[];
      /** Card transaction event */
      event: {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Payment";
        status: "Approved" | "IncorrectPin" | "InsufficientFunds" | "ExceedsApprovalAmountLimit" | "InvalidAmount" | "PinEntryTriesExceeded" | "IncorrectSecurityCode" | "Reversal" | "PartialReversal" | "Other";
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Refund";
        refundAmount: string;
        refundCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      } | {
        threadId: string;
        createdAt: string;
        clearedAt: string;
        isPending: boolean;
        country: {
          name: string;
          numeric: string;
          alpha2: string;
          alpha3: string;
        };
        mcc: string;
        merchant: {
          name: string;
          city: string;
          country?: {
            name: string;
            numeric: string;
            alpha2: string;
            alpha3: string;
          };
        };
        billingAmount: string;
        billingCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionAmount: string;
        transactionCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
        transactionType: string;
        cardToken: string;
        impactsCashback: boolean | null;
        transactions: {
          status: "Unsubmitted" | "Unconfirmed" | "ExecReverted" | "ExecSuccess";
          to: string;
          value: string;
          data: string;
          hash: string | null;
        }[];
        kind: "Reversal";
        reversalAmount: string;
        reversalCurrency: {
          symbol: string;
          code: string;
          decimals: number;
          name: string;
        };
      };
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "card.transaction.declined Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when the transaction hash becomes available after broadcast."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "card.transaction.declined"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "signInWallets": {
                  "type": "array",
                  "description": "User's sign-in wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Sign-in wallet address"
                      }
                    },
                    "required": [
                      "address"
                    ]
                  }
                },
                "event": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Payment"
                          ]
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "Approved",
                            "IncorrectPin",
                            "InsufficientFunds",
                            "ExceedsApprovalAmountLimit",
                            "InvalidAmount",
                            "PinEntryTriesExceeded",
                            "IncorrectSecurityCode",
                            "Reversal",
                            "PartialReversal",
                            "Other"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "status"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Refund"
                          ]
                        },
                        "refundAmount": {
                          "type": "string"
                        },
                        "refundCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "refundAmount",
                        "refundCurrency"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "threadId": {
                          "type": "string"
                        },
                        "createdAt": {
                          "type": "string"
                        },
                        "clearedAt": {
                          "type": "string",
                          "nullable": true
                        },
                        "isPending": {
                          "type": "boolean"
                        },
                        "country": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "numeric": {
                              "type": "string"
                            },
                            "alpha2": {
                              "type": "string"
                            },
                            "alpha3": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "name",
                            "numeric",
                            "alpha2",
                            "alpha3"
                          ]
                        },
                        "mcc": {
                          "type": "string"
                        },
                        "merchant": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "city": {
                              "type": "string"
                            },
                            "country": {
                              "type": "object",
                              "properties": {
                                "name": {
                                  "type": "string"
                                },
                                "numeric": {
                                  "type": "string"
                                },
                                "alpha2": {
                                  "type": "string"
                                },
                                "alpha3": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "name",
                                "numeric",
                                "alpha2",
                                "alpha3"
                              ]
                            }
                          },
                          "required": [
                            "name",
                            "city"
                          ]
                        },
                        "billingAmount": {
                          "type": "string"
                        },
                        "billingCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionAmount": {
                          "type": "string"
                        },
                        "transactionCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        },
                        "transactionType": {
                          "type": "string"
                        },
                        "cardToken": {
                          "type": "string"
                        },
                        "impactsCashback": {
                          "type": "boolean",
                          "nullable": true
                        },
                        "transactions": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "status": {
                                "type": "string",
                                "enum": [
                                  "Unsubmitted",
                                  "Unconfirmed",
                                  "ExecReverted",
                                  "ExecSuccess"
                                ]
                              },
                              "to": {
                                "type": "string"
                              },
                              "value": {
                                "type": "string"
                              },
                              "data": {
                                "type": "string"
                              },
                              "hash": {
                                "type": "string",
                                "nullable": true
                              }
                            },
                            "required": [
                              "status",
                              "to",
                              "value",
                              "data"
                            ]
                          }
                        },
                        "kind": {
                          "type": "string",
                          "enum": [
                            "Reversal"
                          ]
                        },
                        "reversalAmount": {
                          "type": "string"
                        },
                        "reversalCurrency": {
                          "type": "object",
                          "properties": {
                            "symbol": {
                              "type": "string"
                            },
                            "code": {
                              "type": "string"
                            },
                            "decimals": {
                              "type": "number"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "symbol",
                            "code",
                            "decimals",
                            "name"
                          ]
                        }
                      },
                      "required": [
                        "threadId",
                        "createdAt",
                        "clearedAt",
                        "isPending",
                        "country",
                        "mcc",
                        "merchant",
                        "billingAmount",
                        "billingCurrency",
                        "transactionAmount",
                        "transactionCurrency",
                        "transactionType",
                        "cardToken",
                        "transactions",
                        "kind",
                        "reversalAmount",
                        "reversalCurrency"
                      ]
                    }
                  ],
                  "example": {
                    "event": {
                      "kind": "Payment",
                      "threadId": "thread_123456789",
                      "createdAt": "2024-01-15T10:30:00.000Z",
                      "clearedAt": "2024-01-15T10:35:00.000Z",
                      "isPending": false,
                      "country": {
                        "name": "United States",
                        "numeric": "840",
                        "alpha2": "US",
                        "alpha3": "USA"
                      },
                      "mcc": "5411",
                      "merchant": {
                        "name": "Grocery Store Inc",
                        "city": "New York",
                        "country": {
                          "name": "United States",
                          "numeric": "840",
                          "alpha2": "US",
                          "alpha3": "USA"
                        }
                      },
                      "billingAmount": "5000",
                      "billingCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionAmount": "5000",
                      "transactionCurrency": {
                        "symbol": "$",
                        "code": "840",
                        "decimals": 2,
                        "name": "US Dollar"
                      },
                      "transactionType": "purchase",
                      "cardToken": "card_token_abc123",
                      "impactsCashback": true,
                      "status": "Approved",
                      "transactions": [
                        {
                          "status": "ExecSuccess",
                          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                          "value": "5000000000000000000",
                          "data": "0x",
                          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                        }
                      ]
                    }
                  },
                  "description": "Card transaction event"
                },
                "safeWallets": {
                  "type": "array",
                  "description": "User's Safe wallet addresses",
                  "items": {
                    "type": "object",
                    "properties": {
                      "address": {
                        "type": "string",
                        "description": "Safe wallet address"
                      },
                      "chainId": {
                        "type": "string",
                        "nullable": true,
                        "description": "Blockchain chain ID"
                      },
                      "tokenSymbol": {
                        "type": "string",
                        "nullable": true,
                        "description": "Token symbol"
                      },
                      "createdAt": {
                        "type": "string",
                        "description": "Creation timestamp"
                      }
                    },
                    "required": [
                      "address",
                      "createdAt"
                    ]
                  }
                }
              },
              "required": [
                "userId",
                "signInWallets",
                "event",
                "safeWallets"
              ]
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when the transaction hash becomes available after broadcast.",
          "example": {
            "eventType": "card.transaction.declined",
            "data": {
              "userId": "user_123",
              "signInWallets": [
                {
                  "address": "0x1234567890123456789012345678901234567890"
                }
              ],
              "safeWallets": [
                {
                  "address": "0xabcdef1234567890abcdef1234567890abcdef12",
                  "chainId": "100",
                  "tokenSymbol": "EURe",
                  "createdAt": "2024-01-15T10:00:00.000Z"
                }
              ],
              "event": {
                "kind": "Payment",
                "threadId": "thread_123456789",
                "createdAt": "2024-01-15T10:30:00.000Z",
                "clearedAt": "2024-01-15T10:35:00.000Z",
                "isPending": false,
                "country": {
                  "name": "United States",
                  "numeric": "840",
                  "alpha2": "US",
                  "alpha3": "USA"
                },
                "mcc": "5411",
                "merchant": {
                  "name": "Grocery Store Inc",
                  "city": "New York",
                  "country": {
                    "name": "United States",
                    "numeric": "840",
                    "alpha2": "US",
                    "alpha3": "USA"
                  }
                },
                "billingAmount": "5000",
                "billingCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionAmount": "5000",
                "transactionCurrency": {
                  "symbol": "$",
                  "code": "840",
                  "decimals": 2,
                  "name": "US Dollar"
                },
                "transactionType": "purchase",
                "cardToken": "card_token_abc123",
                "impactsCashback": true,
                "status": "Approved",
                "transactions": [
                  {
                    "status": "ExecSuccess",
                    "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
                    "value": "5000000000000000000",
                    "data": "0x",
                    "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
                  }
                ]
              }
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "card.transaction.declined",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100",
        "tokenSymbol": "EURe",
        "createdAt": "2024-01-15T10:00:00.000Z"
      }
    ],
    "event": {
      "kind": "Payment",
      "threadId": "thread_123456789",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "clearedAt": "2024-01-15T10:35:00.000Z",
      "isPending": false,
      "country": {
        "name": "United States",
        "numeric": "840",
        "alpha2": "US",
        "alpha3": "USA"
      },
      "mcc": "5411",
      "merchant": {
        "name": "Grocery Store Inc",
        "city": "New York",
        "country": {
          "name": "United States",
          "numeric": "840",
          "alpha2": "US",
          "alpha3": "USA"
        }
      },
      "billingAmount": "5000",
      "billingCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionAmount": "5000",
      "transactionCurrency": {
        "symbol": "$",
        "code": "840",
        "decimals": 2,
        "name": "US Dollar"
      },
      "transactionType": "purchase",
      "cardToken": "card_token_abc123",
      "impactsCashback": true,
      "status": "Approved",
      "transactions": [
        {
          "status": "ExecSuccess",
          "to": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
          "value": "5000000000000000000",
          "data": "0x",
          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
        }
      ]
    }
  }
}
```

### physical.card.activated

Triggered when a physical card is activated.

**Event Type**: `physical.card.activated`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "physical.card.activated";
    data: {
      /** Card ID */
      id: string;
      /** Unique card token identifier */
      cardToken: string;
      /** User ID */
      userId: string;
      /** Last four digits of the card */
      lastFourDigits: string;
      /** When the card was activated (ISO 8601) */
      activatedAt: string | null;
      /** True for virtual cards, false for physical */
      virtual: boolean;
      /** Card status code from payment processor (e.g. 1000 = Active) */
      statusCode: number;
      /** Human-readable card status (e.g. Active, Frozen, Void) */
      statusName: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "physical.card.activated Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a physical card is activated."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "physical.card.activated"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Card ID"
                },
                "cardToken": {
                  "type": "string",
                  "description": "Unique card token identifier"
                },
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "lastFourDigits": {
                  "type": "string",
                  "description": "Last four digits of the card"
                },
                "activatedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "When the card was activated (ISO 8601)"
                },
                "virtual": {
                  "type": "boolean",
                  "description": "True for virtual cards, false for physical"
                },
                "statusCode": {
                  "type": "number",
                  "description": "Card status code from payment processor (e.g. 1000 = Active)"
                },
                "statusName": {
                  "type": "string",
                  "description": "Human-readable card status (e.g. Active, Frozen, Void)"
                }
              },
              "required": [
                "id",
                "cardToken",
                "userId",
                "lastFourDigits",
                "activatedAt",
                "virtual",
                "statusCode",
                "statusName"
              ],
              "description": "Card data payload for card-related webhook events.",
              "example": {
                "id": "card_abc123",
                "userId": "user_123",
                "cardToken": "card_123456789",
                "lastFourDigits": "4242",
                "activatedAt": "2024-01-15T10:30:00Z",
                "virtual": false,
                "statusCode": 1000,
                "statusName": "Active"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a physical card is activated.",
          "example": {
            "eventType": "physical.card.activated",
            "data": {
              "id": "card_abc123",
              "userId": "user_123",
              "cardToken": "card_123456789",
              "lastFourDigits": "4242",
              "activatedAt": "2024-01-15T10:30:00Z",
              "virtual": false,
              "statusCode": 1000,
              "statusName": "Active"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "physical.card.activated",
  "data": {
    "id": "card_abc123",
    "userId": "user_123",
    "cardToken": "card_123456789",
    "lastFourDigits": "4242",
    "activatedAt": "2024-01-15T10:30:00Z",
    "virtual": false,
    "statusCode": 1000,
    "statusName": "Active"
  }
}
```

### physical.card.order.status.changed

Triggered when the status of a physical card order changes.

**Event Type**: `physical.card.order.status.changed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "physical.card.order.status.changed";
    data: {
      /** User ID */
      userId: string;
      /** Card token */
      cardToken: string;
      /** Card order ID */
      cardOrderId: string;
      /** Previous order status */
      oldStatus: string;
      /** New order status */
      newStatus: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "physical.card.order.status.changed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when the status of a physical card order changes."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "physical.card.order.status.changed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "cardToken": {
                  "type": "string",
                  "description": "Card token"
                },
                "cardOrderId": {
                  "type": "string",
                  "description": "Card order ID"
                },
                "oldStatus": {
                  "type": "string",
                  "description": "Previous order status"
                },
                "newStatus": {
                  "type": "string",
                  "description": "New order status"
                }
              },
              "required": [
                "userId",
                "cardToken",
                "cardOrderId",
                "oldStatus",
                "newStatus"
              ],
              "description": "Physical card order status change data",
              "example": {
                "userId": "user_123",
                "cardToken": "card_123",
                "cardOrderId": "order_456",
                "oldStatus": "ordered",
                "newStatus": "shipped"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when the status of a physical card order changes.",
          "example": {
            "eventType": "physical.card.order.status.changed",
            "data": {
              "userId": "user_123",
              "cardToken": "card_123",
              "cardOrderId": "order_456",
              "oldStatus": "ordered",
              "newStatus": "shipped"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "physical.card.order.status.changed",
  "data": {
    "userId": "user_123",
    "cardToken": "card_123",
    "cardOrderId": "order_456",
    "oldStatus": "ordered",
    "newStatus": "shipped"
  }
}
```

### physical.card.ordered

Triggered when a physical card is ordered.

**Event Type**: `physical.card.ordered`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "physical.card.ordered";
    data: {
      /** User ID */
      userId: string;
      /** Card token */
      cardToken: string;
      /** Card order ID */
      id: string;
      /** Order status */
      status: string;
      /** Name to emboss on card */
      embossedName: string;
      /** Primary address */
      address1: string;
      /** Secondary address */
      address2: string;
      /** City */
      city: string;
      /** Postal code */
      postalCode: string;
      /** State */
      state: string;
      /** Country */
      country: string;
      /** Phone number */
      phone: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "physical.card.ordered Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a physical card is ordered."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "physical.card.ordered"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "cardToken": {
                  "type": "string",
                  "description": "Card token"
                },
                "id": {
                  "type": "string",
                  "description": "Card order ID"
                },
                "status": {
                  "type": "string",
                  "description": "Order status"
                },
                "embossedName": {
                  "type": "string",
                  "description": "Name to emboss on card"
                },
                "address1": {
                  "type": "string",
                  "nullable": true,
                  "description": "Primary address"
                },
                "address2": {
                  "type": "string",
                  "nullable": true,
                  "description": "Secondary address"
                },
                "city": {
                  "type": "string",
                  "nullable": true,
                  "description": "City"
                },
                "postalCode": {
                  "type": "string",
                  "nullable": true,
                  "description": "Postal code"
                },
                "state": {
                  "type": "string",
                  "nullable": true,
                  "description": "State"
                },
                "country": {
                  "type": "string",
                  "nullable": true,
                  "description": "Country"
                },
                "phone": {
                  "type": "string",
                  "nullable": true,
                  "description": "Phone number"
                }
              },
              "required": [
                "userId",
                "cardToken",
                "id",
                "status",
                "embossedName",
                "address1",
                "address2",
                "city",
                "postalCode",
                "state",
                "country",
                "phone"
              ],
              "description": "Physical card order data",
              "example": {
                "userId": "user_123",
                "cardToken": "card_123",
                "id": "order_456",
                "status": "ordered",
                "embossedName": "John Doe",
                "address1": "123 Main Street",
                "address2": "Apt 4B",
                "city": "New York",
                "postalCode": "10001",
                "state": "NY",
                "country": "US",
                "phone": "+1234567890"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a physical card is ordered.",
          "example": {
            "eventType": "physical.card.ordered",
            "data": {
              "userId": "user_123",
              "cardToken": "card_123",
              "id": "order_456",
              "status": "ordered",
              "embossedName": "John Doe",
              "address1": "123 Main Street",
              "address2": "Apt 4B",
              "city": "New York",
              "postalCode": "10001",
              "state": "NY",
              "country": "US",
              "phone": "+1234567890"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "physical.card.ordered",
  "data": {
    "userId": "user_123",
    "cardToken": "card_123",
    "id": "order_456",
    "status": "ordered",
    "embossedName": "John Doe",
    "address1": "123 Main Street",
    "address2": "Apt 4B",
    "city": "New York",
    "postalCode": "10001",
    "state": "NY",
    "country": "US",
    "phone": "+1234567890"
  }
}
```

### physical.card.pin.changed

Triggered when a physical card's PIN is changed.

**Event Type**: `physical.card.pin.changed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "physical.card.pin.changed";
    data: {
      /** User ID */
      userId: string;
      /** Unique card token identifier */
      cardToken: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "physical.card.pin.changed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a physical card's PIN is changed."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "physical.card.pin.changed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "cardToken": {
                  "type": "string",
                  "description": "Unique card token identifier"
                }
              },
              "required": [
                "userId",
                "cardToken"
              ],
              "description": "Card token data",
              "example": {
                "userId": "user_123",
                "cardToken": "card_123456789"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a physical card's PIN is changed.",
          "example": {
            "eventType": "physical.card.pin.changed",
            "data": {
              "userId": "user_123",
              "cardToken": "card_123456789"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "physical.card.pin.changed",
  "data": {
    "userId": "user_123",
    "cardToken": "card_123456789"
  }
}
```

### virtual.card.issued

Triggered when a virtual card is issued.

**Event Type**: `virtual.card.issued`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "virtual.card.issued";
    data: {
      /** Card ID */
      id: string;
      /** Unique card token identifier */
      cardToken: string;
      /** User ID */
      userId: string;
      /** Last four digits of the card */
      lastFourDigits: string;
      /** When the card was activated (ISO 8601) */
      activatedAt: string | null;
      /** True for virtual cards, false for physical */
      virtual: boolean;
      /** Card status code from payment processor (e.g. 1000 = Active) */
      statusCode: number;
      /** Human-readable card status (e.g. Active, Frozen, Void) */
      statusName: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "virtual.card.issued Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a virtual card is issued."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "virtual.card.issued"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Card ID"
                },
                "cardToken": {
                  "type": "string",
                  "description": "Unique card token identifier"
                },
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "lastFourDigits": {
                  "type": "string",
                  "description": "Last four digits of the card"
                },
                "activatedAt": {
                  "type": "string",
                  "format": "date-time",
                  "nullable": true,
                  "description": "When the card was activated (ISO 8601)"
                },
                "virtual": {
                  "type": "boolean",
                  "description": "True for virtual cards, false for physical"
                },
                "statusCode": {
                  "type": "number",
                  "description": "Card status code from payment processor (e.g. 1000 = Active)"
                },
                "statusName": {
                  "type": "string",
                  "description": "Human-readable card status (e.g. Active, Frozen, Void)"
                }
              },
              "required": [
                "id",
                "cardToken",
                "userId",
                "lastFourDigits",
                "activatedAt",
                "virtual",
                "statusCode",
                "statusName"
              ],
              "description": "Card data payload for card-related webhook events.",
              "example": {
                "id": "card_abc123",
                "userId": "user_123",
                "cardToken": "card_123456789",
                "lastFourDigits": "4242",
                "activatedAt": "2024-01-15T10:30:00Z",
                "virtual": true,
                "statusCode": 1000,
                "statusName": "Active"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a virtual card is issued.",
          "example": {
            "eventType": "virtual.card.issued",
            "data": {
              "id": "card_abc123",
              "userId": "user_123",
              "cardToken": "card_123456789",
              "lastFourDigits": "4242",
              "activatedAt": "2024-01-15T10:30:00Z",
              "virtual": true,
              "statusCode": 1000,
              "statusName": "Active"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "virtual.card.issued",
  "data": {
    "id": "card_abc123",
    "userId": "user_123",
    "cardToken": "card_123456789",
    "lastFourDigits": "4242",
    "activatedAt": "2024-01-15T10:30:00Z",
    "virtual": true,
    "statusCode": 1000,
    "statusName": "Active"
  }
}
```

## Account Events

### account.balance.changed

Triggered when an account's balance changes.

**Event Type**: `account.balance.changed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "account.balance.changed";
    data: {
      /** User ID */
      userId: string;
      /** Total balance in wei */
      total: number;
      /** Spendable balance in wei */
      spendable: number;
      /** Pending balance in wei */
      pending: number;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "account.balance.changed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when an account's balance changes."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "account.balance.changed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "total": {
                  "type": "number",
                  "description": "Total balance in wei"
                },
                "spendable": {
                  "type": "number",
                  "description": "Spendable balance in wei"
                },
                "pending": {
                  "type": "number",
                  "description": "Pending balance in wei"
                }
              },
              "required": [
                "userId",
                "total",
                "spendable",
                "pending"
              ],
              "description": "Account balance change data",
              "example": {
                "userId": "user_123",
                "total": 1000000000000000000,
                "spendable": 800000000000000000,
                "pending": 200000000000000000
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when an account's balance changes.",
          "example": {
            "eventType": "account.balance.changed",
            "data": {
              "userId": "user_123",
              "total": 1000000000000000000,
              "spendable": 800000000000000000,
              "pending": 200000000000000000
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "account.balance.changed",
  "data": {
    "userId": "user_123",
    "total": 1000000000000000000,
    "spendable": 800000000000000000,
    "pending": 200000000000000000
  }
}
```

### account.limit.changed

Triggered when an account's limit changes.

**Event Type**: `account.limit.changed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "account.limit.changed";
    data: {
      /** User ID */
      userId: string;
      /** Previous account limit */
      oldLimit: number;
      /** New account limit */
      newLimit: number;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "account.limit.changed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when an account's limit changes."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "account.limit.changed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "oldLimit": {
                  "type": "number",
                  "description": "Previous account limit"
                },
                "newLimit": {
                  "type": "number",
                  "description": "New account limit"
                }
              },
              "required": [
                "userId",
                "oldLimit",
                "newLimit"
              ],
              "description": "Account limit change data",
              "example": {
                "userId": "user_123",
                "oldLimit": 1000,
                "newLimit": 2000
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when an account's limit changes.",
          "example": {
            "eventType": "account.limit.changed",
            "data": {
              "userId": "user_123",
              "oldLimit": 1000,
              "newLimit": 2000
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "account.limit.changed",
  "data": {
    "userId": "user_123",
    "oldLimit": 1000,
    "newLimit": 2000
  }
}
```

### account.withdrawal.completed

Triggered when an account withdrawal is completed.

**Event Type**: `account.withdrawal.completed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "account.withdrawal.completed";
    data: {
      /** Transaction ID */
      id: string;
      /** Safe address */
      safeAddress: string;
      /** Transaction data */
      transactionData: string;
      /** Enqueue task ID */
      enqueueTaskId: string;
      /** Dispatch task ID */
      dispatchTaskId: string;
      /** Ready timestamp */
      readyAt: string;
      /** Operation type for delay transaction */
      operationType: "CALL" | "DELEGATECALL";
      /** User ID */
      userId: string;
      /** Delay transaction status */
      status: "QUEUING" | "WAITING" | "EXECUTING" | "EXECUTED" | "FAILED";
      /** Creation timestamp */
      createdAt: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "account.withdrawal.completed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when an account withdrawal is completed."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "account.withdrawal.completed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Transaction ID"
                },
                "safeAddress": {
                  "type": "string",
                  "description": "Safe address"
                },
                "transactionData": {
                  "type": "string",
                  "description": "Transaction data"
                },
                "enqueueTaskId": {
                  "type": "string",
                  "description": "Enqueue task ID"
                },
                "dispatchTaskId": {
                  "type": "string",
                  "nullable": true,
                  "description": "Dispatch task ID"
                },
                "readyAt": {
                  "type": "string",
                  "nullable": true,
                  "format": "date",
                  "description": "Ready timestamp"
                },
                "operationType": {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    "CALL",
                    "DELEGATECALL"
                  ],
                  "description": "Operation type for delay transaction",
                  "example": "CALL"
                },
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "QUEUING",
                    "WAITING",
                    "EXECUTING",
                    "EXECUTED",
                    "FAILED"
                  ],
                  "description": "Delay transaction status",
                  "example": "EXECUTED"
                },
                "createdAt": {
                  "type": "string",
                  "format": "date",
                  "description": "Creation timestamp"
                }
              },
              "required": [
                "id",
                "safeAddress",
                "transactionData",
                "enqueueTaskId",
                "dispatchTaskId",
                "readyAt",
                "operationType",
                "userId",
                "status",
                "createdAt"
              ],
              "description": "Delay transaction data",
              "example": {
                "id": "tx_123",
                "safeAddress": "0x123...",
                "transactionData": "0x456...",
                "enqueueTaskId": "task_789",
                "dispatchTaskId": "task_101",
                "readyAt": "2025-10-15T08:00:24.194Z",
                "operationType": "CALL",
                "userId": "user_123",
                "status": "EXECUTED",
                "createdAt": "2025-10-15T08:00:24.194Z"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when an account withdrawal is completed.",
          "example": {
            "eventType": "account.withdrawal.completed",
            "data": {
              "id": "tx_123",
              "safeAddress": "0x123...",
              "transactionData": "0x456...",
              "enqueueTaskId": "task_789",
              "dispatchTaskId": "task_101",
              "readyAt": "2025-10-15T08:00:24.194Z",
              "operationType": "CALL",
              "userId": "user_123",
              "status": "EXECUTED",
              "createdAt": "2025-10-15T08:00:24.194Z"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "account.withdrawal.completed",
  "data": {
    "id": "tx_123",
    "safeAddress": "0x123...",
    "transactionData": "0x456...",
    "enqueueTaskId": "task_789",
    "dispatchTaskId": "task_101",
    "readyAt": "2025-10-15T08:00:24.194Z",
    "operationType": "CALL",
    "userId": "user_123",
    "status": "EXECUTED",
    "createdAt": "2025-10-15T08:00:24.194Z"
  }
}
```

### account.withdrawal.failed

Triggered when an account withdrawal fails.

**Event Type**: `account.withdrawal.failed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "account.withdrawal.failed";
    data: {
      /** User ID */
      userId: string;
      /** Error message */
      error: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "account.withdrawal.failed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when an account withdrawal fails."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "account.withdrawal.failed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "error": {
                  "type": "string",
                  "description": "Error message"
                }
              },
              "required": [
                "userId",
                "error"
              ],
              "description": "Error data",
              "example": {
                "userId": "user_123",
                "error": "Transaction failed"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when an account withdrawal fails.",
          "example": {
            "eventType": "account.withdrawal.failed",
            "data": {
              "userId": "user_123",
              "error": "Transaction failed"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "account.withdrawal.failed",
  "data": {
    "userId": "user_123",
    "error": "Transaction failed"
  }
}
```

## Banking Events

### iban.created

Triggered when an IBAN is created for a user.

**Event Type**: `iban.created`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "iban.created";
    data: {
      /** User ID */
      userId: string;
      /** International Bank Account Number */
      iban: string;
      /** Bank Identifier Code */
      bic: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "iban.created Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when an IBAN is created for a user."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "iban.created"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "iban": {
                  "type": "string",
                  "description": "International Bank Account Number"
                },
                "bic": {
                  "type": "string",
                  "description": "Bank Identifier Code"
                }
              },
              "required": [
                "userId",
                "iban",
                "bic"
              ],
              "description": "IBAN data",
              "example": {
                "userId": "user_123",
                "iban": "GB82WEST12345698765432",
                "bic": "WESTGB22"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when an IBAN is created for a user.",
          "example": {
            "eventType": "iban.created",
            "data": {
              "userId": "user_123",
              "iban": "GB82WEST12345698765432",
              "bic": "WESTGB22"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "iban.created",
  "data": {
    "userId": "user_123",
    "iban": "GB82WEST12345698765432",
    "bic": "WESTGB22"
  }
}
```

### iban.status.changed

Triggered when an IBAN's status changes.

**Event Type**: `iban.status.changed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "iban.status.changed";
    data: {
      /** User ID */
      userId: string;
      /** IBAN status */
      previousStatus: "NOTSTARTED" | "PENDING" | "PENDING_OAUTH" | "ASSIGNED";
      /** IBAN status */
      currentStatus: "NOTSTARTED" | "PENDING" | "PENDING_OAUTH" | "ASSIGNED";
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "iban.status.changed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when an IBAN's status changes."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "iban.status.changed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "previousStatus": {
                  "type": "string",
                  "enum": [
                    "NOTSTARTED",
                    "PENDING",
                    "PENDING_OAUTH",
                    "ASSIGNED"
                  ],
                  "description": "IBAN status",
                  "example": "ASSIGNED"
                },
                "currentStatus": {
                  "type": "string",
                  "enum": [
                    "NOTSTARTED",
                    "PENDING",
                    "PENDING_OAUTH",
                    "ASSIGNED"
                  ],
                  "description": "IBAN status",
                  "example": "ASSIGNED"
                }
              },
              "required": [
                "userId",
                "previousStatus",
                "currentStatus"
              ],
              "description": "IBAN status change data",
              "example": {
                "userId": "user_123",
                "previousStatus": "PENDING",
                "currentStatus": "ASSIGNED"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when an IBAN's status changes.",
          "example": {
            "eventType": "iban.status.changed",
            "data": {
              "userId": "user_123",
              "previousStatus": "PENDING",
              "currentStatus": "ASSIGNED"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "iban.status.changed",
  "data": {
    "userId": "user_123",
    "previousStatus": "PENDING",
    "currentStatus": "ASSIGNED"
  }
}
```

## Safe Wallet Events

### safe.created

Triggered when a Safe wallet is created.

**Event Type**: `safe.created`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "safe.created";
    data: {
      /** Safe account ID */
      id: string;
      /** Safe account address */
      address: string;
      /** Account salt */
      salt: string;
      /** Blockchain chain ID */
      chainId: string;
      /** User ID */
      userId: string;
      /** Token symbol */
      tokenSymbol: "GBPe" | "EURe" | "USDCe";
      /** Creation timestamp */
      createdAt: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "safe.created Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a Safe wallet is created."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "safe.created"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Safe account ID"
                },
                "address": {
                  "type": "string",
                  "description": "Safe account address"
                },
                "salt": {
                  "type": "string",
                  "nullable": true,
                  "description": "Account salt"
                },
                "chainId": {
                  "type": "string",
                  "nullable": true,
                  "description": "Blockchain chain ID"
                },
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "tokenSymbol": {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    "GBPe",
                    "EURe",
                    "USDCe"
                  ],
                  "description": "Token symbol",
                  "example": "EURe"
                },
                "createdAt": {
                  "type": "string",
                  "description": "Creation timestamp"
                }
              },
              "required": [
                "id",
                "address",
                "salt",
                "chainId",
                "userId",
                "tokenSymbol",
                "createdAt"
              ],
              "description": "Safe account data",
              "example": {
                "id": "safe_123",
                "address": "0x456...",
                "salt": "salt_123",
                "chainId": "100",
                "userId": "user_123",
                "tokenSymbol": "EURe",
                "createdAt": "2025-10-15T08:00:24.193Z"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a Safe wallet is created.",
          "example": {
            "eventType": "safe.created",
            "data": {
              "id": "safe_123",
              "address": "0x456...",
              "salt": "salt_123",
              "chainId": "100",
              "userId": "user_123",
              "tokenSymbol": "EURe",
              "createdAt": "2025-10-15T08:00:24.193Z"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "safe.created",
  "data": {
    "id": "safe_123",
    "address": "0x456...",
    "salt": "salt_123",
    "chainId": "100",
    "userId": "user_123",
    "tokenSymbol": "EURe",
    "createdAt": "2025-10-15T08:00:24.193Z"
  }
}
```

### safe.currency.updated

Triggered when a Safe's currency is updated.

**Event Type**: `safe.currency.updated`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "safe.currency.updated";
    data: {
      /** Safe account ID */
      id: string;
      /** Safe account address */
      address: string;
      /** Account salt */
      salt: string;
      /** Blockchain chain ID */
      chainId: string;
      /** User ID */
      userId: string;
      /** Token symbol */
      tokenSymbol: "GBPe" | "EURe" | "USDCe";
      /** Creation timestamp */
      createdAt: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "safe.currency.updated Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when a Safe's currency is updated."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "safe.currency.updated"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Safe account ID"
                },
                "address": {
                  "type": "string",
                  "description": "Safe account address"
                },
                "salt": {
                  "type": "string",
                  "nullable": true,
                  "description": "Account salt"
                },
                "chainId": {
                  "type": "string",
                  "nullable": true,
                  "description": "Blockchain chain ID"
                },
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "tokenSymbol": {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    "GBPe",
                    "EURe",
                    "USDCe"
                  ],
                  "description": "Token symbol",
                  "example": "EURe"
                },
                "createdAt": {
                  "type": "string",
                  "description": "Creation timestamp"
                }
              },
              "required": [
                "id",
                "address",
                "salt",
                "chainId",
                "userId",
                "tokenSymbol",
                "createdAt"
              ],
              "description": "Safe account data",
              "example": {
                "id": "safe_123",
                "address": "0x456...",
                "salt": "salt_123",
                "chainId": "100",
                "userId": "user_123",
                "tokenSymbol": "EURe",
                "createdAt": "2025-10-15T08:00:24.193Z"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when a Safe's currency is updated.",
          "example": {
            "eventType": "safe.currency.updated",
            "data": {
              "id": "safe_123",
              "address": "0x456...",
              "salt": "salt_123",
              "chainId": "100",
              "userId": "user_123",
              "tokenSymbol": "EURe",
              "createdAt": "2025-10-15T08:00:24.193Z"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "safe.currency.updated",
  "data": {
    "id": "safe_123",
    "address": "0x456...",
    "salt": "salt_123",
    "chainId": "100",
    "userId": "user_123",
    "tokenSymbol": "EURe",
    "createdAt": "2025-10-15T08:00:24.193Z"
  }
}
```

### safe.modules.deployed

Triggered when Safe modules are deployed.

**Event Type**: `safe.modules.deployed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "safe.modules.deployed";
    data: {
      /** Safe account ID */
      id: string;
      /** Safe account address */
      address: string;
      /** Account salt */
      salt: string;
      /** Blockchain chain ID */
      chainId: string;
      /** User ID */
      userId: string;
      /** Token symbol */
      tokenSymbol: "GBPe" | "EURe" | "USDCe";
      /** Creation timestamp */
      createdAt: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "safe.modules.deployed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when Safe modules are deployed."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "safe.modules.deployed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Safe account ID"
                },
                "address": {
                  "type": "string",
                  "description": "Safe account address"
                },
                "salt": {
                  "type": "string",
                  "nullable": true,
                  "description": "Account salt"
                },
                "chainId": {
                  "type": "string",
                  "nullable": true,
                  "description": "Blockchain chain ID"
                },
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "tokenSymbol": {
                  "type": "string",
                  "nullable": true,
                  "enum": [
                    "GBPe",
                    "EURe",
                    "USDCe"
                  ],
                  "description": "Token symbol",
                  "example": "EURe"
                },
                "createdAt": {
                  "type": "string",
                  "description": "Creation timestamp"
                }
              },
              "required": [
                "id",
                "address",
                "salt",
                "chainId",
                "userId",
                "tokenSymbol",
                "createdAt"
              ],
              "description": "Safe account data",
              "example": {
                "id": "safe_123",
                "address": "0x456...",
                "salt": "salt_123",
                "chainId": "100",
                "userId": "user_123",
                "tokenSymbol": "EURe",
                "createdAt": "2025-10-15T08:00:24.193Z"
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when Safe modules are deployed.",
          "example": {
            "eventType": "safe.modules.deployed",
            "data": {
              "id": "safe_123",
              "address": "0x456...",
              "salt": "salt_123",
              "chainId": "100",
              "userId": "user_123",
              "tokenSymbol": "EURe",
              "createdAt": "2025-10-15T08:00:24.193Z"
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "safe.modules.deployed",
  "data": {
    "id": "safe_123",
    "address": "0x456...",
    "salt": "salt_123",
    "chainId": "100",
    "userId": "user_123",
    "tokenSymbol": "EURe",
    "createdAt": "2025-10-15T08:00:24.193Z"
  }
}
```

### safe.owner.added

Triggered when an owner is added to a Safe.

**Event Type**: `safe.owner.added`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "safe.owner.added";
    data: {
      /** User ID */
      userId: string;
      /** Current owner address */
      owner: string;
      /** Safe address */
      safeAddress: string;
      /** Newly added owner address */
      addedOwner: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "safe.owner.added Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when an owner is added to a Safe."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "safe.owner.added"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "owner": {
                  "type": "string",
                  "description": "Current owner address"
                },
                "safeAddress": {
                  "type": "string",
                  "description": "Safe address"
                },
                "addedOwner": {
                  "type": "string",
                  "description": "Newly added owner address"
                }
              },
              "required": [
                "userId",
                "owner",
                "safeAddress",
                "addedOwner"
              ],
              "description": "Safe owner added data",
              "example": {
                "userId": "user_123",
                "owner": "0x123...",
                "safeAddress": "0x456...",
                "addedOwner": "0x789..."
              }
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when an owner is added to a Safe.",
          "example": {
            "eventType": "safe.owner.added",
            "data": {
              "userId": "user_123",
              "owner": "0x123...",
              "safeAddress": "0x456...",
              "addedOwner": "0x789..."
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "safe.owner.added",
  "data": {
    "userId": "user_123",
    "owner": "0x123...",
    "safeAddress": "0x456...",
    "addedOwner": "0x789..."
  }
}
```

### safe.owner.removed

Triggered when an owner is removed from a Safe.

**Event Type**: `safe.owner.removed`

**Schema Definition**:

<CodeGroup>
  ```typescript TypeScript theme={null}
  {
    eventType: "safe.owner.removed";
    data: {
      /** User ID */
      userId: string;
      safeAddress: string;
      removedOwner: string;
    };
  }
  ```

  ```json OpenAPI Schema theme={null}
  {
    "openapi": "3.0.0",
    "info": {
      "title": "safe.owner.removed Webhook Event",
      "version": "1.0.0",
      "description": "Triggered when an owner is removed from a Safe."
    },
    "components": {
      "schemas": {
        "WebhookEvent": {
          "type": "object",
          "properties": {
            "eventType": {
              "type": "string",
              "enum": [
                "safe.owner.removed"
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "description": "User ID"
                },
                "safeAddress": {
                  "type": "string"
                },
                "removedOwner": {
                  "type": "string"
                }
              },
              "required": [
                "userId",
                "safeAddress",
                "removedOwner"
              ]
            }
          },
          "required": [
            "eventType",
            "data"
          ],
          "description": "Triggered when an owner is removed from a Safe.",
          "example": {
            "eventType": "safe.owner.removed",
            "data": {
              "userId": "user_123",
              "safeAddress": "0x456...",
              "removedOwner": "0x789..."
            }
          }
        }
      }
    }
  }
  ```
</CodeGroup>

**Example**:

```json theme={null}
{
  "eventType": "safe.owner.removed",
  "data": {
    "userId": "user_123",
    "safeAddress": "0x456...",
    "removedOwner": "0x789..."
  }
}
```


# Working with Webhooks
Source: https://docs.gnosispay.com/webhooks/getting-started

Step-by-step guide to set up and implement webhooks in your application.

## Guidelines

To implement webhooks in your application, follow these essential steps:

<Steps>
  <Step title="Configure Your Endpoint">
    Create a publicly accessible HTTP endpoint in your application that can receive POST requests. This endpoint must be available over HTTPS and return a 2xx status code to acknowledge receipt of webhook events.

    <Warning>
      Your webhook endpoint must be publicly accessible. For local development, use tools like [ngrok](https://ngrok.com/) to expose your local server.
    </Warning>
  </Step>

  <Step title="Configure Webhooks">
    Configure your webhook endpoint URL directly through the [Partners Dashboard](https://partners.gnosispay.com/) or contact your Gnosis Pay partner manager for assistance. Provide the complete HTTPS URL where you want to receive webhook notifications.

    <Info>
      **Partners Dashboard**: For partners registered through the dashboard, webhook configuration is available instantly in your dashboard settings.
      **Manual Setup**: If you need technical support assistance, webhook configuration typically takes 1-2 business days.
    </Info>
  </Step>

  <Step title="Receive and Verify Events">
    When events happen in the Gnosis Pay system, we'll send HTTP POST requests to your webhook endpoint with event data and cryptographic signatures.

    All webhooks include cryptographic signatures using **Ed25519 asymmetric cryptography**:

    * **`X-Webhook-Timestamp`**: Unix timestamp when the webhook was sent
    * **`X-Webhook-Signature`**: Base64-encoded Ed25519 signature

    <Warning>
      **Always verify webhook signatures** before processing events. This ensures
      the webhook originated from Gnosis Pay and hasn't been tampered with.
    </Warning>

    Retrieve the public key for signature verification from our API:

    ```bash cURL theme={null}
    curl -X GET https://webhooks.gnosispay.com/api/v1/public-key
    ```
  </Step>

  <Step title="Parse and Process Event Data">
    Extract the `eventType` and `data` fields from the webhook payload. The `eventType` identifies what happened (e.g., `user.created`, `kyc.status.changed`), while `data` contains the complete entity information.

    ```json theme={null}
    {
      "eventType": "user.created",
      "data": {
        "id": "user_123",
        "email": "user@example.com",
        // ... complete user entity
      }
    }
    ```

    Handle each event type appropriately in your application. Since we send complete entity data, you typically won't need additional API calls to get the full context.

    <Info>
      Process events idempotently to handle potential duplicates, and implement proper error handling and logging for monitoring.
    </Info>

    <Info>
      **Retry Policy**: If your webhook endpoint returns a non-2xx status code, we'll retry delivery up to 3 times with exponential backoff (1 minute, 5 minutes, 15 minutes).
    </Info>

    <Warning>
      **Timeout**: Your webhook endpoint must respond within 30 seconds. Requests that exceed this timeout are considered failed and will trigger our retry mechanism.
    </Warning>
  </Step>
</Steps>

## Complete Example

<CodeGroup>
  ```typescript Node.js theme={null}
  import express from "express";
  import crypto from "crypto";

  const app = express();

  // Use raw body parsing for webhook signature verification
  app.use("/webhook", express.raw({ type: "application/json" }));
  app.use(express.json());

  app.post("/webhook", async (req: express.Request, res: express.Response) => {
    try {
      // Verify the webhook signature
      const isValid = await verifyWebhookSignature(req);
      if (!isValid) {
        return res.status(401).send("Invalid signature");
      }

      // Parse the body after verification
      const payload = JSON.parse(req.body.toString());
      const { eventType, data } = payload;
      await processWebhookEvent(eventType, data);

      // Acknowledge receipt
      res.status(200).send("OK");
    } catch (error) {
      console.error("Webhook processing error:", error);
      res.status(500).send("Internal server error");
    }
  });

  async function verifyWebhookSignature(req: express.Request): Promise<boolean> {
    try {
      const signature = req.headers["x-webhook-signature"] as string;
      const timestamp = req.headers["x-webhook-timestamp"] as string;

      // Check if required headers are present
      if (!timestamp || !signature) {
        console.error(
          "Missing required headers: x-webhook-timestamp or x-webhook-signature"
        );
        return false;
      }

      // Use the raw body for signature verification
      const body = req.body.toString();

      // Retrieve the public key from Gnosis Pay
      const publicKeyResponse = await fetch(
        "https://webhooks.gnosispay.com/api/v1/public-key"
      );
      const keyData = await publicKeyResponse.json();

      if (!keyData.success || !keyData.publicKey) {
        throw new Error("Failed to fetch public key");
      }

      const { publicKey } = keyData;

      // Create the payload for verification (same as Bun implementation)
      const signingPayload = `${timestamp}.${body}`;

      // Verify the signature using the same method as Bun
      return crypto.verify(
        null,
        Buffer.from(signingPayload, "utf8"),
        publicKey,
        Buffer.from(signature, "base64")
      );
    } catch (error) {
      console.error("Signature verification failed:", error);
      return false;
    }
  }

  async function processWebhookEvent(eventType: string, data: any) {
    switch (eventType) {
      case "user.created":
        console.log("user.created", data);
        break;
      case "kyc.status.changed":
        console.log("kyc.status.changed", data);
        break;
      case "card.transaction.created":
        console.log("card.transaction.created", data);
        break;
      // Handle other event types
      default:
        console.log(`Unhandled event type: ${eventType}`);
    }
  }
  ```
</CodeGroup>


# Introduction
Source: https://docs.gnosispay.com/webhooks/introduction

Learn how to integrate with Gnosis Pay webhooks to receive real-time event notifications.

Webhooks provide real-time notifications when events happen in the Gnosis Pay system. Rather than constantly polling our APIs for updates, you can configure webhook endpoints to receive instant notifications about user activities, KYC status changes, card transactions, and more.

Our [Sign-In with Ethereum (SIWE) authentication system](/auth) requires customers to generate short-lived tokens (JWTs) that expire after 1 hour. This means your application may not always have a valid token to fetch updated data from our APIs.
To avoid problems, we send complete entity data whenever possible in our webhook payloads.

## Enable Webhooks

To enable webhooks for your account:

1. **Contact your Gnosis Pay partner manager** or reach out to our technical support team
2. **Provide your webhook endpoint URL** (must be publicly accessible and use HTTPS)
3. **Wait for confirmation** that your webhook has been configured

<Info>
  **Setup Time**: Webhook configuration typically takes 1-2 business days after
  you provide the required information.
</Info>