Let a Player Cash Out

Cashing out moves a player's wallet balance to their own bank account. This is a push: wallet → bank account. It is same-account — you can only cash out a wallet to that same account's bank. It settles asynchronously over the bank rail.

Acting for the player

The source is the player's account (source_account), so the cash-out is performed as the player (control of source). Because you onboarded the player, you act on their behalf from your own Secret Key token — the source account (the player) is the actor. Pathly authorizes the call through the onboarding relationship — a merchant may only act for accounts it onboarded.

Verification required

The player must be KYX-verified (status: active). Pathly rejects a push to a bank from an unverified account with 422. See Create & verify a player.

This KYX gate is enforced by default but can be waived per merchant: an admin (or the onboarding partner) may grant the merchant the KYX Cash-Out Exemption capability (kyx-cashout-exemption), after which the merchant and the players it onboarded may cash out without being KYX-verified. Use with care — it relaxes a compliance control.

The player must have a bank account on file (type: "bank-account", added as in Fund a wallet). The source wallet is addressed by the player's account id (no lookup needed); the destination bank is addressed by its payment-method id — fetch it with GET /payment-methods?accountId=<player>&type=bank-account. Then create the transfer:

curl -i -X POST \
  https://sandbox-api.pathly.io/transfers \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cashout_2026-06-25_peter_03' \
  -d '{
    "source_account": "5b3f0c2e-1d4a-4e8b-9c7a-2f6d8e0a1b22",
    "destination_payment_method": "<PLAYER_BANK_PAYMENT_METHOD_ID>",
    "amount": 8000,
    "currency": "USD",
    "reference": "cash out"
  }'

source_account is the player's account (its USD wallet); destination_payment_method is the player's bank account. Both belong to the player — you can only push a wallet out to that same account's bank — and the source account (the player) is the actor (you act on their behalf because you onboarded them).
Pathly infers the push rail from the destination instrument (wallet → bank).
amount is in the smallest currency unit (cents) and must not exceed the wallet's available balance.
The Idempotency-Key header is required.

For the full transfer request and response, see the Create a transfer API reference.

Response

POST /transfers is a command and returns no body. A cash-out involves a bank leg that is still settling, so the response is 202 Accepted; the Location header carries the new transfer's path:

HTTP/1.1 202 Accepted
Location: /transfers/0a9b8c7d-...

Read the result from the Location header with GET /transfers/{id}, and/or subscribe to the transfer.* webhooks. The wallet is debited and the transfer is born pending, then dispatched to the bank, then settled when funds land — or returned if the bank rejects it (e.g. a closed account), in which case the debit is reversed. Track the outcome with transfer.settled / transfer.returned / transfer.failed webhooks (next). For the full retrieval response, see the Get a transfer API reference.

Let a Player Cash Out

Response​

Response