Skip to main content
Once a player has accumulated a positive money_balance_usd from coin conversions, they can request a PayPal payout directly from your app. Your game calls the withdrawal endpoint with the amount and the player’s PayPal email address, and your team reviews and processes the request in the admin panel.
1

Check the player's USD balance

The player’s current money_balance_usd is part of their profile. Before showing the withdrawal UI, confirm the balance is at or above the minimum withdrawal amount.To fetch the minimum withdrawal amount, call GET /v1/app-settings and read the minimum_withdrawal_amount field. Do not hardcode this value — it can change and varies by deployment.Only present the withdrawal option if:
  • money_balance_usd is greater than zero, and
  • money_balance_usd is at or above minimum_withdrawal_amount.
2

Submit the withdrawal request

Call POST /v1/withdrawals with the player’s Bearer token, the requested amount in USD, and the PayPal email address where payment should be sent.
curl -X POST https://playsmart-gateway-1w8ko864.uc.gateway.dev/v1/withdrawals \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 5.00,
    "paypal_email": "player@example.com"
  }'
A successful request returns HTTP 201 with the withdrawal record:
{
  "data": {
    "id": "64f3a2b1c8e4d10012ab3456",
    "status": "pending",
    "amount_usd": 5.00,
    "money_balance_usd_after": 2.50
  }
}
money_balance_usd_after is the player’s remaining balance after the deduction.
3

Track the withdrawal status

Every withdrawal moves through the following lifecycle:
StatusMeaning
pendingThe request has been created and the amount has been deducted from the player’s balance. It is waiting for admin review.
paidAn admin has marked the withdrawal as paid. The player should receive the PayPal payment shortly.
failedAn admin has marked the withdrawal as failed. The amount is not automatically refunded — contact your PlaySmart admin if a refund is needed.
You can surface this status in your app to keep players informed.
The amount_usd is deducted from the player’s money_balance_usd immediately when the withdrawal request is created, before it is reviewed or paid. If the withdrawal is later marked failed, the balance is not automatically restored.

​
Error handling

HTTP statusError codeMeaning
422 UNPROCESSABLEinsufficient_balance_or_user_not_foundThe player’s money_balance_usd is less than amount_usd, or the authenticated user could not be found.
400 BAD_REQUESTinvalid_payloadThe request body failed validation — for example, paypal_email is not a valid email address, or amount_usd is zero or negative.
401 UNAUTHORIZED—The Bearer token is missing or invalid.