API Documentation

🚀 Getting Started

🌍 IP Whitelist

📋 Copycurl -4 -s https://api.ipify.org

Multiple server IP addresses may be added to the same API key. Each API key has its own independent whitelist.

🔐 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",
    "redirect_url": "https://merchant.example/payment/return"
}

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

Both responses use HTTP 201 Created.

✅ 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://cashwanna.com/checkout/Xy7Qp2LmN8vR4tKc9WbZ3aHs6DfJ1eGu",
        "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

closed: the provider closed or the customer cancelled the payment. expired: the payment window ended (orders expired by the timer do not send a webhook; poll this endpoint).

💰 Get Balance

✅ Response

📋 Copy{
    "success": true,
    "data": {
        "balance": "1500.00",
        "bonus_balance": "50.00",
        "available_balance": "1400.00",
        "on_hold": "100.00",
        "currency": "USD"
    }
}

on_hold is part of balance (reserve or admin hold) but cannot be paid out or withdrawn. Payouts can use up to available_balance.

📋 Get PayIns

✅ Response

📋 Copy{
    "success": true,
    "data": {
        "total": 45,
        "payins": [
            {
                "id": 123,
                "order_no": "API_1706000000_abc123",
                "merchant_order_no": "MCH_1706000000_xyz789",
                "pay_way": "cashapp",
                "amount": "100.00",
                "real_amount": "100.00",
                "fee": "11.00",
                "net": "89.00",
                "status": "success",
                "cashier_url": "https://provider.example/checkout/xxx",
                "created_at": "2026-01-15 10:00:00",
                "success_time": "2026-01-15 10:05:00",
                "expire_time": "2026-01-15 12:00:00"
            }
        ]
    }
}

📋 Get Payouts

✅ Response

📋 Copy{
    "success": true,
    "data": {
        "total": 12,
        "payouts": [
            {
                "id": 456,
                "payout_id": 456,
                "transaction_id": "POU-123456",
                "amount": "50.00",
                "fee": "3.50",
                "total_deducted": "53.50",
                "pay_way": "chime_payout3",
                "recipient": "$ExampleTag",
                "status": "approved",
                "rejection_reason": null,
                "reason": null,
                "needs_review": false,
                "invoice_number": "INV-20260906-000456",
                "completion_image": "https://proof.provider.example/photo/abc.jpg",
                "created_at": "2026-09-06 12:49:35",
                "approved_at": "2026-09-06 12:52:00",
                "completed_at": "2026-09-06 12:52:00"
            }
        ]
    }
}

📊 Payout Status Values

completion_image is a full URL to the payment proof (or null). reason explains a failure (provider message or our reason) or why the payout needs review. needs_review is true while an automatic payout is waiting for a manual check by our team; the money is not refunded automatically in that case.

📊 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,
        "merchant_no": "MCH_6650A1B2C3D4E",
        "name": "Example Merchant",
        "email": "merchant@example.com",
        "role": "merchant",
        "status": "active",
        "created_at": "2026-01-10 09:00:00"
    }
}

📤 Create Payout (API)

📤 Headers

📋 CopyContent-Type: application/json
X-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": "ach_payout",
    "recipient": {
        "accountNumber": "123456789",
        "routingNumber": "021000021"
    }
}

👤 Recipient fields per wallet

✅ Response (201 Created)

📋 Copy{
    "success": true,
    "data": {
        "payout_id": 456,
        "transaction_id": "POU-20260901-A1B2C3D4E5",
        "amount": "50.00",
        "fee": "3.50",
        "total_deducted": "53.50",
        "pay_way": "ach_payout",
        "recipient": "ACH ****6789 / 021000021",
        "status": "processing",
        "reason": null,
        "needs_review": false,
        "created_at": "2026-09-01 10:00:00",
        "message": "Payout sent to the provider. Final status comes by webhook."
    }
}

transaction_id format: POU-YYYYMMDD- + 10 characters.

Other responses

🔄 Merchant Webhooks

⚙️ Setup

📤 Request Headers

📋 CopyContent-Type: application/json
X-OESPay-Event-Id: 85d5cb6f-93a9-48d4-a2a7-20a9b271111e
X-OESPay-Timestamp: 1788264000
X-OESPay-Signature: 3f9a1c0e5b7d2a8f6c4e1b9d0a7f3e2c5b8d1a4f7e0c3b6a9d2f5e8b1c4a7d0e
User-Agent: Cashwanna-OESPay-Webhook/1.0

📥 PayIn Status Event

📋 Copy{
    "event_id": "550e8400-e29b-41d4-a716-446655440000",
    "event": "payin.status.updated",
    "created_at": "2026-09-07T16:57:02+00:00",
    "data": {
        "local_order_no": "MCH_1788800033_example",
        "order_id": "API_1788800033_example",
        "transaction_id": 37050,
        "status": "failed",
        "amount": "20.00",
        "real_amount": null,
        "fee": "3.10",
        "net": "16.90",
        "pay_way": "chime",
        "admin_notes": "Payment was not received from the provided account.",
        "success_time": null
    }
}

📤 Payout Status Event

📋 Copy{
    "event_id": "a3d38cb1-7a89-42dd-8fac-e2e017199edb",
    "event": "payout.status.updated",
    "created_at": "2026-09-07T17:02:00+00:00",
    "data": {
        "local_order_no": "PO_1788800120_aB3dE5gH",
        "order_id": 456,
        "transaction_id": "POU-20260907-A1B2C3D4E5",
        "status": "approved",
        "amount": "50.00",
        "fee": "3.50",
        "total_deducted": "53.50",
        "pay_way": "paypal_payout",
        "recipient": "customer@example.com",
        "rejection_reason": null,
        "reason": null,
        "needs_review": false,
        "invoice_number": "INV-20260907-ABC123",
        "completion_image": "https://proof.provider.example/photo/abc.jpg",
        "completed_at": "2026-09-07T17:01:30+00:00"
    }
}

Payout event: order_id is the payout id (same as payout_id in API responses). local_order_no is the provider order number for automatic payouts and null for manual ones. reason / needs_review as in GET /merchant/payouts. Payin event: order_id is the order_no from create-invoice, transaction_id the numeric order_id, local_order_no our internal order number.

When events are sent

• PayIn: when the status (or the admin note) changes.
• Payout: when the status, the rejection reason, the failure / review reason, the proof photo or the invoice number changes.
• Only for orders created with the API key that has the webhook enabled.
• PayIns that expire by the payment timer are closed in bulk and do not send a webhook: poll GET /check-status/{order_id} for open orders after their expires_at.

📋 Copy$expected = hash_hmac('sha256', $rawBody, $webhookSecret);
$valid = hash_equals($expected, $_SERVER['HTTP_X_OESPAY_SIGNATURE'] ?? '');

💳 Supported Wallets

PayIn

Payout

⚠️ Error Codes

Error bodies with a code look like {"success": false, "error": "...", "code": "PAYIN_001"}; PAYIN_007 from a preset-amount wallet also includes allowed_amounts, and PAYOUT_006 includes errors.

⏱️ Rate Limit

Only authenticated requests are counted. Successful responses carry:

Over the limit you receive 429 Too Many Requests with headers X-RateLimit-Limit, X-RateLimit-Remaining: 0 and Retry-After (seconds; no X-RateLimit-Reset on a 429), and this body:

📋 Copy{
    "success": false,
    "error": "Rate limit exceeded",
    "code": "RATE_001",
    "limit": 5000,
    "reset_in": 42
}