POST /v1/withdrawals — Submit a PayPal withdrawal request

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.

The amount is deducted from the player’s balance immediately when you call this endpoint, before the payout is processed by PayPal.

Endpoint

POST /v1/withdrawals

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

Authorization: Bearer <access_token>

Request body

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.

string

required

A valid email address for the PayPal account that will receive the payment.

Example request

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

string

The unique identifier for this withdrawal request. Use this to track the status of the payout.

string

The initial status of the withdrawal. Always "pending" when the request is first created.

number

The USD amount requested in this withdrawal.

number

The player’s remaining USD balance after the withdrawal amount has been deducted.

{
  "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.

{
  "error": {
    "code": "UNPROCESSABLE",
    "message": "insufficient_balance_or_user_not_found"
  }
}

Auth

App & Games

Economy

Events

POST /v1/withdrawals — Submit a PayPal withdrawal request

Endpoint

Request body

Example request

Response

201 Created

Error responses

​Endpoint

​Request body

​Example request

​Response

​201 Created

​Error responses

Endpoint

Request body

Example request

Response

201 Created

Error responses