Collect From User API

Partner collects money from user HooPay wallets. Requires user authorization via secure redirect flow.

User Authorization Required

All collections require explicit user authorization. After creating a collection request, you must redirect the user to the auth_url where they will log in and confirm with their PIN.

Authorization Flow

1 Partner creates collection request via API

2 HooPay returns auth_url (status: pending_authorization)

3 Partner redirects user to auth_url

4 User logs in to HooPay (if needed) and reviews collection details

5 User enters PIN to confirm OR cancels

6 HooPay processes collection and redirects to success_url or cancel_url

7 Webhook sent to partner with final status

Collect From User

POST /collect-from-user

Request Body

Parameter	Type	Required	Description
`partner_reference`	string	Yes	Unique collection ID for idempotency
`user_identifier`	string	Yes	User's email, phone, or 6-digit wallet ID
`amount`	string	Yes	Amount to withdraw (e.g., "100.00")
`success_url`	string	Yes	URL to redirect user after successful authorization
`cancel_url`	string	Yes	URL to redirect user if they cancel
`currency`	string	No	Currency code (default: USD)
`description`	string	No	Description shown to user during authorization
`destination_account`	string	No	Partner account identifier (e.g., MT5 account)
`metadata`	object	No	Additional data to store with collection

Example Request

cURL

curl -X POST https://hoopaywallet.com/api/v1/partner/collect-from-user \
  -H "Content-Type: application/json" \
  -H "X-API-Key: hpk_sandbox_your_key" \
  -H "X-Signature: your_hmac_signature" \
  -d '{
    "partner_reference": "WD-2025-001",
    "user_identifier": "310146",
    "amount": "200.00",
    "currency": "USD",
    "success_url": "https://yoursite.com/collection/success",
    "cancel_url": "https://yoursite.com/collection/cancel",
    "description": "Fund MT5 trading account",
    "destination_account": "MT5-12345678"
  }'

Response 201 Created

JSON

{
  "success": true,
  "message": "Collection request created. Awaiting user authorization.",
  "data": {
    "collection_id": "WD-xyz789abc",
    "partner_reference": "WD-2025-001",
    "amount": "200.00",
    "fee_amount": "0.00",
    "net_amount": "200.00",
    "currency": "USD",
    "status": "pending_authorization",
    "auth_url": "https://hoopaywallet.com/authorize/collection/abc123...",
    "auth_expires_at": "2025-11-29T12:10:00Z",
    "created_at": "2025-11-29T12:00:00Z"
  }
}

⚠️ Important: Redirect User to auth_url

After receiving the response, immediately redirect the user to the auth_url:

// JavaScript
window.location.href = response.data.auth_url;

// PHP
header("Location: " . $response->data->auth_url);
exit;

Other Endpoints

GET /collect-from-user/{reference}

Get collection status by HooPay reference or partner_reference

GET /collect-from-user

List all collections with optional filters (status, date range, user)

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

Cancel a collection (only works for pending_authorization or pending status)

GET /collect-from-user/stats

Get aggregated collection statistics

Collection Statuses

pending_authorization Awaiting user authorization at auth_url

pending Authorized, queued for processing

processing Currently being processed

completed Successfully transferred

failed Transfer failed (see failure_reason)

cancelled Cancelled by user or partner

expired Authorization link expired (10 min default)

refunded Funds returned to user

Security Considerations

🔐 Authorization Expiry

Auth URLs expire after 10 minutes by default. Configurable per partner.

🔒 PIN Lockout

5 failed PIN attempts locks authorization for 30 minutes.

🔄 Idempotency

Same partner_reference returns existing collection.

📧 Webhook Notifications

Receive real-time status updates via webhooks.

Previous Pay User

Next Refunds