### Install Mint CLI

Source: https://github.com/gnosispay/docs/blob/main/Readme.md

Installs the Mint CLI globally using npm. This is a prerequisite for local documentation preview.

```bash
npm i -g mint
```

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

### iban.status.changed Event Example (JSON)

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

An example payload for the iban.status.changed webhook event.

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

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

### Start Local Documentation Server

Source: https://github.com/gnosispay/docs/blob/main/Readme.md

Runs the Mint CLI development server from the documentation root. Ensure docs.json is present.

```bash
mint dev
```

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

### Complete Withdrawal Implementation Example

Source: https://github.com/gnosispay/docs/blob/main/gp-onchain/withdraw-funds-from-safe.mdx

This TypeScript example demonstrates the full withdrawal flow: fetching transaction data, signing it with a wallet client, and submitting the transaction. It also shows how to log the transaction result and notes the mandatory delay.

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

```

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

### Retrieve Link for Web Integration

Source: https://github.com/gnosispay/docs/blob/main/onboarding-flow.mdx

Get a unique URL for users to start their KYC process via a Sumsub iframe.

```APIDOC
## Retrieve Link for Web Integration

### Description
Retrieves a unique URL for initiating the KYC process through a Sumsub iframe.

### Method
GET

### Endpoint
/api/v1/kyc/integration

### Request Example
```bash
curl -X GET /api/v1/kyc/integration
```
```

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

### kyc.status.changed Webhook Event Example

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

This example demonstrates the structure of the payload received when a user's KYC status changes. It includes user details and their current KYC status.

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

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

### safe.currency.updated Event Example (JSON)

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

A concrete example of the JSON payload received when a Safe's currency is updated. Useful for testing your webhook integrations.

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

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

### card.transaction.confirmed Event Example

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

This example shows the structure of the card.transaction.confirmed event payload. It includes details about the transaction, merchant, and involved currencies.

```json
{
  "eventType": "card.transaction.confirmed",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "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"
        }
      ]
    },
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ]
  }
}
```

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

### Physical Card Ordered Event Example (JSON)

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

An example JSON payload for the physical.card.ordered webhook event. This demonstrates the expected data format when a physical card is ordered.

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

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

### Deploy GP Safe

Source: https://github.com/gnosispay/docs/blob/main/onboarding-flow.mdx

Initiates the deployment of a GP Safe with currency and setup delay and roles modules. The currency is automatically assigned based on the user's country.

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

### Description
Deploys a GP Safe with currency and setup delay and roles modules. The currency is automatically assigned based on the user's country: GBPe for UK, USDCe for Brazil, and EURe for other countries.

### Method
POST

### Endpoint
https://api.gnosispay.com/api/v1/safe/deploy

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

### Response
#### Success Response (202 Accepted)
Returns "accepted" if the request to deploy the safe is successful. Deployment and module setup may take up to 1 minute.
```

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

### Card Transaction Failed Event Example

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

This example shows the structure of a card transaction failed event. It includes details about the user, sign-in wallets, and the specific transaction event.

```json
{
  "eventType": "card.transaction.failed",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ],
    "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 Event Example (JSON)

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

A sample JSON payload for the `physical.card.activated` webhook event. This demonstrates the expected data format for a card activation.

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

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

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

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

An example payload for the physical.card.order.status.changed webhook event.

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

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

### Signup User with Email

Source: https://github.com/gnosispay/docs/blob/main/onboarding-flow.mdx

Register a new user with their email and partner ID. Include an optional referral coupon code if available. The partner ID is obtained from the Partners Dashboard.

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

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

### Account Withdrawal Failed Event Example

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

Example payload for the account.withdrawal.failed event. Use this to understand the structure of the data received.

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

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

### Complete Daily Limit Update Flow

Source: https://github.com/gnosispay/docs/blob/main/gp-onchain/daily-limit.mdx

Use this example to implement the entire process of updating a daily limit. It covers fetching transaction data, signing with a wallet, submitting the update, and optionally polling for confirmation. Ensure you have a wallet client configured.

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

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

### IBAN Created Event Example

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

Example payload for the iban.created event. Use this to understand the structure of the data received when an IBAN is created.

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

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

### Register New User with Email and Partner ID

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

Register a new user by providing their email address. The `partnerId` must be included to attribute the user to your integration. A `referralCouponCode` can optionally be provided.

```bash
curl -X POST https://api.gnosispay.com/api/v1/auth/signup \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "authEmail": "user@example.com",
    "partnerId": "partner_abc123",
    "referralCouponCode": "SAVE10"
  }'
# Response: { "userId": "usr_xyz", ... }
```

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

### Initialize Gnosis Pay Client and Fetch Transactions

Source: https://github.com/gnosispay/docs/blob/main/transactions/integration-guide.mdx

Set up the GnosisPayClient with an authentication token to interact with the API. Use the getTransactions method to retrieve transaction data, with optional parameters for filtering.

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

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

### physical.card.pin.changed Event Example (JSON)

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

An example JSON payload for the physical.card.pin.changed webhook event, showing the event type and associated data.

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

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

### Create a Card Order

Source: https://github.com/gnosispay/docs/blob/main/cards/create-physical-cards.mdx

Use this endpoint to initiate a new physical card order. The shipping address can be specified, otherwise the KYC address will be used. The amount is set in EURe.

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

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

### Card Transaction Refunded Event Example

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

This is an example of the card.transaction.refunded event payload. It includes details about the user, their wallets, and the refunded transaction.

```json
{
  "eventType": "card.transaction.refunded",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ],
    "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"
        }
      ]
    }
  }
}
```

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

### User Registration (Signup)

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

Registers a new user with their email address. Requires the `partnerId` to attribute the user to a specific integration. The JWT obtained from authentication must be included in the Authorization header.

```APIDOC
## User Registration (Signup)

### Description
Registers a new user with their email address. Requires the `partnerId` to attribute the user to a specific integration. The JWT obtained from authentication must be included in the Authorization header.

### Method
POST

### Endpoint
https://api.gnosispay.com/api/v1/auth/signup

### Parameters
#### Request Body
- **authEmail** (string) - Required - The email address of the user.
- **partnerId** (string) - Required - The unique identifier for the partner integration.
- **referralCouponCode** (string) - Optional - A coupon code for referrals.

### Response
#### Success Response (200)
- **userId** (string) - The unique identifier for the newly registered user.
```

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

### card.transaction.cleared Event Example

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

This example demonstrates the structure of the card.transaction.cleared event payload. It includes details about the transaction, merchant, and involved currencies.

```json
{
  "eventType": "card.transaction.cleared",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "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"
        }
      ]
    },
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100",
        "tokenSymbol": "EURe"
      }
    ]
  }
}
```

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

### Deploy GP Safe Account

Source: https://github.com/gnosispay/docs/blob/main/onboarding-flow.mdx

Initiates the deployment of a GP Safe with currency, setup delay, and roles modules. The currency is assigned based on the user's country. Ensure accountStatus is not 0 before deployment.

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

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

### Virtual Card Issued Event Example (JSON)

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

A concrete JSON example of the virtual.card.issued webhook event. This can be used for testing your webhook receivers.

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

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

### safe.created Event Example Payload

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

An example JSON payload for the safe.created webhook event. This demonstrates the expected data format when a Safe wallet is created.

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

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

### Create Physical Card for Order

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

Initiates the creation of a physical card for a confirmed order.

```bash
curl -X POST https://api.gnosispay.com/api/v1/order/ord_abc/create-card \
  -H "Authorization: Bearer <jwt>"
```

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

### Card Transaction Reversed Event Example

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

This example shows the structure of the card.transaction.reversed event payload. It includes details about the transaction, merchant, and involved currencies.

```json
{
  "eventType": "card.transaction.reversed",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "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"
        }
      ]
    },
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ]
  }
}
```

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

### Create a Physical Card

Source: https://github.com/gnosispay/docs/blob/main/cards/create-physical-cards.mdx

Finally, create the physical card using the order ID. This endpoint has several prerequisites including user verification, address, and risk assessment.

```bash
curl -X POST /api/v1/order/:orderId/create-card
```

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

### card.status.changed Event Example (JSON)

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

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

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

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

### Verify Safe Configuration

Source: https://github.com/gnosispay/docs/blob/main/onboarding-flow.mdx

Verifies the Safe account configuration post-deployment by checking the account status. An accountStatus of 0 indicates the Safe is fully configured.

```APIDOC
## GET /api/v1/safe-config

### Description
Verifies the Safe is fully configured by checking the account status. An `accountStatus` of 0 means the GP Safe is fully configured and ready for use.

### Method
GET

### Endpoint
https://api.gnosispay.com/api/v1/safe-config

### Response
#### Success Response (200 OK)
- **accountStatus** (number) - The status of the Safe account. `0` indicates the Safe modules are deployed and the account is ready.

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

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

### Retrieve and Accept Terms of Service

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

Fetch pending terms that require user acceptance and then submit the acceptance for each. Ensure to display terms with mapped titles and require user confirmation.

```bash
# 1. Get pending terms
curl -X GET https://api.gnosispay.com/api/v1/user/terms \
  -H "Authorization: Bearer <jwt>"
# Response: [{ "terms": "general-tos", "version": "TOS_GENERAL_VERSION_1", "accepted": false }, ...]

# 2. Accept each term
curl -X POST https://api.gnosispay.com/api/v1/user/terms \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "terms": "general-tos", "version": "TOS_GENERAL_VERSION_1" }'
```

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

### card.transaction.declined Event Example

Source: https://github.com/gnosispay/docs/blob/main/webhooks/events.mdx

This example shows the structure of the data payload for a card transaction declined event. It includes details about the transaction, merchant, and involved currencies.

```json
{
  "eventType": "card.transaction.declined",
  "data": {
    "userId": "user_123",
    "signInWallets": [
      {
        "address": "0x1234567890123456789012345678901234567890"
      }
    ],
    "safeWallets": [
      {
        "address": "0xabcdef1234567890abcdef1234567890abcdef12",
        "chainId": "100"
      }
    ],
    "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"
        }
      ]
    }
  }
}
```

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

### Deploy Gnosis Pay Safe

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

Initiate the deployment of a Gnosis Pay Safe for the user. The currency is auto-assigned based on the user's country. The response indicates acceptance, and deployment status should be polled.

```bash
# Deploy Safe
curl -X POST https://api.gnosispay.com/api/v1/safe/deploy \
  -H "Authorization: Bearer <jwt>"
# Response: { "status": "accepted" } — can take up to 1 minute
```