Pay User API
Partner pays money to user wallets. Use this for payouts, refunds, rewards, and fund transfers.
✅ Recommended Flow: Verify Before Pay User
Step 1: User enters their HooPay wallet ID on your platform
Step 2: Call GET /wallets/{id}/verify to get account holder name
Step 3: Show name to user: "Pay to John D***?"
Step 4: User confirms → Call POST /pay-user
Verify Wallet (Pre-Pay-User Check)
GET
/wallets/{wallet_id}/verify
Verify a wallet ID exists and get the masked account holder name. Always call this before paying a user to prevent sending money to the wrong person.
Example Request
cURL
curl https://hoopaywallet.com/api/v1/partner/wallets/310146/verify \
-H "X-API-Key: hpk_sandbox_your_key" \
-H "X-Signature: your_hmac_signature"Response 200 OK
JSON
{
"success": true,
"data": {
"wallet_id": "310146",
"account_holder": "John D***",
"email_hint": "jo***@gm***.com",
"account_status": "active",
"verified": true,
"kyc_verified": true,
"can_receive_payments": true
}
}Error Response 404 Not Found
{
"success": false,
"error": {
"code": "WALLET_NOT_FOUND",
"message": "No wallet found with this ID."
}
}Pay User
POST
/pay-user
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
reference_id |
string | Yes | Unique identifier (idempotency key) |
user_wallet_id |
string | Yes | User's 6-digit HooPay wallet ID |
amount |
string | Yes | Amount to pay user (e.g., "100.00") |
currency |
string | Yes | Currency code (USD) |
description |
string | No | Description shown to user |
metadata |
object | No | Custom key-value pairs |
Example Request
cURL
curl -X POST https://hoopaywallet.com/api/v1/partner/pay-user \
-H "Content-Type: application/json" \
-H "X-API-Key: hpk_sandbox_your_key" \
-H "X-Signature: your_hmac_signature" \
-d '{
"reference_id": "DEP-001",
"user_wallet_id": "310146",
"amount": "50.00",
"currency": "USD",
"description": "Cashback reward"
}'Response 201 Created
JSON
{
"success": true,
"data": {
"payment_id": "pay_abc123xyz",
"reference_id": "DEP-001",
"amount": "50.00",
"currency": "USD",
"status": "pending_settlement",
"user_wallet_id": "310146",
"created_at": "2025-11-27T10:30:00Z"
}
}Get Pay User Status
GET
/pay-user/{reference_id}
Example Request
cURL
curl https://hoopaywallet.com/api/v1/partner/pay-user/DEP-001 \
-H "X-API-Key: hpk_sandbox_your_key" \
-H "X-Signature: your_hmac_signature"Pay User Statuses
pending_settlement
Pay user transaction received, awaiting ledger settlement
settled
Pay user transaction credited to user wallet
failed
Pay user transaction failed (user not found, etc.)
Idempotency
The reference_id acts as an idempotency key. If you send the same request twice,
the second request will return the existing pay-user transaction instead of creating a duplicate.