💷Payout (Withdrawal) Integration

This document describes how to integrate Xixapay Payout API to transfer funds from your platform to Nigerian bank accounts. 🔐 Authentication

All payout requests to Xixapay require API credentials.

Required Headers

Header	Value
api-key	Your Xixapay API Key
Authorization	Bearer {XIXAPAY_SECRET_KEY}
Content-Type	application/json

📍 Payout Endpoint

POST https://api.xixapay.com/api/v1/transfer

📦 Payout Request Payload (JSON)

{
  "businessId": "string",
  "amount": 0,
  "bank": "string",
  "accountNumber": "string",
  "narration": "string"
}

Field Description

Field	Type	Required	Description
businessId	string	✅	Xixapay business ID
amount	number	✅	Amount to transfer (NGN)
bank	string	✅	Bank code or bank name
accountNumber	string	✅	10-digit Nigerian account number
narration	string	❌	Transfer narration

Example Payout Request

{
  "businessId": "BUS_9f8e7d6c",
  "amount": 25000,
  "bank": "058",
  "accountNumber": "0123456789",
  "narration": "Wallet withdrawal"
}

---

🏦 Bank Verification (Recommended)

Before initiating a payout, verify bank details.

Endpoint

POST https://api.xixapay.com/api/verify/bank

Request Body

{
  "bank": "058",
  "accountNumber": "0123456789"
}

---

Verification Response (Example)

{
  "status": "success",
  "AccountName": "JOHN DOE",
  "BankName": "Guaranty Trust Bank"
}

⚠️ Always verify account details before sending a payout.

---

✅ Successful Payout Response

{
  "status": "success",
  "message": "Transfer queued successfully",
  "reference": "XIXA_98374839"
}

---

❌ Failed Payout Response

{
  "status": "failed",
  "message": "Insufficient wallet balance"
}

🔄 Recommended Payout Flow

1. Fetch supported banks

2. Verify bank account

3. Deduct user balance (lock row)

4. Initiate Xixapay payout

5. Store provider response

6. Mark payout as success or failed

7. Refund on failure if required

🏦 Get Supported Banks

Endpoint

GET https://api.xixapay.com/api/get/banks

---

Example Response

{
  "status": "success",
  "data": [
    {
      "bankName": "Access Bank",
      "bankCode": "044"
    },
    {
      "bankName": "GTBank",
      "bankCode": "058"
    }
  ]
}

---

🔐 Security Best Practices

• Store API keys securely

• Never expose secret keys on frontend

• Validate payout amounts server-side

• Implement idempotency using reference

• Log and monitor failed payouts

---

📌 Notes

• All amounts are in NGN

• Account number must be 10 digits

• Payouts are instant

---