API Documentation

🚀 Getting Started

🔐 Authentication

🔑 Permissions

Each API key can have one or more permissions. The all permission grants full access.

🌐 Base URL

All endpoints are relative to this base URL.

📝 Create Invoice

📤 Request

📋 Copy{
    "amount": 100.00,
    "pay_way": "cashapp",
    "customer_email": "customer@example.com",
    "customer_name": "John Doe"
}

Fee and net values vary according to the authenticated merchant's effective rate.

✅ Response (Auto Wallet)

📋 Copy{
    "success": true,
    "data": {
        "order_id": 123,
        "order_no": "API_1788264000_abc123",
        "amount": "99.99",
        "fee": "14.80",
        "net": "85.19",
        "pay_way": "applepay",
        "payment_url": "https://provider.example/checkout/xxx",
        "expires_at": "2026-09-01T12:00:00Z",
        "status": "processing"
    }
}

✅ Response (Manual Wallet)

📋 Copy{
    "success": true,
    "data": {
        "order_id": 124,
        "order_no": "API_1788264000_def456",
        "amount": "100.00",
        "fee": "10.30",
        "net": "89.70",
        "pay_way": "chime",
        "manual_code": "W6X-F1",
        "wallet_address": "$ExampleTag",
        "checkout_url": "https://chash.app/checkout/124",
        "expires_at": "2026-09-01T20:00:00Z",
        "status": "pending_manual"
    }
}

🔍 Check Order Status

✅ Response

📋 Copy{
    "success": true,
    "data": {
        "order_id": 123,
        "order_no": "API_1788264000_abc123",
        "amount": "99.99",
        "real_amount": "99.99",
        "fee": "14.80",
        "net": "85.19",
        "pay_way": "applepay",
        "payment_url": "https://provider.example/checkout/xxx",
        "manual_code": null,
        "status": "success",
        "created_at": "2026-09-01T10:00:00Z",
        "success_time": "2026-09-01T10:05:00Z",
        "expires_at": "2026-09-01T12:00:00Z"
    }
}

📊 Status Values

💰 Get Balance

✅ Response

📋 Copy{
    "success": true,
    "data": {
        "merchant_id": 123,
        "merchant_name": "My Store",
        "balance": "1500.00",
        "bonus_balance": "50.00"
    }
}

📋 Get PayIns

✅ Response

📋 Copy{
    "success": true,
    "data": {
        "total": 45,
        "payins": [
            {
                "id": 123,
                "order_no": "API_1706000000_abc123",
                "amount": "100.00",
                "fee": "11.00",
                "net": "89.00",
                "pay_way": "cashapp",
                "status": "success",
                "created_at": "2026-01-15 10:00:00"
            }
        ]
    }
}

📋 Get Payouts

✅ Response

📋 Copy{
    "success": true,
    "data": {
        "total": 12,
        "payouts": [
            {
                "id": 456,
                "transaction_id": "POU-123456",
                "amount": "50.00",
                "fee": "3.50",
                "pay_way": "paypal_payout",
                "recipient": "merchant@example.com",
                "status": "approved",
                "created_at": "2026-01-15 10:00:00"
            }
        ]
    }
}

📊 Get Stats

✅ Response

📋 Copy{
    "success": true,
    "data": {
        "balance": "1500.00",
        "bonus_balance": "50.00",
        "payin": {
            "total_count": 45,
            "total_amount": "5000.00",
            "total_success": "4500.00",
            "total_pending": "500.00",
            "total_failed": "0.00"
        },
        "payout": {
            "total_count": 12,
            "total_amount": "1200.00",
            "total_approved": "1100.00",
            "total_pending": "100.00",
            "total_failed": "0.00"
        }
    }
}

👤 Get Profile

✅ Response

📋 Copy{
    "success": true,
    "data": {
        "id": 12,
        "name": "Example Merchant",
        "email": "merchant@example.com",
        "status": "active"
    }
}

📤 Create Payout (API)

📤 Headers

📋 CopyX-API-Key: oes_your_api_key
X-API-Secret: sk_your_secret
Idempotency-Key: unique_request_id_123

📤 Request Body

📋 Copy{
    "amount": 50.00,
    "pay_way": "paypal_payout",
    "account_info": "merchant@example.com"
}

✅ Response (201 Created)

📋 Copy{
    "success": true,
    "data": {
        "payout_id": 456,
        "transaction_id": "POU-20260901-A1B2C3D4E5F6-1788264000",
        "amount": "50.00",
        "fee": "3.50",
        "total_deducted": "53.50",
        "pay_way": "paypal_payout",
        "recipient": "merchant@example.com",
        "status": "pending",
        "created_at": "2026-09-01 10:00:00"
    }
}

🔄 Merchant Webhooks

This section describes the planned OESPay-to-merchant callback format. It is separate from provider callbacks received by OESPay from BTCPay Server or other payout providers.

📤 Planned Request Headers

📋 CopyContent-Type: application/json
X-OESPay-Event-Id: evt_01JABCDEF123456789
X-OESPay-Timestamp: 1788264000
X-OESPay-Signature: sha256=generated_hmac_signature

📦 Planned Payout Event

📋 Copy{
    "event_id": "evt_01JABCDEF123456789",
    "event": "payout.approved",
    "created_at": "2026-09-01T10:00:00Z",
    "data": {
        "payout_id": 456,
        "transaction_id": "POU-20260901-A1B2C3D4E5F6-1788264000",
        "amount": "50.00",
        "fee": "3.50",
        "total_deducted": "53.50",
        "pay_way": "paypal_payout",
        "status": "approved"
    }
}

💳 Supported Wallets

PayIn

Payout

⚠️ Error Codes

⏱️ Rate Limit

If you exceed this limit, you will receive a 429 Too Many Requests response.