MzzPay

https://mzzpay.io/developers
Admin
MzzPay is a unified, resilient payments API that integrates cards, wallets, open banking, and gaming...
Tokens:33,249
Snippets:281
Trust Score:1.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Go SDK

Source: https://mzzpay.io/developers/sdks

Use go get to install the official Go client library.

```bash
go get github.com/mzzpay/mzzpay-go
```

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

### Install Python SDK

Source: https://mzzpay.io/developers/sdks

Use pip to install the official Python client library.

```bash
pip install mzzpay
```

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

### Install PHP SDK

Source: https://mzzpay.io/developers/sdks

Use composer to install the official PHP client library.

```bash
composer require mzzpay/mzzpay-php
```

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

### Install Ruby SDK

Source: https://mzzpay.io/developers/sdks

Use gem to install the official Ruby client library.

```bash
gem install mzzpay
```

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

### Install Node.js SDK

Source: https://mzzpay.io/developers/sdks

Use npm to install the official Node.js client library.

```bash
npm install @mzzpay/node
```

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

### Install Java SDK

Source: https://mzzpay.io/developers/sdks

Add the dependency to your build configuration.

```gradle
implementation 'com.mzzpay:mzzpay-java:1.0.0'
```

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

### Webhook Payload Example

Source: https://mzzpay.io/developers/quick-start

Example structure of a payment completion event received via webhook.

```json
# Webhook payload example
{
  "event": "payment.completed",
  "data": {
    "id": "pay_abc123",
    "amount": 5000,
    "status": "succeeded"
  }
}
```

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

### Webhook Event Payload Example

Source: https://mzzpay.io/developers/webhooks

Example of the HTTP request structure and JSON body sent to your webhook endpoint.

```http
POST /your/endpoint
Content-Type: application/json
X-Mzzpay-Event: payment.succeeded
X-Mzzpay-Signature: <hex hmac-sha256 of body>

{
  "id": "evt_test_abc123",
  "type": "payment.succeeded",
  "created": 1786905888326,
  "data": {
    "id": "9b1c2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f",
    "amount": 5000,
    "currency": "usd",
    "status": "completed",
    "merchant_id": "mer_test_123"
  }
}
```

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

### List Refunds Request

Source: https://mzzpay.io/developers/api/refunds

Example request to query the refunds table using PostgREST filters.

```bash
curl "https://api.mzzpay.io/rest/v1/refunds?transaction_id=eq.9b1c..." \
  -H "Authorization: Bearer <user_jwt>" \
  -H "apikey: <publishable_key>"
```

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

### GET /rest/v1/products

Source: https://mzzpay.io/developers/api/products

Retrieves a list of products from the merchant's catalog.

```APIDOC
## GET /rest/v1/products

### Description
Returns the merchant's catalog. Filter is_active=eq.true to show only live items.

### Method
GET

### Endpoint
/rest/v1/products

### Parameters
#### Query Parameters
- **is_active** (boolean) - Optional - eq.true / eq.false
- **category** (string) - Optional - PostgREST filter

### Response
#### Success Response (200)
- **id** (string) - Product ID
- **name** (string) - Product name
- **price** (number) - Product price

#### Response Example
[ { "id": "6f7a...", "name": "Premium Plan", "price": 249 } ]
```

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

### Create a Refund Request

Source: https://mzzpay.io/developers/api/refunds

Example request to refund a completed transaction using the refund-payment function.

```bash
curl -X POST https://api.mzzpay.io/functions/v1/refund-payment \
  -H "Authorization: Bearer <user_jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "transactionId": "9b1c2d3e-4f5a-6b7c-8d9e-0a1b2c3d4e5f",
    "amount": 25.00,
    "reason": "requested_by_customer"
  }'
```

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

### GET /rest/v1/customers

Source: https://mzzpay.io/developers/verification

Retrieves a list of customers.

```APIDOC
## GET /rest/v1/customers

### Description
Fetches customers associated with the merchant account.

### Method
GET

### Endpoint
/rest/v1/customers

### Query Parameters
- **select** (string) - Optional
- **email** (string) - Optional
- **limit** (number) - Optional
- **order** (string) - Optional

### Response
- **Array<Customer>** - RLS scoped to merchant_id
```

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

### Idempotency Header

Source: https://mzzpay.io/developers/quick-start

Example of the Idempotency-Key header used to prevent duplicate operations.

```http
Idempotency-Key: 6f3b2a1e-9c4d-4f8a-bb12-7e9f3a2b1c4d
```

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

### GET /rest/v1/crypto_wallets

Source: https://mzzpay.io/developers/api/crypto

Returns a list of crypto wallets for the authenticated merchant.

```APIDOC
## GET /rest/v1/crypto_wallets

### Description
Returns one row per merchant + store + asset combination.

### Method
GET

### Endpoint
/rest/v1/crypto_wallets

### Parameters
#### Query Parameters
- **merchant_id** (uuid) - Optional - eq.<id>
- **asset_id** (string) - Optional - eq.USDT
- **is_active** (boolean) - Optional - eq.true

### Response
#### Success Response (200)
- **id** (string) - Wallet ID
- **asset_id** (string) - Asset identifier
- **balance** (number) - Total balance
- **available** (number) - Available balance
- **on_hold** (number) - Amount on hold
- **address** (string) - Wallet address

#### Response Example
[
  {
    "id": "wal_usdt",
    "asset_id": "USDT",
    "balance": 1842.50,
    "available": 1750.50,
    "on_hold": 92.00,
    "address": "0x742d35..."
  }
]
```

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

### GET /v1/open-banking/banks

Source: https://mzzpay.io/developers/api/open-banking

List supported Open Banking institutions available in a specific country.

```APIDOC
## GET /v1/open-banking/banks

### Description
List Supported Banks. Returns a list of Open Banking institutions available in a given country.

### Method
GET

### Endpoint
/v1/open-banking/banks

### Parameters
#### Query Parameters
- **country** (string) - Required - ISO 3166-1 alpha-2 (GB, DE, FR, ES, IT, NL, IE)

### Response
#### Success Response (200)
- **object** (string) - List type
- **data** (array) - List of bank objects
```

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

### Handle Authentication Error Responses

Source: https://mzzpay.io/developers/api/authentication

Example JSON structures for 401 Unauthorized and 403 Forbidden error responses.

```json
// 401 Unauthorized
{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key provided.",
    "code": "invalid_api_key"
  }
}

// 403 Forbidden
{
  "error": {
    "type": "authorization_error",
    "message": "This key does not have permission for this resource.",
    "code": "insufficient_permissions"
  }
}
```

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

### GET /rest/v1/crypto_wallets

Source: https://mzzpay.io/developers/api/wallets

Returns crypto wallets across all of a merchant's stores.

```APIDOC
## GET /rest/v1/crypto_wallets

### Description
Returns crypto wallets across all of a merchant's stores. Filter ?store_id=eq.{id} to scope to one store.

### Method
GET

### Endpoint
/rest/v1/crypto_wallets

### Parameters
#### Query Parameters
- **store_id** (uuid) - Optional - Scope to one crypto_stores row
- **asset_id** (string) - Optional - Filter by asset symbol
- **is_active** (boolean) - Optional - eq.true to hide disabled wallets

### Response
#### Success Response (200)
- **id** (string) - Wallet ID
- **asset_id** (string) - Asset symbol
- **balance** (number) - Total balance
- **available** (number) - Available balance

#### Response Example
[
  { "id": "0a1b...", "asset_id": "USDT_TRC20", "balance": 1250.42, "available": 1180.42 }
]
```

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

### 3DS-aware Transaction Response

Source: https://mzzpay.io/developers/api/3d-secure

Example of a transaction response indicating that a 3D Secure challenge is required.

```json
{
  "success": true,
  "transaction": {
    "id": "9b1c2d3e-...",
    "status": "pending",
    "amount": 50.00,
    "currency": "EUR",
    "provider": "mondo",
    "card_brand": "visa",
    "card_last4": "4242",
    "processor_raw_response": {
      "three_ds": {
        "required": true,
        "version": "2.2.0",
        "redirect_url": "https://3ds.acs.example/challenge/abc",
        "ds_transaction_id": "f4a83e..."
      }
    }
  }
}
```

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

### Create a Product

Source: https://mzzpay.io/developers/api/products

Inserts a new row into the public.products table.

```bash
curl -X POST "https://api.mzzpay.io/rest/v1/products" -H "Authorization: Bearer <user_jwt>" -H "apikey: <publishable_key>" -H "Content-Type: application/json" -H "Prefer: return=representation" -d '{ "merchant_id":"9b1c...", "name":"Premium Plan", "price":249, "currency":"USD" }'
```

```json
[ { "id": "6f7a...", "name": "Premium Plan", "price": 249, "is_active": true } ]
```

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

### GET /rest/v1/disputes

Source: https://mzzpay.io/developers/verification

Retrieves a list of disputes.

```APIDOC
## GET /rest/v1/disputes

### Description
Fetches dispute records synced via webhooks.

### Method
GET

### Endpoint
/rest/v1/disputes

### Query Parameters
- **status** (string) - Optional
- **transaction_id** (string) - Optional

### Response
- **Array<Dispute>**
```

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

### Initialize Checkout.js

Source: https://mzzpay.io/developers/sdks

Include the script in your HTML and mount the payment form to a DOM element.

```html
<!-- Add to your HTML -->
<script src="https://js.mzzpay.io/v1/checkout.js"></script>

<script>
  const checkout = MzzPay.checkout({
    publishableKey: 'pk_test_your_key',
    amount: 5000,
    currency: 'usd',
    onSuccess: (result) => {
      console.log('Payment succeeded:', result.payment_id);
    },
    onError: (error) => {
      console.error('Payment failed:', error.message);
    }
  });

  checkout.mount('#payment-form');
</script>
```

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

### Subscribe a Customer

Source: https://mzzpay.io/developers/api/subscriptions

Links a customer to a plan and a payment method to initiate a subscription.

```bash
curl -X POST "https://api.mzzpay.io/rest/v1/subscriptions" -H "Authorization: Bearer <user_jwt>" -H "apikey: <publishable_key>" -H "Content-Type: application/json" -d '{ "customer_id":"8a2b...", "plan_id":"5e6f...", "payment_method_id":"3c4d...", "current_period_start":"2026-04-22T10:00:00Z", "current_period_end":"2026-05-22T10:00:00Z" }'
```

```json
[ { "id": "4d5e...", "status": "active" } ]
```

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

### GET /rest/v1/invoices

Source: https://mzzpay.io/developers/verification

Retrieves a list of invoices.

```APIDOC
## GET /rest/v1/invoices

### Description
Fetches invoices with optional filtering.

### Method
GET

### Endpoint
/rest/v1/invoices

### Query Parameters
- **status** (string) - Optional
- **customer_id** (string) - Optional
- **select** (string) - Optional

### Response
- **Array<Invoice>** - Includes line items via select
```

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

### Create a Fiat Payout

Source: https://mzzpay.io/developers/api/payouts

Initiate a fiat payout using the Moneto wallet endpoint.

```bash
curl -X POST "https://api.mzzpay.io/functions/v1/moneto-wallet" -H "Authorization: Bearer <user_jwt>" -H "Content-Type: application/json" -d '{ "action":"create_payout", "amount":1500, "currency_code":"USD", "country_code":"US", "bank_account":{ "institution_number":"021", "transit_number":"00001", "account_number":"1234567890", "account_holder_name":"Acme Inc" } }'
```

```json
{ "success": true, "payout": { "id":"2b3c...", "amount":1500, "currency":"USD", "status":"pending", "external_id":"moneto_8821" } }
```

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

### Create a Subscription Plan

Source: https://mzzpay.io/developers/api/subscriptions

Creates a new recurring billing plan for a merchant.

```bash
curl -X POST "https://api.mzzpay.io/rest/v1/subscription_plans" -H "Authorization: Bearer <user_jwt>" -H "apikey: <publishable_key>" -H "Content-Type: application/json" -d '{ "merchant_id":"9b1c...", "name":"Premium Monthly", "amount":29, "currency":"USD", "interval":"month" }'
```

```json
[ { "id": "5e6f...", "amount": 29 } ]
```

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

### Initiate an Open Banking Payment

Source: https://mzzpay.io/developers/api/open-banking

Create a Payment Initiation Request (PIS) to receive a redirect URL for customer authorisation.

```bash
curl -X POST https://api.mzzpay.io/v1/open-banking/payments \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4999,
    "currency": "gbp",
    "country": "GB",
    "reference": "INV-2026-0418",
    "return_url": "https://shop.example.com/thanks",
    "bank": "monzo"
  }'
```

```json
{
  "id": "obp_9QkLm2",
  "status": "awaiting_authorisation",
  "redirect_url": "https://obp.mzzpay.io/auth/9QkLm2",
  "expires_at": "2026-04-22T12:00:00Z"
}
```

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

### GET /payments

Source: https://mzzpay.io/developers/api-reference

Retrieve a list of all payments processed through the account.

```APIDOC
## GET /payments

### Description
List all payments associated with the account.

### Method
GET

### Endpoint
/payments
```

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

### Create a Payment Link

Source: https://mzzpay.io/developers/api/payment-links

Create a new payment link by inserting a row into the payment_links table.

```bash
curl -X POST "https://api.mzzpay.io/rest/v1/payment_links" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "apikey: <publishable_key>" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{
    "merchant_id": "9b1c...",
    "amount": 49.99,
    "currency": "GBP",
    "description": "Premium plan — annual",
    "payment_method": "all",
    "url": "https://checkout.mzzpay.io/?link=PLACEHOLDER"
  }'
```

```json
[ { "id": "ee11...", "url": "https://checkout.mzzpay.io/?link=ee11...", "status": "active" } ]
```

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

### GET /rest/v1/ledger_entries

Source: https://mzzpay.io/developers/api/wallets

Retrieves the double-entry ledger records for transactions.

```APIDOC
## GET /rest/v1/ledger_entries

### Description
The double-entry ledger. Every transaction (payment, refund, payout, fee, FX, adjustment) is recorded as a credit/debit pair.

### Method
GET

### Endpoint
/rest/v1/ledger_entries

### Parameters
#### Query Parameters
- **transaction_id** (uuid) - Optional - Filter to a single source transaction
- **currency** (string) - Optional - Filter by ledger currency
- **entry_type** (string) - Optional - credit | debit

### Response
#### Success Response (200)
- **id** (string) - Entry ID
- **transaction_id** (uuid) - Source transaction ID
- **account_id** (string) - Account ID
- **currency** (string) - Currency
- **entry_type** (string) - credit or debit
- **amount** (number) - Transaction amount
- **created_at** (string) - Timestamp

#### Response Example
[
  {
    "id": "btx_001",
    "transaction_id": "9b1c...",
    "account_id": "1a2b...",
    "currency": "USD",
    "entry_type": "credit",
    "amount": 50.00,
    "created_at": "2026-04-22T10:00:00Z"
  }
]
```

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

### GET /rest/v1/crypto_transactions

Source: https://mzzpay.io/developers/api/payouts

List payouts by filtering for withdrawal transactions.

```APIDOC
## GET /rest/v1/crypto_transactions

### Description
Filter tx_type=eq.withdrawal to scope to payouts.

### Method
GET

### Endpoint
/rest/v1/crypto_transactions

### Parameters
#### Query Parameters
- **tx_type** (string) - Required - eq.withdrawal
- **status** (string) - Optional - eq.pending | eq.complete | eq.failed

### Response
#### Success Response (200)
- **array** (object) - List of payout transactions
```

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

### Configure API Key

Source: https://mzzpay.io/developers/quick-start

Set the sandbox API key as an environment variable for authentication.

```bash
# Your sandbox key starts with sk_test_
export MZZPAY_API_KEY="sk_test_your_key_here"
```

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

### List Products

Source: https://mzzpay.io/developers/api/products

Retrieves the merchant's catalog, supporting filters like is_active.

```bash
curl "https://api.mzzpay.io/rest/v1/products?is_active=eq.true" -H "Authorization: Bearer <user_jwt>" -H "apikey: <publishable_key>"
```

```json
[ { "id": "6f7a...", "name": "Premium Plan", "price": 249 } ]
```

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

### GET /rest/v1/invoices

Source: https://mzzpay.io/developers/api/invoices

List invoices filtered by customer, status, or date.

```APIDOC
## GET /rest/v1/invoices

### Description
Filter by customer, status, or date. Authenticated merchants see all of theirs; anon publishable key only sees sent/overdue.

### Method
GET

### Endpoint
/rest/v1/invoices

### Parameters
#### Query Parameters
- **status** (string) - Optional - eq.draft | eq.sent | eq.paid | eq.overdue | eq.void
- **customer_id** (uuid) - Optional - Filter by customer

### Response
#### Success Response (200)
- **id** (string) - Invoice ID
- **amount** (number) - Invoice amount
- **status** (string) - Invoice status

#### Response Example
[ { "id": "7c8d...", "amount": 249, "status": "sent" } ]
```

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

### POST /rest/v1/products

Source: https://mzzpay.io/developers/api/products

Creates a new product in the merchant's catalog.

```APIDOC
## POST /rest/v1/products

### Description
Insert a row into public.products.

### Method
POST

### Endpoint
/rest/v1/products

### Parameters
#### Request Body
- **merchant_id** (uuid) - Required - Owning merchant
- **name** (string) - Required - Display name
- **price** (number) - Optional - Major units. Default 0
- **currency** (string) - Optional - Default 'USD'
- **stock** (integer) - Optional - Default 0
- **product_type** (string) - Optional - physical | digital | subscription
- **sku** (string) - Optional - Merchant SKU
- **image_url** (string) - Optional - Hero image URL
- **is_active** (boolean) - Optional - Default true

### Request Example
{ "merchant_id":"9b1c...", "name":"Premium Plan", "price":249, "currency":"USD" }

### Response
#### Success Response (200)
- **id** (string) - Product ID
- **name** (string) - Product name
- **price** (number) - Product price
- **is_active** (boolean) - Active status

#### Response Example
[ { "id": "6f7a...", "name": "Premium Plan", "price": 249, "is_active": true } ]
```

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

### Create a Customer

Source: https://mzzpay.io/developers/api/customers

Insert a new customer record. Requires a valid merchant_id owned by the authenticated user.

```bash
curl -X POST "https://api.mzzpay.io/rest/v1/customers" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "apikey: <publishable_key>" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{
    "merchant_id": "9b1c2d3e-...",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe"
  }'
```

```json
[
  {
    "id": "8a2b1c3d-...",
    "merchant_id": "9b1c2d3e-...",
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "billing_address": null,
    "created_at": "2026-04-22T10:00:00Z",
    "updated_at": "2026-04-22T10:00:00Z"
  }
]
```

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

### GET /rest/v1/transactions

Source: https://mzzpay.io/developers/api/payments

Query the transactions table directly using PostgREST syntax.

```APIDOC
## GET /rest/v1/transactions

### Description
Query the transactions table directly via PostgREST. Apply filters with PostgREST query syntax.

### Method
GET

### Endpoint
/rest/v1/transactions

### Parameters
#### Query Parameters
- **select** (string) - Optional - Comma-separated columns. Default *
- **status** (string) - Optional - eq.completed, eq.pending, eq.failed, eq.refunded
- **order** (string) - Optional - Sort: created_at.desc
- **limit** (integer) - Optional - 1-1000 (Supabase default cap)

### Response
#### Success Response (200)
- **transactions** (array) - A list of transaction objects matching the query criteria
```

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

### Update a Product

Source: https://mzzpay.io/developers/api/products

Updates specific columns for a product identified by its ID.

```bash
curl -X PATCH "https://api.mzzpay.io/rest/v1/products?id=eq.6f7a..." -H "Authorization: Bearer <user_jwt>" -H "apikey: <publishable_key>" -H "Content-Type: application/json" -d '{ "price": 199 }'
```

```json
[ { "id": "6f7a...", "price": 199 } ]
```

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

### GET /rest/v1/payment_links

Source: https://mzzpay.io/developers/api/payment-links

Retrieves a list of payment links, optionally filtered by status.

```APIDOC
## GET /rest/v1/payment_links

### Description
List payment links, filterable by status to show only live links.

### Method
GET

### Endpoint
/rest/v1/payment_links

### Parameters
#### Query Parameters
- **status** (string) - Optional - eq.active | eq.inactive
- **order** (string) - Optional - e.g. created_at.desc

### Response
#### Success Response (200)
- **id** (string) - Link ID
- **amount** (number) - Link amount
- **status** (string) - Link status

#### Response Example
[ { "id": "ee11...", "amount": 49.99, "status": "active" } ]
```

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

### List or Search Customers

Source: https://mzzpay.io/developers/api/customers

Retrieve a list of customers with optional filtering and projection.

```bash
curl "https://api.mzzpay.io/rest/v1/customers?select=id,email,created_at&order=created_at.desc&limit=20" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "apikey: <publishable_key>"
```

```json
[
  { "id": "8a2b...", "email": "jane@example.com", "created_at": "2026-04-22T10:00:00Z" }
]
```

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

### GET /payments/{id}

Source: https://mzzpay.io/developers/api-reference

Retrieve the details of a specific payment by its unique identifier.

```APIDOC
## GET /payments/{id}

### Description
Retrieve a specific payment record.

### Method
GET

### Endpoint
/payments/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the payment.
```

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

### POST /functions/v1/moneto-wallet

Source: https://mzzpay.io/developers/api/payouts

Initiate a fiat payout (USD/EUR/GBP) via Moneto. Settles T+1 for SEPA or T+2 for SWIFT.

```APIDOC
## POST /functions/v1/moneto-wallet

### Description
Initiate USD/EUR/GBP payout via Moneto. Settles T+1 SEPA / T+2 SWIFT.

### Method
POST

### Endpoint
/functions/v1/moneto-wallet

### Parameters
- **action** (string) - Required - Must be 'create_payout'
- **amount** (number) - Required - Major units
- **currency_code** (string) - Required - USD | EUR | GBP
- **country_code** (string) - Required - ISO-3166 alpha-2
- **bank_account** (object) - Required - { institution_number, transit_number, account_number, account_holder_name }
- **description** (string) - Optional - Statement reference

### Request Example
{ "action":"create_payout", "amount":1500, "currency_code":"USD", "country_code":"US", "bank_account":{ "institution_number":"021", "transit_number":"00001", "account_number":"1234567890", "account_holder_name":"Acme Inc" } }

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful
- **payout** (object) - The created payout object
```

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

### POST /payments

Source: https://mzzpay.io/developers/api/payments

Create and charge a customer for a one-off purchase.

```APIDOC
## POST /payments

### Description
Create and charge a customer for a one-off purchase.

### Method
POST

### Endpoint
https://api.mzzpay.io/v1/payments

### Parameters
#### Request Body
- **amount** (integer) - Required - Smallest currency unit (cents, pence, paise…)
- **currency** (string) - Required - ISO-4217 lowercase (usd, eur, gbp)
- **payment_method** (string) - Required - A pm_… token from Checkout.js or a saved method
- **capture** (boolean) - Optional - Default true. Set false for auth-only.
- **description** (string) - Optional - Shown on customer's statement.
- **metadata** (object) - Optional - Up to 50 keys, 500 chars each. Returned on every event.
- **customer_id** (string) - Optional - Attach to a saved customer for analytics.
- **statement_descriptor** (string) - Optional - Up to 22 chars, alphanumeric + space.
```

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

### Create a Payment

Source: https://mzzpay.io/developers/quick-start

Initiate a payment request using the Payments API.

```curl
curl -X POST https://api.mzzpay.io/v1/payments \
  -H "Authorization: Bearer $MZZPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "usd",
    "payment_method": "pm_card_visa",
    "description": "Order #1234"
  }'
```

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

### GET /v1/disputes

Source: https://mzzpay.io/developers/api/disputes

Retrieve a paginated list of disputes, optionally filtered by status or network.

```APIDOC
## GET /v1/disputes

### Description
Paginated list of disputes. Filter by status, network, or date range.

### Method
GET

### Endpoint
/v1/disputes

### Parameters
#### Query Parameters
- **status** (string) - Optional - Filter by needs_response, under_review, won, or lost.
- **network** (string) - Optional - Filter by visa, mastercard, amex, or discover.

### Response
#### Success Response (200)
- **object** (string) - The type of object returned.
- **data** (array) - List of dispute objects.
- **has_more** (boolean) - Indicates if there are more pages.

#### Response Example
{
  "object": "list",
  "data": [],
  "has_more": false
}
```

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

### Create an Invoice

Source: https://mzzpay.io/developers/api/invoices

Insert a new invoice record. Set status to 'sent' to publish the invoice immediately.

```bash
curl -X POST "https://api.mzzpay.io/rest/v1/invoices" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "apikey: <publishable_key>" \
  -H "Content-Type: application/json" \
  -H "Prefer: return=representation" \
  -d '{ "merchant_id":"9b1c...", "customer_email":"jane@example.com", "amount":249, "currency":"USD", "status":"sent", "due_date":"2026-05-22T00:00:00Z" }'
```

```json
[ { "id": "7c8d...", "status": "sent", "created_at": "..." } ]
```

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

### GET /rest/v1/accounts

Source: https://mzzpay.io/developers/api/wallets

Returns one accounts row per merchant and currency combination.

```APIDOC
## GET /rest/v1/accounts

### Description
Returns one accounts row per (merchant, currency) you transact in.

### Method
GET

### Endpoint
/rest/v1/accounts

### Parameters
#### Query Parameters
- **currency** (string) - Optional - eq.USD / eq.EUR / eq.GBP
- **select** (string) - Optional - Column projection

### Response
#### Success Response (200)
- **currency** (string) - Currency code
- **balance** (number) - Total balance
- **available_balance** (number) - Withdrawable balance
- **pending_balance** (number) - Settling balance

#### Response Example
[
  { "currency": "USD", "balance": 18425, "available_balance": 17505, "pending_balance": 1240 },
  { "currency": "EUR", "balance": 9820, "available_balance": 9410, "pending_balance": 410 }
]
```

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

### GET /rest/v1/transactions

Source: https://mzzpay.io/developers/api/3d-secure

Polls for the outcome of a transaction after the cardholder completes the 3D Secure challenge.

```APIDOC
## GET /rest/v1/transactions

### Description
Polls the transaction status to verify if the 3D Secure challenge was completed successfully.

### Method
GET

### Endpoint
/rest/v1/transactions?id=eq.{id}&select=id,status,processor_raw_response

### Parameters
#### Query Parameters
- **id** (string) - Required - The transaction ID to filter by
- **select** (string) - Required - Fields to return

### Response
#### Success Response (200)
- **id** (string) - Transaction ID
- **status** (string) - Current status (e.g., 'completed')
- **processor_raw_response** (object) - Contains 3DS details like eci, cavv, and ds_transaction_id

#### Response Example
[
  {
    "id": "9b1c...",
    "status": "completed",
    "processor_raw_response": {
      "three_ds": { "required": true, "eci": "05", "cavv": "AAABBg...", "ds_transaction_id": "f4a83e..." }
    }
  }
]
```

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

### POST /functions/v1/crypto-pay

Source: https://mzzpay.io/developers/verification

Initiates a crypto payment.

```APIDOC
## POST /functions/v1/crypto-pay

### Description
Creates a crypto payment charge.

### Method
POST

### Endpoint
/functions/v1/crypto-pay

### Request Body
- **amount** (number) - Required
- **currency** (string) - Required
- **asset_id** (string) - Required
- **customer_email** (string) - Optional
- **return_url** (string) - Optional

### Response
- **success** (boolean)
- **charge_id** (string)
- **address** (string)
- **network** (string)
- **expires_at** (string)
```

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

### Create a payment endpoint

Source: https://mzzpay.io/developers/api/payments

The base endpoint for initiating a payment charge.

```http
POST https://api.mzzpay.io/v1/payments
```

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

### List Supported Banks

Source: https://mzzpay.io/developers/api/open-banking

Retrieve available Open Banking institutions for a specific country.

```bash
curl "https://api.mzzpay.io/v1/open-banking/banks?country=GB" \
  -H "Authorization: Bearer sk_test_your_key"
```

```json
{
  "object": "list",
  "data": [
    { "id": "monzo", "name": "Monzo", "logo": "...", "instant": true },
    { "id": "hsbc", "name": "HSBC UK", "logo": "...", "instant": true },
    { "id": "barclays", "name": "Barclays", "logo": "...", "instant": true }
  ]
}
```

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

### GET /v1/disputes/:id

Source: https://mzzpay.io/developers/api/disputes

Retrieve the current status, evidence checklist, and outcome of a specific dispute.

```APIDOC
## GET /v1/disputes/:id

### Description
Get the current status, evidence checklist, and outcome of a dispute.

### Method
GET

### Endpoint
/v1/disputes/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the dispute.

### Response
#### Success Response (200)
- **id** (string) - The dispute ID.
- **status** (string) - The current status of the dispute.
- **evidence_due_date** (string) - The deadline for submitting evidence.

#### Response Example
{
  "id": "dp_8MzQp",
  "status": "needs_response",
  "evidence_due_date": "2026-05-08T00:00:00Z"
}
```

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

### GET /rest/v1/fx_rates

Source: https://mzzpay.io/developers/api/fx

Queries the rate cache directly to retrieve historical exchange rate data.

```APIDOC
## GET /rest/v1/fx_rates

### Description
Query the rate cache directly via PostgREST. This is useful for displaying rate history charts or auditing settlement conversions.

### Method
GET

### Endpoint
/rest/v1/fx_rates

### Parameters
#### Query Parameters
- **base_currency** (string) - Optional - Filter by base currency (e.g., eq.usd)
- **quote_currency** (string) - Optional - Filter by quote currency (e.g., eq.eur)
- **order** (string) - Optional - Ordering parameter (e.g., fetched_at.desc)
- **limit** (integer) - Optional - Limit the number of results (default 1000)

### Response
#### Success Response (200)
- **base_currency** (string) - Base currency code
- **quote_currency** (string) - Quote currency code
- **rate** (number) - Exchange rate
- **source** (string) - Data source
- **fetched_at** (string) - Timestamp of the rate fetch

#### Response Example
[
  {
    "base_currency": "usd",
    "quote_currency": "eur",
    "rate": 0.9215,
    "source": "ecb",
    "fetched_at": "2026-04-22T10:00:03Z"
  }
]
```

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

### POST /functions/v1/moneto-wallet

Source: https://mzzpay.io/developers/verification

Performs Moneto wallet actions.

```APIDOC
## POST /functions/v1/moneto-wallet

### Description
Manages balance or payout actions for Moneto wallets.

### Method
POST

### Endpoint
/functions/v1/moneto-wallet

### Request Body
- **action** (string) - Required (balance|payout)
- **currency** (string) - Optional
- **amount** (number) - Optional
- **destination** (string) - Optional

### Response
- **success** (boolean)
- **balance** (number) - Optional
- **payout_id** (string) - Optional
- **status** (string)
```

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

### GET /rest/v1/customers

Source: https://mzzpay.io/developers/api/customers

Retrieves a list of customers visible to the authenticated merchant, with support for filtering and column projection.

```APIDOC
## GET /rest/v1/customers

### Description
Returns rows visible under RLS. Use ?email=ilike.*jane* for fuzzy search and select=id,email,... to project columns.

### Method
GET

### Endpoint
/rest/v1/customers

### Parameters
#### Query Parameters
- **select** (string) - Optional - Comma-separated column projection
- **email** (string) - Optional - PostgREST filter, e.g. eq.jane@example.com
- **order** (string) - Optional - e.g. created_at.desc
- **limit** (integer) - Optional - Max 1000 by default

### Response
#### Success Response (200)
- **data** (array) - List of customer objects
```

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

### POST /rest/v1/customers

Source: https://mzzpay.io/developers/verification

Creates a new customer record.

```APIDOC
## POST /rest/v1/customers

### Description
Adds a new customer to the database.

### Method
POST

### Endpoint
/rest/v1/customers

### Request Body
- **email** (string) - Required
- **full_name** (string) - Optional
- **phone** (string) - Optional
- **country** (string) - Optional
- **metadata** (object) - Optional

### Response
- **Inserted Customer row**
```

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

### Convert Currency Amount

Source: https://mzzpay.io/developers/api/fx

Performs a currency conversion using the latest cached mid-market rate.

```bash
curl -X POST https://api.mzzpay.io/functions/v1/fx-convert \
  -H "Authorization: Bearer <user_jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 100, "from": "usd", "to": "eur" }'
```

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

### GET /rest/v1/refunds

Source: https://mzzpay.io/developers/api/refunds

Query the refunds table. Filter by transaction, status, or date range using PostgREST operators.

```APIDOC
## GET /rest/v1/refunds

### Description
Query the refunds table. Filter by transaction, status, or date range using PostgREST operators.

### Method
GET

### Endpoint
/rest/v1/refunds

### Parameters
#### Query Parameters
- **transaction_id** (uuid) - Optional - eq.<id> to filter by source transaction
- **status** (string) - Optional - eq.completed, eq.pending, eq.failed
- **limit** (integer) - Optional - Default 1000 cap

### Response
#### Success Response (200)
- **refunds** (array) - List of refund objects

#### Response Example
[
  {
    "id": "8a2b1c3d-...",
    "transaction_id": "9b1c...",
    "amount": 25,
    "status": "completed",
    "created_at": "2026-04-22T10:14:00Z"
  }
]
```

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

### Create a Crypto Payout

Source: https://mzzpay.io/developers/api/payouts

Withdraw crypto assets to an external address via the Elektropay wallet endpoint.

```bash
curl -X POST "https://api.mzzpay.io/functions/v1/elektropay-wallet" -H "Authorization: Bearer <user_jwt>" -H "Content-Type: application/json" -d '{ "action":"withdrawal", "wallet_id":"1a2b...", "asset_id":"USDT_TRC20", "amount":250, "to_address":"TXYZ...abcd" }'
```

```json
{ "success": true, "transaction": { "id":"2b3c...", "tx_type":"withdrawal", "amount":250, "status":"pending" } }
```

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

### GET /v1/open-banking/payments/:id

Source: https://mzzpay.io/developers/api/open-banking

Retrieve the status of an existing Open Banking payment. It is recommended to use webhooks for production traffic instead of polling.

```APIDOC
## GET /v1/open-banking/payments/:id

### Description
Retrieve an Open Banking Payment. Poll for status.

### Method
GET

### Endpoint
/v1/open-banking/payments/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The payment ID

### Response
#### Success Response (200)
- **id** (string) - Payment ID
- **status** (string) - Current status
- **settled_at** (string) - Settlement timestamp
- **rail_reference** (string) - Rail reference identifier
```

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

### Subscription Object Structure

Source: https://mzzpay.io/developers/api/subscriptions

Represents a customer's enrollment in a specific subscription plan.

```json
{
  "id": "4d5e6f7a-...",
  "customer_id": "8a2b1c3d-...",
  "plan_id": "5e6f7a8b-...",
  "payment_method_id": "3c4d5e6f-...",
  "status": "active",
  "current_period_start": "2026-04-22T10:00:00Z",
  "current_period_end": "2026-05-22T10:00:00Z",
  "trial_end": null,
  "canceled_at": null
}
```

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

### Prorate Subscription Plan Change

Source: https://mzzpay.io/developers/api/subscriptions

Switches a subscription to a new plan mid-cycle and calculates the prorated credit or charge.

```bash
curl -X POST "https://api.mzzpay.io/functions/v1/prorate-subscription" -H "Authorization: Bearer <user_jwt>" -H "Content-Type: application/json" -d '{ "subscription_id":"4d5e...", "new_plan_id":"5e6f..." }'
```

```json
{ "success": true, "proration": { "old_plan":"Standard", "new_plan":"Premium", "days_remaining":17, "unused_credit":5.66, "new_charge":16.42, "prorated_amount":10.76, "is_upgrade":true, "currency":"USD" } }
```

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

### Create a Crypto Charge

Source: https://mzzpay.io/developers/api/crypto

Generates a deposit address for receiving funds. Requires a merchant_id or invoice_id to resolve the receiving account.

```curl
curl -X POST https://api.mzzpay.io/functions/v1/crypto-pay \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "mer_abc123",
    "asset_id": "USDT",
    "amount": 49.99,
    "currency": "USD",
    "reference": "order_42"
  }'
```

```json
{
  "success": true,
  "transaction_id": "c1a2b3c4-...",
  "deposit_address": "0x742d35Cc6634C0532925a3b8D697...",
  "asset_id": "USDT",
  "amount": 49.99,
  "currency": "USD",
  "expires_at": "2026-04-22T13:00:00Z"
}
```

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

### List Payment Links

Source: https://mzzpay.io/developers/api/payment-links

Retrieve a list of payment links, optionally filtered by status.

```bash
curl "https://api.mzzpay.io/rest/v1/payment_links?status=eq.active&order=created_at.desc" \
  -H "Authorization: Bearer <user_jwt>" \
  -H "apikey: <publishable_key>"
```

```json
[ { "id": "ee11...", "amount": 49.99, "status": "active" } ]
```

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

### POST /rest/v1/subscription_plans

Source: https://mzzpay.io/developers/api/subscriptions

Creates a new recurring subscription plan that can be reused across multiple customer subscriptions.

```APIDOC
## POST /rest/v1/subscription_plans

### Description
Insert a recurring plan. Plans are reusable across many subscriptions.

### Method
POST

### Endpoint
/rest/v1/subscription_plans

### Parameters
#### Request Body
- **merchant_id** (uuid) - Required - Owning merchant
- **name** (string) - Required - Display name
- **amount** (number) - Required - Price per period
- **currency** (string) - Required - ISO 4217
- **interval** (string) - Required - day | week | month | year
- **interval_count** (integer) - Optional - Default 1

### Request Example
{
  "merchant_id": "9b1c...",
  "name": "Premium Monthly",
  "amount": 29,
  "currency": "USD",
  "interval": "month"
}

### Response
#### Success Response (200)
- **id** (string) - Plan ID
- **amount** (number) - Plan amount

#### Response Example
[
  {
    "id": "5e6f...",
    "amount": 29
  }
]
```
Tokens:
Raw