MarblePay API Reference

Base URL: https://api.marblepay.io/v1 Test URL: https://api-test.marblepay.io/v1

Authentication

All API requests require authentication using API keys in the Authorization header:

Authorization: Bearer mp_live_your_api_key_here

API Key Formats

Live mode: mp_live_...
Test mode: mp_test_...

Rate Limits

Live: 1000 requests/min per merchant
Test: 100 requests/min per merchant

Core Resources

1. Checkout Sessions

Create Checkout Session

POST /v1/checkout/sessions

Request Body:

{
  "amount": 250000,
  "currency": "NGN",
  "settleCurrency": "USDC",
  "chain": "base",
  "description": "Order #1234",
  "customerEmail": "customer@example.com",
  "metadata": {
    "orderId": "1234",
    "customField": "value"
  },
  "webhookUrl": "https://yourdomain.com/webhooks/marblepay",
  "redirectUrl": "https://yourdomain.com/payment/success",
  "expiryMinutes": 15
}

Response (201 Created):

{
  "id": "cs_abc123",
  "object": "checkout_session",
  "status": "pending",
  "amount": 250000,
  "currency": "NGN",
  "settleCurrency": "USDC",
  "chain": "base",
  "description": "Order #1234",
  "payTo": {
    "chain": "base",
    "asset": "USDC",
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "234.56",
    "qrCode": "data:image/png;base64,iVBORw0KG...",
    "networkFee": "0.05"
  },
  "expiresAt": "2025-11-05T15:30:00Z",
  "hostedCheckoutUrl": "https://checkout.marblepay.io/cs_abc123",
  "metadata": {
    "orderId": "1234",
    "customField": "value"
  },
  "createdAt": "2025-11-05T15:15:00Z"
}

Parameters:

Field	Type	Required	Description
`amount`	integer	Yes	Amount in smallest currency unit (e.g., kobo for NGN)
`currency`	string	Yes	Fiat currency code (`NGN`, `USD`)
`settleCurrency`	string	No	Settlement currency (`USDC`, `USDT`, `NGN`) - default: `USDC`
`chain`	string	Yes	Blockchain network (`ethereum`, `base`, `solana`)
`description`	string	Yes	Payment description
`customerEmail`	string	No	Customer email for receipt
`metadata`	object	No	Custom key-value data (max 50 keys)
`webhookUrl`	string	No	Override default webhook URL
`redirectUrl`	string	No	Redirect after payment success
`expiryMinutes`	integer	No	Quote expiry time (default: 15, max: 60)

Retrieve Checkout Session

GET /v1/checkout/sessions/:id

Response (200 OK):

{
  "id": "cs_abc123",
  "object": "checkout_session",
  "status": "confirmed",
  "payment": {
    "id": "pay_xyz789",
    "txHash": "0x8f3b7c...",
    "confirmations": 12,
    "confirmedAt": "2025-11-05T15:20:00Z"
  },
  "settlement": {
    "id": "stl_def456",
    "status": "completed",
    "amount": "234.56",
    "currency": "USDC"
  },
  // ... other fields
}

Status Values:

pending - Awaiting payment
paid - Payment detected, pending confirmations
confirmed - Payment confirmed
expired - Quote expired
refunded - Payment refunded
cancelled - Session cancelled

2. Payments

List Payments

GET /v1/payments

Query Parameters:

?limit=20
&startingAfter=pay_xyz789
&status=confirmed
&chain=base
&createdGte=2025-11-01
&createdLte=2025-11-05

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "pay_xyz789",
      "object": "payment",
      "sessionId": "cs_abc123",
      "txHash": "0x8f3b7c...",
      "chain": "base",
      "asset": "USDC",
      "amount": "234.56",
      "status": "confirmed",
      "confirmations": 12,
      "requiredConfirmations": 2,
      "detectedAt": "2025-11-05T15:17:00Z",
      "confirmedAt": "2025-11-05T15:20:00Z",
      "metadata": {}
    }
  ],
  "hasMore": true,
  "nextCursor": "pay_xyz789"
}

Retrieve Payment

GET /v1/payments/:id

Response (200 OK):

{
  "id": "pay_xyz789",
  "object": "payment",
  "sessionId": "cs_abc123",
  "txHash": "0x8f3b7c...",
  "chain": "base",
  "asset": "USDC",
  "amount": "234.56",
  "status": "confirmed",
  "confirmations": 12,
  "requiredConfirmations": 2,
  "fromAddress": "0x1234...",
  "toAddress": "0x742d...",
  "blockNumber": 12345678,
  "blockHash": "0xabc...",
  "detectedAt": "2025-11-05T15:17:00Z",
  "confirmedAt": "2025-11-05T15:20:00Z",
  "explorerUrl": "https://basescan.org/tx/0x8f3b7c...",
  "metadata": {}
}

3. Refunds

Create Refund

POST /v1/refunds

Request Body:

{
  "paymentId": "pay_xyz789",
  "amount": "234.56",
  "reason": "Customer requested refund",
  "refundAddress": "0x1234...",
  "metadata": {}
}

Response (201 Created):

{
  "id": "ref_ghi012",
  "object": "refund",
  "paymentId": "pay_xyz789",
  "amount": "234.56",
  "chain": "base",
  "asset": "USDC",
  "status": "pending",
  "refundAddress": "0x1234...",
  "txHash": null,
  "reason": "Customer requested refund",
  "createdAt": "2025-11-05T16:00:00Z",
  "metadata": {}
}

Refund Status:

pending - Awaiting processing
processing - Transaction submitted to blockchain
completed - Refund confirmed on-chain
failed - Refund failed (insufficient funds, invalid address, etc.)

Retrieve Refund

GET /v1/refunds/:id

List Refunds

GET /v1/refunds?paymentId=pay_xyz789&limit=20

4. Settlements

List Settlements

GET /v1/settlements

Query Parameters:

?limit=20
&startingAfter=stl_def456
&status=completed
&currency=USDC
&createdGte=2025-11-01

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "stl_def456",
      "object": "settlement",
      "paymentId": "pay_xyz789",
      "amount": "234.56",
      "currency": "USDC",
      "method": "crypto",
      "destination": "0x9876...",
      "status": "completed",
      "txHash": "0xdef...",
      "fee": "0.10",
      "netAmount": "234.46",
      "initiatedAt": "2025-11-05T15:25:00Z",
      "completedAt": "2025-11-05T15:27:00Z"
    }
  ],
  "hasMore": false
}

Retrieve Settlement

GET /v1/settlements/:id

5. Payouts (Merchant Withdrawals)

Create Payout

POST /v1/payouts

Request Body:

{
  "amount": "1000.00",
  "currency": "USDC",
  "destination": "0x9876...",
  "chain": "base",
  "description": "Weekly payout",
  "metadata": {}
}

Response (201 Created):

{
  "id": "po_jkl345",
  "object": "payout",
  "amount": "1000.00",
  "currency": "USDC",
  "chain": "base",
  "destination": "0x9876...",
  "status": "pending",
  "fee": "1.00",
  "netAmount": "999.00",
  "description": "Weekly payout",
  "txHash": null,
  "createdAt": "2025-11-05T17:00:00Z",
  "metadata": {}
}

Payout Status:

pending - Awaiting processing
processing - Transaction submitted
completed - Payout confirmed
failed - Payout failed

Retrieve Payout

GET /v1/payouts/:id

List Payouts

GET /v1/payouts?limit=20&status=completed

6. Balances

Get Balance

GET /v1/balance

Response (200 OK):

{
  "object": "balance",
  "available": {
    "USDC": "5430.20",
    "USDT": "1200.00",
    "NGN": "250000.00"
  },
  "pending": {
    "USDC": "234.56",
    "USDT": "0.00",
    "NGN": "0.00"
  },
  "reserved": {
    "USDC": "100.00",
    "USDT": "0.00",
    "NGN": "0.00"
  }
}

7. Webhooks

List Webhook Events

GET /v1/webhook_events

Query Parameters:

?limit=20
&type=payment.confirmed
&deliveryStatus=delivered
&createdGte=2025-11-01

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "id": "evt_mno678",
      "object": "webhook_event",
      "type": "payment.confirmed",
      "data": {
        "id": "pay_xyz789",
        "sessionId": "cs_abc123",
        // ... payment object
      },
      "deliveryAttempts": 1,
      "deliveryStatus": "delivered",
      "deliveredAt": "2025-11-05T15:20:05Z",
      "createdAt": "2025-11-05T15:20:00Z"
    }
  ],
  "hasMore": false
}

Retrieve Webhook Event

GET /v1/webhook_events/:id

8. Supported Assets

Get Supported Assets

GET /v1/assets

Response (200 OK):

{
  "object": "list",
  "data": [
    {
      "asset": "USDC",
      "name": "USD Coin",
      "chains": [
        {
          "chain": "ethereum",
          "contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "minAmount": "1.00",
          "maxAmount": "100000.00",
          "requiredConfirmations": 12,
          "avgConfirmationTime": "3 minutes"
        },
        {
          "chain": "base",
          "contractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
          "minAmount": "1.00",
          "maxAmount": "100000.00",
          "requiredConfirmations": 2,
          "avgConfirmationTime": "5 seconds"
        }
      ]
    },
    {
      "asset": "USDT",
      "name": "Tether USD",
      "chains": [
        {
          "chain": "ethereum",
          "contractAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
          "minAmount": "10.00",
          "maxAmount": "50000.00",
          "requiredConfirmations": 12,
          "avgConfirmationTime": "3 minutes"
        }
      ]
    }
  ]
}

Error Handling

Error Response Format

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_small",
    "message": "Amount must be at least 100 NGN",
    "param": "amount",
    "docUrl": "https://docs.marblepay.io/errors#amount_too_small"
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - API key lacks permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable

Error Types

authentication_error - API key invalid or missing
invalid_request_error - Request parameters invalid
rate_limit_error - Too many requests
resource_not_found - Resource doesn't exist
insufficient_funds - Merchant balance too low
blockchain_error - Blockchain RPC failure
compliance_error - Transaction blocked by compliance checks

Idempotency

Prevent duplicate requests using the Idempotency-Key header:

curl https://api.marblepay.io/v1/checkout/sessions \
  -H "Authorization: Bearer mp_live_..." \
  -H "Idempotency-Key: unique-key-123" \
  -d amount=250000 \
  -d currency=NGN

Keys expire after 24 hours. Use UUID v4 for uniqueness.

Pagination

List endpoints use cursor-based pagination:

{
  "object": "list",
  "data": [...],
  "hasMore": true,
  "nextCursor": "pay_xyz789"
}

Query Parameters:

limit - Number of items (default: 20, max: 100)
startingAfter - Cursor for next page
endingBefore - Cursor for previous page

Versioning

API version is in the URL path: /v1/...

Breaking changes will increment the version. Non-breaking changes are deployed without version changes.

SDKs

JavaScript/TypeScript

npm install @marblepay/node

import MarblePay from '@marblepay/node';

const marblepay = new MarblePay('mp_live_...');

const session = await marblepay.checkout.sessions.create({
  amount: 250000,
  currency: 'NGN',
  chain: 'base'
});

Python

pip install marblepay

import marblepay

marblepay.api_key = 'mp_live_...'

session = marblepay.CheckoutSession.create(
    amount=250000,
    currency='NGN',
    chain='base'
)

PHP

composer require marblepay/marblepay-php

<?php
require_once('vendor/autoload.php');

\MarblePay\MarblePay::setApiKey('mp_live_...');

$session = \MarblePay\CheckoutSession::create([
    'amount' => 250000,
    'currency' => 'NGN',
    'chain' => 'base'
]);

Next: Webhooks Guide | Compliance Guide

FilesExpand file tree

API_REFERENCE.md

Latest commit

History

API_REFERENCE.md

File metadata and controls

MarblePay API Reference

Authentication

API Key Formats

Rate Limits

Core Resources

1. Checkout Sessions

Create Checkout Session

Retrieve Checkout Session

2. Payments

List Payments

Retrieve Payment

3. Refunds

Create Refund

Retrieve Refund

List Refunds

4. Settlements

List Settlements

Retrieve Settlement

5. Payouts (Merchant Withdrawals)

Create Payout

Retrieve Payout

List Payouts

6. Balances

Get Balance

7. Webhooks

List Webhook Events

Retrieve Webhook Event

8. Supported Assets

Get Supported Assets

Error Handling

Error Response Format

HTTP Status Codes

Error Types

Idempotency

Pagination

Versioning

SDKs

JavaScript/TypeScript

Python

PHP