Refunds API

Reverse completed pay-user and collect-from-user transactions. Use refunds to handle disputes, failed payouts, or customer requests.

⚠️ When to Use Refunds

Pay User Refund: User returned funds to your platform → reverse the wallet credit

Collection Refund: You couldn't process the payout → return funds to user's wallet

Note: Refunds are final. The original transaction will be marked as refunded.

Refund a Pay User Transaction

POST /pay-user/{reference_id}/refund

Reverse a completed pay-user transaction. This debits the amount from the user's wallet.

Request Body

Parameter	Type	Required	Description
`reference_id`	string	Yes	Your unique reference for this refund
`amount`	number	No	Partial refund amount (defaults to full amount)
`reason`	string	Yes	Reason for the refund

Example Request

cURL

curl -X POST https://hoopaywallet.com/api/v1/partner/pay-user/DEP-abc123/refund \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hpk_sandbox_your_key" \
  -H "X-Signature: your_hmac_signature" \
  -d '{
    "reference_id": "REFUND-001",
    "reason": "Customer requested refund"
  }'

Response 201 Created

JSON

{
  "success": true,
  "message": "Refund processed successfully.",
  "data": {
    "refund_id": "REF-X7K9M2P4Q1",
    "reference_id": "REFUND-001",
    "refund_type": "pay-user",
    "amount": 100.00,
    "fee_refunded": 0.00,
    "currency": "USD",
    "status": "completed",
    "reason": "Customer requested refund",
    "created_at": "2025-11-29T10:30:00Z",
    "completed_at": "2025-11-29T10:30:01Z"
  }
}

Refund a Collection

POST /collect-from-user/{reference}/refund

Return funds to a user's wallet when you couldn't complete their collection on your end.

Request Body

Parameter	Type	Required	Description
`reference_id`	string	Yes	Your unique reference for this refund
`reason`	string	Yes	Reason for the refund

Example Request

cURL

curl -X POST https://hoopaywallet.com/api/v1/partner/collect-from-user/WTH-xyz789/refund \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hpk_sandbox_your_key" \
  -H "X-Signature: your_hmac_signature" \
  -d '{
    "reference_id": "REFUND-002",
    "reason": "Bank transfer failed - invalid account"
  }'

Response 201 Created

JSON

{
  "success": true,
  "message": "Refund processed successfully. Funds returned to user wallet.",
  "data": {
    "refund_id": "REF-A1B2C3D4E5",
    "reference_id": "REFUND-002",
    "refund_type": "collection",
    "amount": 500.00,
    "fee_refunded": 5.00,
    "currency": "USD",
    "status": "completed",
    "reason": "Bank transfer failed - invalid account",
    "created_at": "2025-11-29T11:00:00Z",
    "completed_at": "2025-11-29T11:00:01Z"
  }
}

Get Refund Status

GET /refunds/{refund_id}

Check the status of a refund using either the HooPay refund ID or your reference ID.

Example Request

cURL

curl https://hoopaywallet.com/api/v1/partner/refunds/REF-X7K9M2P4Q1 \
  -H "X-API-Key: hpk_sandbox_your_key" \
  -H "X-Signature: your_hmac_signature"

List Refunds

GET /refunds

Get a paginated list of all your refunds with optional filters.

Query Parameters

Parameter	Type	Description
`type`	string	Filter by type: `pay-user`, `collect-from-user`
`status`	string	Filter by status: `pending`, `completed`, `failed`
`from_date`	date	Filter from date (YYYY-MM-DD)
`to_date`	date	Filter to date (YYYY-MM-DD)
`per_page`	integer	Results per page (1-100, default: 20)

Refund Statuses

pending Refund is being processed

processing Funds are being moved

completed Refund successful - funds returned

failed Refund failed - check failure_reason

Webhook Events

You'll receive webhooks for refund status changes:

Event	Description
`refund.completed`	Refund was successful
`refund.failed`	Refund failed

Previous Collect From User

Next Fees