Pay-Outs & Withdrawals

Two outbound money flows:

• Payouts — Company-initiated transfers. Dashboard-only with OTP.
• User Withdrawals — End-user requests. Auto-approved or merchant-approved.

Both deduct from merchant balance, execute on-chain, and send webhook notifications.

Rate Limits

Create a User Withdrawal

Always auto-approves and executes immediately.

POST /api/v1/public/user/withdrawal/create

Auth: apikey + x-api-secret (recommended)

const response = await axios.post(
  "https://pay.3pa-y.com/api/v1/public/user/withdrawal/create",
  {
    userId: "user-12345",
    walletAddress: "TN7oGaKhMfSfAwnVUiPNaEiGgRbRQGrain",
    amount: 50,
    currencyType: "USDT-TRC20"
  },
  { headers: { apikey: "your-api-key", "x-api-secret": "your-api-secret" } }
);
// response.data.data → { status: "completed", transactionHash: "abc123...", fee: 2, netAmount: 48 }

Validation Rules

• User must have a generated wallet
• User + merchant balance must cover the amount
• Minimum: 0.1 USDT, net amount after fee must be positive
• Address format: TRC20 starts with T, ERC20 starts with 0x

Fees

withdrawalFeePayer controls who pays: "merchant" or "user". Details: Settlement & Reconciliation

Withdrawal Request Management

For withdrawals that go through the approval flow.

List Pending Requests

GET /api/v1/public/withdrawal-requests?status=pending&page=1&limit=20

Auth: apikey

Approve

POST /api/v1/public/withdrawal-requests/{withdrawalId}/approve

Auth: apikey + x-api-secret (required)

Triggers blockchain execution immediately.

Reject

POST /api/v1/public/withdrawal-requests/{withdrawalId}/reject

Auth: apikey + x-api-secret (required)

Restores the pending amount to merchant balance.

// Approve example
await axios.post(
  `https://pay.3pa-y.com/api/v1/public/withdrawal-requests/${id}/approve`,
  {},
  { headers: { apikey: "your-api-key", "x-api-secret": "your-api-secret" } }
);

x-api-secret is required for approve/reject — additional auth for money-moving operations.

Auto-Approve Settings

• Enabled + under threshold: 1 webhook (completed / failed)
• Disabled or over threshold: pending → merchant approves → 2 webhooks

Configure in Dashboard > Settings.

Webhook Notifications

Auto-approved (1 webhook): status: "completed" or "failed" with type: "withdrawal".

Manual approval (2 webhooks):

1. status: "pending" when created
2. status: "completed" / "failed" / "rejected" after merchant action

See Webhook Handling for payload structure and HMAC verification.

Get Payout Details

GET /api/v1/public/payout/get?id={withdrawalId}

Auth: apikey — read-only query for any payout/withdrawal.

Note: POST /payout/create is disabled — payouts are dashboard-only with 2FA.

Error Handling