Gnosis Pay

https://docs.gnosispay.com
Admin
Gnosis Pay is a stablecoin-based payment platform that enables users to spend cryptocurrency in the...
Tokens:203,553
Snippets:925
Trust Score:8.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Setup Safe with Signature Request Example

Source: https://docs.gnosispay.com/api-reference/safe-management/setup-safe-with-signature

This example shows the structure of the request body required to set up a Safe account using an EIP-712 signature. Ensure the signature is correctly formatted and obtained from the GET /api/v1/account/signature-payload endpoint.

```json
{
  "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b"
}
```

--------------------------------

### Successful Safe Setup Response

Source: https://docs.gnosispay.com/api-reference/safe-management/setup-safe-with-signature

This is an example of a successful response after executing the account setup transaction. It includes the transaction hash and a boolean indicating if the deployment was successful. This endpoint waits for on-chain confirmation, which may take up to 10 seconds.

```json
{
  "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "deployed": true
}
```

--------------------------------

### Create or Deploy Safe (pending Setup)

Source: https://docs.gnosispay.com/api-reference/safe-management/create-or-deploy-a-safe-pending-setup

This endpoint checks for an existing Safe account for the user. If none exists, it creates one and starts the deployment. If an account exists but is not deployed, it initiates the deployment process. The endpoint waits for transaction execution and confirmation on-chain, which may take up to 10 seconds. It uses a sponsored transaction on the Gnosis Chain.

```APIDOC
## POST /api/v1/account

### Description
This endpoint serves two purposes - it first checks if a Safe account
exists for the user. If no account exists, it creates one and initiates
deployment.

If an account already exists but is not deployed, it initiates the
deployment process.

This endpoint can be called immediately after user signup as there are
no restrictions or prerequisites.

When deploying a new Safe, the endpoint waits for transaction execution
and confirmation on-chain.

Because of this, the request may take up to 10 seconds to complete when
a deployment is needed.

The deployment process is handled by a sponsored transaction on the
Gnosis Chain, and the response
includes the transaction hash for tracking the deployment status.

Next steps after successful deployment is to setup the Safe:

- Once this endpoint successfully creates and deploys a Safe account, the user should call
  the `/api/v1/safe/set-currency` endpoint to set the currency for the account.
- Note that the `/api/v1/safe/set-currency` endpoint requires the user to have completed
  the KYC process successfully.
- Then, the user should call the `/api/v1/account/signature-payload` endpoint to get the signature data for the account setup.

- Finally, the user should call the
`/api/v1/account/deploy-safe-modules` endpoint to deploy the Safe modules with the user's signature.

### Method
POST

### Endpoint
/api/v1/account

### Parameters
#### Request Body
- **chainId** (string) - Required - The ID of chain (currently only supports Gnosis Chain)

### Request Example
{
  "chainId": "100"
}

### Response
#### Success Response (200)
- **id** (string) - The Safe account ID
- **address** (string) - The Safe account address
- **userId** (string) - ID of the user owning this Safe
- **chainId** (string) - ID of the blockchain
- **salt** (string) - Salt used for Safe address generation
- **createdAt** (string) - Timestamp of when the Safe was created
- **deployed** (boolean) - Whether the Safe is deployed on-chain
- **transactionHash** (string) - Transaction hash of the deployment transaction (if completed)

#### Response Example
```json
{
  "id": "safe-account-id-123",
  "address": "0x1234567890123456789012345678901234567890",
  "userId": "user123",
  "chainId": "100",
  "salt": "some-salt-value",
  "createdAt": "2024-01-01T00:00:00Z",
  "deployed": true
}
```
```

--------------------------------

### Setup Safe with Signature

Source: https://docs.gnosispay.com/llms.txt

Takes an EIP-712 signature provided by the user's wallet and executes the account setup transaction. This is the second step in the account setup process, after obtaining the signature data from the GET /api/v1/account/signature-payload endpoint.

```APIDOC
## Setup Safe with Signature

### Description
Takes an EIP-712 signature provided by the user's wallet and executes the account setup transaction. This is the second step in the account setup process, after obtaining the signature data from the GET /api/v1/account/signature-payload endpoint.

### Method
POST

### Endpoint
/api/v1/account/setup

### Parameters
#### Request Body
- **signature** (string) - Required - The EIP-712 signature provided by the user's wallet.
```

--------------------------------

### Setup Safe with Signature

Source: https://docs.gnosispay.com/api-reference/safe-management/setup-safe-with-signature

Takes an EIP-712 signature provided by the user's wallet and executes the account setup transaction. This is the second step in the account setup process, after obtaining the signature data from the GET /api/v1/account/signature-payload endpoint. This endpoint will wait for the transaction to be confirmed on-chain and return the transaction hash when successful.

```APIDOC
## PATCH /api/v1/account/deploy-safe-modules

### Description
Takes an EIP-712 signature provided by the user's wallet and executes the account setup transaction. This is the second step in the account setup process, after obtaining the signature data from the GET /api/v1/account/signature-payload endpoint.

The process flow is:

1. Call GET /api/v1/account/signature-payload to get the EIP-712 signature data
2. Sign the data with the user's wallet
3. Submit the signature to this endpoint to execute the transaction

This endpoint will wait for the transaction to be confirmed on-chain and return the transaction hash when successful. Because it waits for on-chain confirmation, this request may take up to 10 seconds to complete.

The setup process configures Safe account allowances and delay mechanisms required for secure operation.

Prerequisites:

- User must have a deployed Safe account
- The Safe account must have a currency set (via /api/v1/safe/set-currency)
- User must have signed the data from GET /api/v1/account/signature-payload

### Method
PATCH

### Endpoint
/api/v1/account/deploy-safe-modules

### Request Body
#### Request Body
- **signature** (string) - Required - The EIP-712 signature for the account setup transaction

### Request Example
```json
{
  "signature": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1b"
}
```

### Response
#### Success Response (200)
- **transactionHash** (string) - The transaction hash of the executed transaction
- **deployed** (boolean) - Whether the account setup is deployed

#### Response Example
```json
{
  "transactionHash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "deployed": true
}
```

#### Error Response (400)
- **error** (string) - Error message explaining why the request failed

##### Example
```json
{
  "error": "Account not found"
}
```

#### Error Response (401)
- Unauthorized Error

#### Error Response (500)
- Internal Server Error
```

--------------------------------

### Example Private Key Format

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

This is an example of the PEM format for a private key.

```text
-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC7VJTUt9Us8cKB
... (base64 encoded private key data) ...
-----END PRIVATE KEY-----
```

--------------------------------

### Deploy and Setup a Safe

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

Deploys and sets up the Safe account for the authenticated user. The user must be KYC approved. This endpoint is idempotent; subsequent calls with an ongoing deployment will return `202` without initiating a new workflow. Deployment status can be monitored using `GET /api/v1/safe/deploy`.

```APIDOC
## POST /api/v1/safe/deploy

### Description
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`).

### Method
POST

### Endpoint
/api/v1/safe/deploy

### Responses
#### Success Response (202)
- **status** (string) - Accepted the deployment request. The partner should check the status of the deployment with the GET /api/v1/safe/deploy endpoint.

#### Error Response (401)
- **message** (string) - Unauthorized Error

#### Error Response (403)
- **error** (string) - Forbidden. Missing signer address.

#### Error Response (422)
- **error** (string) - Unprocessable Entity. Safe account already exists or user is not KYC approved.

#### Error Response (500)
- **error** (string) - Internal Server Error
```

--------------------------------

### Example Certificate Format

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

This is an example of the PEM format for a client certificate.

```text
-----BEGIN CERTIFICATE-----
MIIFazCCA1OgAwIBAgIRAIIQz7DSQONZRGPgu2oCiwYwDQYJKoZIhvcNAQELBQAw
... (base64 encoded certificate data) ...
-----END CERTIFICATE-----
```

--------------------------------

### Monitor Gnosis Pay Safe Deployment Status

Source: https://docs.gnosispay.com/onboarding-flow

After initiating Safe deployment, use this GET request to monitor its progress. Successful deployment and module setup can take up to 1 minute.

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

--------------------------------

### Account Limit Changed Event Example (JSON)

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

An example JSON payload for the account.limit.changed event. This demonstrates the expected format for the event data.

```json
{
  "eventType": "account.limit.changed",
  "data": {
    "userId": "user_123",
    "oldLimit": 1000,
    "newLimit": 2000
  }
}
```

--------------------------------

### IBAN Created Event Example

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

Provides a concrete JSON example of the iban.created event payload.

```json
{
  "eventType": "iban.created",
  "data": {
    "userId": "user_123",
    "iban": "GB82WEST12345698765432",
    "bic": "WESTGB22"
  }
}
```

--------------------------------

### Execute Account Setup Transaction

Source: https://docs.gnosispay.com/api-reference/safe-management/setup-safe-with-signature

Submits the EIP-712 signature to execute the Safe account setup transaction. This endpoint waits for on-chain confirmation and returns the transaction hash upon success.

```APIDOC
## POST /api/v1/safe/setup-with-signature

### Description
Takes an EIP-712 signature provided by the user's wallet and executes the account setup transaction. This is the second step in the account setup process, after obtaining the signature data from the GET /api/v1/account/signature-payload endpoint.

### Method
POST

### Endpoint
/api/v1/safe/setup-with-signature

### Request Body
- **signature** (string) - Required - The EIP-712 signature provided by the user's wallet.

### Response
#### Success Response (200)
- **transactionHash** (string) - The hash of the confirmed transaction.

#### Response Example
{
  "transactionHash": "0xabc123..."
}
```

--------------------------------

### Node.js Express Webhook Example

Source: https://docs.gnosispay.com/webhooks/getting-started

This example demonstrates how to set up an Express.js server to receive and verify Gnosis Pay webhooks. It includes signature verification using the raw request body and processing of different event types.

```typescript
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}`);
  }
}

```

--------------------------------

### safe.modules.deployed Event Payload Example (JSON)

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

A sample JSON payload for the safe.modules.deployed webhook event. This example illustrates the expected format and fields when a Safe module is deployed.

```json
{
  "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"
  }
}
```

--------------------------------

### Bad Request Response Examples

Source: https://docs.gnosispay.com/api-reference/safe-management/setup-safe-with-signature

These examples illustrate potential error responses for bad requests, such as when the account is not found, the Safe currency is not set, or the signer address is missing. Review the error message to identify the specific issue.

```json
{
  "error": "Account not found"
}
```

```json
{
  "error": "Safe currency not set"
}
```

```json
{
  "error": "Missing signer address"
}
```

--------------------------------

### Bad Request - Missing Parameters

Source: https://docs.gnosispay.com/api-reference/safe-management/create-or-deploy-a-safe-pending-setup

This example illustrates the error response when required parameters are not provided in the request.

```json
{
  "error": "Missing required parameters"
}
```

--------------------------------

### Virtual Card Issued Event Example (JSON)

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

A concrete JSON example of the 'virtual.card.issued' webhook event. This demonstrates the expected payload structure when a virtual card is successfully issued.

```json
{
  "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"
  }
}
```

--------------------------------

### kyc.status.changed Event Example

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

This JSON payload represents an example of the `kyc.status.changed` event. It includes detailed user information, KYC status, available features, card details, and banking information.

```json
{
  "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
  }
}
```

--------------------------------

### Initialize Gnosis Pay Client and Fetch Transactions

Source: https://docs.gnosispay.com/transactions/integration-guide

Set up the Gnosis Pay client with an authentication token and fetch transactions. Supports filtering with query parameters.

```javascript
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
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()
```

--------------------------------

### Deploy and Setup a Safe

Source: https://docs.gnosispay.com/llms.txt

Deploys and sets up the Safe account for the authenticated user. The User needs to be KYC approved.

```APIDOC
## POST /safe/setup

### Description
Deploys and sets up the Safe account for the authenticated user. Requires KYC approval.

### Method
POST

### Endpoint
`/safe/setup`
```

--------------------------------

### List Dispute Reasons OpenAPI Specification

Source: https://docs.gnosispay.com/api-reference/transactions/list-dispute-reasons

This OpenAPI specification defines the GET /api/v1/transactions/dispute endpoint. It details the request, response structure, and example data for dispute reasons.

```yaml
openapi: 3.0.0
info:
  title: GnosisPay API
  version: 1.0.0
  description: OpenAPI documentation for GnosisPay
servers:
  - url: https://api.gnosispay.com
security: []
tags:
  - name: Account Management
    description: Information about your Account
  - name: Authentication
    description: Authenticate to our API using SIWE
  - name: Card Management
    description: Manage all your Cards
  - name: IBAN
    description: Integrate with Monerium to issue IBANs
  - name: KYC
    description: KYC using Sumsub SDK
  - name: Physical Card Order
    description: Order a Physical Card and manage the process
  - name: Rewards
    description: Cashback Rewards
  - name: Safe Management
    description: Manage your Safe
  - name: Transactions
    description: Manage Card Transactions
  - name: User
    description: Manage User Information
  - name: Webhooks
    description: Manage Webhooks
paths:
  /api/v1/transactions/dispute:
    get:
      tags:
        - Transactions
      summary: List Dispute Reasons
      description: >-
        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.
      responses:
        '200':
          description: Successfully retrieved dispute reasons
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                example:
                  purchase_cancelled_but_no_refund_received: Purchase Cancelled But No Refund Received
                  problem_with_the_product_chargeback_: Problem With The Product (chargeback)
                  problem_with_service_subscription_chargeback: Problem With Service/Subscription (chargeback)
                  wrong_installment_number: Wrong Installment Number
                  wrong_value: Wrong Value
                  charged_more_than_once: Charged More Than Once
                  unrecognized_transaction_report_fraudulent: Unrecognized Transaction - Report Fraudulent
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  responses:
    UnauthorizedError:
      description: Unauthorized Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
  InternalServerError:
    description: Internal Server Error
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

```

--------------------------------

### Create or Deploy a Safe (pending Setup)

Source: https://docs.gnosispay.com/llms.txt

This endpoint serves two purposes - it first checks if a Safe account exists for the user. If no account exists, it creates one and initiates deployment. If an account already exists but is not deployed, it initiates the deployment process.

```APIDOC
## POST /safe/deploy

### Description
Checks if a Safe account exists for the user. If not, creates one and initiates deployment. If an account exists but is not deployed, it initiates the deployment process.

### Method
POST

### Endpoint
`/safe/deploy`
```

--------------------------------

### Signup with email

Source: https://docs.gnosispay.com/onboarding-flow

Registers a new user with their email and partner ID. An optional referral coupon code can also be included.

```APIDOC
## POST /api/v1/auth/signup

### Description
Registers a new user with their email and partner ID. An optional referral coupon code can also be included.

### Method
POST

### Endpoint
/api/v1/auth/signup

### Parameters
#### Request Body
- **authEmail** (string) - Required - The user's email address.
- **partnerId** (string) - Required - A unique identifier for your app.
- **referralCouponCode** (string) - Optional - A referral coupon code.

### Request Example
```json
{
  "authEmail": "string",
  "partnerId": "string",
  "referralCouponCode": "string" (optional)
}
```
```

--------------------------------

### Account Withdrawal Failed Event Example

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

Provides a concrete JSON example of the account.withdrawal.failed event payload.

```json
{
  "eventType": "account.withdrawal.failed",
  "data": {
    "userId": "user_123",
    "error": "Transaction failed"
  }
}
```

--------------------------------

### IBAN Status Changed Event Example (JSON)

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

An example JSON payload for the 'iban.status.changed' webhook event. Demonstrates the structure with user ID and status transition.

```json
{
  "eventType": "iban.status.changed",
  "data": {
    "userId": "user_123",
    "previousStatus": "PENDING",
    "currentStatus": "ASSIGNED"
  }
}
```

--------------------------------

### Complete Withdrawal Flow Example

Source: https://docs.gnosispay.com/gp-onchain/withdraw-funds-from-safe

Demonstrates the full process of withdrawing funds from a Gnosis Safe, including fetching transaction data, signing, and submitting the withdrawal. Ensure the user is aware of the Gnosis Chain and that transactions are irreversible.

```typescript
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");
```

--------------------------------

### Physical Card Activated Event Example (JSON)

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

An example JSON payload for the 'physical.card.activated' webhook event. This demonstrates the structure and typical values for the event data.

```json
{
  "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"
  }
}
```

--------------------------------

### Register User with Email and Partner ID

Source: https://docs.gnosispay.com/onboarding-flow

Use this cURL command to register a new user with their email and your partner ID. An optional referral coupon code can be included.

```bash
curl -X POST /api/v1/auth/signup \
    -d '{
      "authEmail": "string",
      "partnerId": "string",
      "referralCouponCode": "string" (optional)
    }'
```

--------------------------------

### Physical Card Order Status Changed Event Example (JSON)

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

An example JSON payload for the physical.card.order.status.changed event. Demonstrates the expected format for eventType and data fields.

```json
{
  "eventType": "physical.card.order.status.changed",
  "data": {
    "userId": "user_123",
    "cardToken": "card_123",
    "cardOrderId": "order_456",
    "oldStatus": "ordered",
    "newStatus": "shipped"
  }
}
```

--------------------------------

### Complete Daily Limit Update Flow

Source: https://docs.gnosispay.com/gp-onchain/daily-limit

This snippet demonstrates the full process of updating a daily limit, including fetching data, signing, submitting, and monitoring the update. Ensure you have a wallet client configured for signing.

```typescript
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);
```

--------------------------------

### Physical Card PIN Changed Event Example (JSON)

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

A JSON example of the physical.card.pin.changed webhook event payload. Includes event type, user ID, and card token.

```json
{
  "eventType": "physical.card.pin.changed",
  "data": {
    "userId": "user_123",
    "cardToken": "card_123456789"
  }
}
```

--------------------------------

### Card Status Changed Event Payload Example (JSON)

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

An example JSON payload for the card.status.changed webhook event. This shows the expected data format when a card's status is updated.

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

--------------------------------

### Create a Card Order

Source: https://docs.gnosispay.com/cards/create-physical-cards

This endpoint creates a new CardOrder with the status of PENDINGTRANSACTION. A shipping address can be specified; otherwise, the KYC address will be used. The amount is set in EURe, and a coupon can be applied.

```bash
curl -X POST /api/v1/order/create
```

--------------------------------

### Account Balance Changed Event Example (JSON)

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

A sample JSON payload for the `account.balance.changed` event. This illustrates the data format received when an account's balance is updated.

```json
{
  "eventType": "account.balance.changed",
  "data": {
    "userId": "user_123",
    "total": 1000000000000000000,
    "spendable": 800000000000000000,
    "pending": 200000000000000000
  }
}
```

--------------------------------

### OpenAPI Specification for Get Signing Message

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

This OpenAPI specification defines the GET /api/v1/ibans/signing-message endpoint. It outlines the request, response structure, and error handling for retrieving the message needed to sign for IBAN activation.

```yaml
openapi: 3.0.0
info:
  title: GnosisPay API
  version: 1.0.0
  description: OpenAPI documentation for GnosisPay
servers:
  - url: https://api.gnosispay.com
security: []
tags:
  - name: Account Management
    description: Information about your Account
  - name: Authentication
    description: Authenticate to our API using SIWE
  - name: Card Management
    description: Manage all your Cards
  - name: IBAN
    description: Integrate with Monerium to issue IBANs
  - name: KYC
    description: KYC using Sumsub SDK
  - name: Physical Card Order
    description: Order a Physical Card and manage the process
  - name: Rewards
    description: Cashback Rewards
  - name: Safe Management
    description: Manage your Safe
  - name: Transactions
    description: Manage Card Transactions
  - name: User
    description: Manage User Information
  - name: Webhooks
    description: Manage Webhooks
paths:
  /api/v1/ibans/signing-message:
    get:
      tags:
        - IBAN
      summary: Get the message that needs to be signed for IBAN activation
      description: >-
        Returns the standard message that users need to sign with their wallet
        to verify ownership for Monerium IBAN activation.
      responses:
        '200':
          description: Successfully retrieved the signing message
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                        example: I hereby declare that I am the address owner.
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - bearerAuth: []
components:
  responses:
    UnauthorizedError:
      description: Unauthorized Error
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: Internal server error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

```
Tokens:
Raw