> ## Documentation Index
> Fetch the complete documentation index at: https://doc.playsmart.api.dolly.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Request and track PayPal cash withdrawals in PlaySmart

> Guide to requesting a PayPal cash withdrawal through the PlaySmart API, including balance requirements and withdrawal status tracking.

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.

<Steps>
  <Step title="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`.
  </Step>

  <Step title="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.

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Track the withdrawal status">
    Every withdrawal moves through the following lifecycle:

    | Status    | Meaning                                                                                                                                      |
    | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
    | `pending` | The request has been created and the amount has been deducted from the player's balance. It is waiting for admin review.                     |
    | `paid`    | An admin has marked the withdrawal as paid. The player should receive the PayPal payment shortly.                                            |
    | `failed`  | An 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.
  </Step>
</Steps>

<Warning>
  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.
</Warning>

## Error handling

| HTTP status         | Error code                               | Meaning                                                                                                                             |
| ------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `422 UNPROCESSABLE` | `insufficient_balance_or_user_not_found` | The player's `money_balance_usd` is less than `amount_usd`, or the authenticated user could not be found.                           |
| `400 BAD_REQUEST`   | `invalid_payload`                        | The 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.                                                                                             |