> ## 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.

# POST /v1/withdrawals — Submit a PayPal withdrawal request

> Submit a withdrawal request for a player's USD balance via PayPal. Requires authentication. Immediately deducts the amount from the player's balance.

Authenticated players with a sufficient USD balance can request a PayPal payout through this endpoint. The requested amount is deducted from the player's `money_balance_usd` immediately when the request is accepted. The actual PayPal transfer is processed asynchronously, and the withdrawal status progresses from `pending` to either `paid` or `failed`.

<Warning>
  The amount is deducted from the player's balance immediately when you call this endpoint, before the payout is processed by PayPal.
</Warning>

## Endpoint

```text theme={null}
POST /v1/withdrawals
```

**Authentication required.** Include the player's access token in the request header:

```text theme={null}
Authorization: Bearer <access_token>
```

## Request body

<ParamField body="amount_usd" type="number" required>
  The USD amount to withdraw. Must be a positive number and must not exceed the player's current `money_balance_usd`. Check the minimum withdrawal amount in `/v1/app-settings` before submitting.
</ParamField>

<ParamField body="paypal_email" type="string" required>
  A valid email address for the PayPal account that will receive the payment.
</ParamField>

## Example request

```bash theme={null}
curl -X POST https://playsmart-gateway-1w8ko864.uc.gateway.dev/v1/withdrawals \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 10.00,
    "paypal_email": "player@paypal.com"
  }'
```

## Response

### 201 Created

<ResponseField name="id" type="string">
  The unique identifier for this withdrawal request. Use this to track the status of the payout.
</ResponseField>

<ResponseField name="status" type="string">
  The initial status of the withdrawal. Always `"pending"` when the request is first created.
</ResponseField>

<ResponseField name="amount_usd" type="number">
  The USD amount requested in this withdrawal.
</ResponseField>

<ResponseField name="money_balance_usd_after" type="number">
  The player's remaining USD balance after the withdrawal amount has been deducted.
</ResponseField>

```json theme={null}
{
  "data": {
    "id": "64f1a2b3c4d5e6f7a8b9c0d1",
    "status": "pending",
    "amount_usd": 10.00,
    "money_balance_usd_after": 5.50
  }
}
```

## Error responses

| HTTP status         | Code            | Message                                  | Meaning                                                                                                                                                                 |
| ------------------- | --------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 UNAUTHORIZED`  | `UNAUTHORIZED`  | —                                        | The `Authorization` header is missing or the token is invalid or expired.                                                                                               |
| `400 BAD_REQUEST`   | `BAD_REQUEST`   | `invalid_payload`                        | The request body failed validation — for example, `amount_usd` is not a positive number or `paypal_email` is not a valid email. Check `details` for field-level errors. |
| `422 UNPROCESSABLE` | `UNPROCESSABLE` | `insufficient_balance_or_user_not_found` | The player's current USD balance is less than the requested `amount_usd`, or no player was found for the authenticated token.                                           |

```json theme={null}
{
  "error": {
    "code": "UNPROCESSABLE",
    "message": "insufficient_balance_or_user_not_found"
  }
}
```