Kispay Developer Doc

Payouts & Withdrawal Integration

Merchants can initiate withdrawals (B2C payouts) to customer accounts via supported channels like Telebirr, CBE Birr.

Initiate Customer Withdrawal

Initiate a withdrawal request from the system using the endpoint below.

Endpoint


 POST /api/checkout/withdrawal/withdrawal-initiate

Headers

Header	Value
Content-Type	`application/json`
x-api-key	`your_api_key_here`
Authorization	`Bearer your_session_token` (Optional)

Request Body

withdrawal Request


{
  "amount": 500.00,
  "currency": "ETB",
  "channel": "TELEBIRR",
  "customerAccountIdentifier": "+251912345678",
  "customerName": "Jane Doe",
  "customerEmail": "jane@example.com",
  "withdrawal_requestID": "WD-REQ-12345",
  "provider": "TELEBIRR"
}

Field Descriptions

Field	Type	Required	Description
amount	Double	Yes	Withdrawal amount (must be positive)
currency	String	Yes	Currency code (e.g., ETB, USD)
channel	String	Yes	Payment channel (e.g., TELEBIRR, CBE_BIRR, AWASH)
customerAccountIdentifier	String	Yes	Customer phone number or bank account
customerName	String	No	Customer full name
customerEmail	String	No	Customer email address
withdrawal_requestID	String	Yes	Your unique withdrawal reference (max 100 chars)
provider	String	No	B2C provider (TELEBIRR or CBE_BIRR). Defaults to TELEBIRR

• The withdrawal_requestID must be unique per merchant.
• Duplicate withdrawal_requestID will return a 409 Conflict error.
• Ensure sufficient balance in your merchant account before initiating a withdrawal.

Response (201 Created)

Success Response


{
  "status": 201,
  "message": "withdrawal request created",
  "data": {
    "id": "7fa85f64-8899-4562-c4fc-3d974g77bga7",
    "merchantId": "merchant-uuid",
    "amount": 500.00,
    "fee": 10.00,
    "netAmount": 490.00,
    "currency": "ETB",
    "channel": "TELEBIRR",
    "status": "PENDING",
    "withdrawalReference": "WR-20251218-1234",
    "withdrawal_requestID": "WD-REQ-12345",
    "customerAccountIdentifier": "+251912345678",
    "customerName": "Jane Doe",
    "customerEmail": "jane@example.com",
    "requestedAt": "2025-12-18T09:24:20Z",
    "processedAt": null,
    "failureReason": null,
    "transactionReference": null,
    "hasBeenRetried": false
  }
}

Withdrawal Status Values

PENDING - Withdrawal initiated, awaiting approval/processing
APPROVED - Withdrawal approved by system
PROCESSING - Withdrawal being processed by payment provider
COMPLETED - Withdrawal successfully completed
FAILED - Withdrawal failed
DECLINED - Withdrawal declined by admin

Get Withdrawal Balance

Check available balance for withdrawals.

Endpoint


 GET /api/checkout/withdrawal/total-balance

Header:


x-api-key: your_api_key_here

Response (200 OK)

Success Response


{ 
  "status": 200, 
  "message": "Balance retrieved successfully", 
  "data": [ 
    { 
      "channel": "TELEBIRR", 
      "currency": "ETB", 
      "availableBalance": 10000.00, 
      "reservedBalance": 500.00, 
      "totalBalance": 10500.00 
    }, 
    { 
      "channel": "CBE_BIRR", 
      "currency": "ETB", 
      "availableBalance": 5000.00, 
      "reservedBalance": 0.00, 
      "totalBalance": 5000.00 
    } 
  ] 
}

Response (409 Conflict - Insufficient Funds)

Error Response


{ 
  "status": 409, 
  "message": "insufficient amount", 
  "data": null, 
  "timestamp": "2025-12-05T06:00:00.000+00:00" 
}

Response (400 Bad Request)

Error Response


{ 
  "status": 400, 
  "message": "request failed", 
  "data": null, 
  "timestamp": "2025-12-05T06:00:00.000+00:00" 
}

Verify Withdrawal by Reference

Endpoint


 GET /api/checkout/withdrawal/verify/{withdrawal_requestID}

Header:


x-api-key: your_api_key_here

Response (200 OK):

Success Response


{ 
  "status": 200, 
  "message": "Withdrawal found", 
  "data": { 
    "id": "7fa85f64-8899-4562-c4fc-3d974g77bga7", 
    "status": "COMPLETED", 
    "amount": 500.00, 
    "fee": 10.00, 
    "netAmount": 490.00, 
    "withdrawal_requestID": "WD-REQ-12345", 
    "transactionReference": "TELEBIRR-TXN-67890", 
    "processedAt": "2025-12-18T09:30:45Z" 
  } 
}

Need Help?

For questions about transaction management and reports:

Developer Support: developers@kispay.et
Merchant Portal: https://merchant.kispay.et
API Documentation: Error Codes Guide

Pro Tip: Use the Merchant Portal for manual reviews and the API for automated reporting and integration with your business systems.