💳 Merchant Endpoints

Welcome to the External Merchant API.

Use this documentation to securely interact with your merchant account, manage balances, and create payouts.

---

🔐 Authentication

All requests must include an API key in the headers:

X-API-Key: your_api_key

⚠️ If the API key is restricted by IP addresses, requests will only be accepted from those IPs.

---

📚 Endpoints

---

💰 Get Merchant Balance

GET /api/v1/external/merchants/balance

Retrieve the current balance of the merchant across all currencies.

✅ Response

{
  "balances": [
    {
      "currency_code": "USDT",
      "amount": 1000.50,
      "symbol": "$",
      "is_primary": true
    }
  ],
  "primary_currency": {
    "code": "USDT",
    "symbol": "$",
    "name": "Tether USD"
  }
}

---

📊 Get Payout Counts by Status

GET /api/v1/external/merchants/payouts/count-by-status

Returns the number of payouts grouped by their status.

✅ Response

{
  "counts": {
    "pending": 5,
    "completed": 120,
    "rejected": 2
  }
}

---

🔎 Get Payout Details

GET /api/v1/external/merchants/payouts/{payout_id}

Get full details of a specific payout by its ID.

✅ Response

{
  "id": "c84b40fe-6158-4f18-a32d-6429522c6393",
  "usdt_amount": 500.00,
  "status": "completed",
  "transaction_hash": "0x1234567890abcdef",
  "recipient_data": {
    "bank_account": "1234567890"
  }

---

📜 List Payouts

GET /api/v1/external/merchants/payouts

Returns a paginated list of all payouts.

🧾 Query Parameters (optional)

Parameter	Type	Description
status	string	Filter by payout status
start_date	string	ISO 8601 format start date
end_date	string	ISO 8601 format end date
skip	int	Number of items to skip
limit	int	Number of items to return

✅ Response

{
  "items": [
    {
      "id": "c84b40fe-6158-4f18-a32d-6429522c6393",
      "usdt_amount": 500.00,
      "status": "completed",
      "created_at": "2023-06-18T10:15:30Z"
    }
  ],
  "total": 122,
  "skip": 0,
  "limit": 20
}

---

✏️ Create a Payout

POST /api/v1/external/merchants/payouts

Creates a new payout request to a recipient.

📦 Request Body

{
  "payment_method_id": "b2c3d4e5-f6a7-8b9c-0d1e",
  "usdt_amount": 500.00,
  "recipient_data": {
    "bank_account": "1234567890",
    "bank_name": "Example Bank"
  }
}

✅ Success Response

{
  "id": "e29b9e3e-3d1c-4c5f-a5f7-9876543210ab",
  "usdt_amount": 500.00,
  "status": "pending",
  "recipient_data": {
    "bank_account": "1234567890",
    "bank_name": "Example Bank"
  },
  "created_at": "2025-06-20T14:22:00Z"
}

❌ Error Response

{
  "detail": "Insufficient funds for payout"
}

---

🛠 Need Help?

If you have questions or want to request access, please contact our support team.

---

📁 Хочешь, я подготовлю Markdown-файлы в структуре /docs/api для GitBook или GitHub Pages?