Skip to main content

Fund a Wallet from a Bank Account

A player can fund their wallet directly from a bank account. This is a pull: bank account → wallet. It is same-account — a pull funds the player's own wallet from the player's own bank. The credit settles asynchronously once the bank clears the debit.

Acting for the player

The source_payment_method is the player's bank account, so this transfer 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 bank PM's owner (the player) is the actor. Pathly authorizes the call through the onboarding relationship — a merchant may only act for accounts it onboarded.

1. Add the bank account as a payment method​

Add it on the player's behalf with the optional account_id field (the player's account id) so the bank account is owned by the player, not your platform:

curl -i -X POST \
  https://sandbox-api.pathly.io/payment-methods/bank-accounts \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "account_id": "5b3f0c2e-1d4a-4e8b-9c7a-2f6d8e0a1b22",
    "account_holder_name": "Peter Griffin",
    "bank_account_holder_type": "individual",
    "bank_account_type": "checking",
    "bank_name": "Chase",
    "bank_country": "US",
    "currency": "USD",
    "routing_number": "021000021",
    "account_number": "000123456789"
  }'

Adding a bank account is a command: it returns the standard success envelope with no resource body (no payment-method id). Look up the new bank account's id in the next step. See the Create a bank account endpoint in the API reference for the full request and response.

2. Look up the player's bank payment-method id​

The source is a bank account, so it's addressed by payment-method id — fetch the player's bank PMs with GET /payment-methods?accountId=<player>&type=bank-account (your token, reading the player you onboarded):

curl -i -X GET \
  'https://sandbox-api.pathly.io/payment-methods?accountId=5b3f0c2e-1d4a-4e8b-9c7a-2f6d8e0a1b22&type=bank-account' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Take the id of the bank account you just added. The destination wallet does not need a lookup — it's addressed by the player's account id. For full query parameters and response, see the List payment methods API reference.

3. Create the pull transfer​

The source bank is addressed by its payment-method id; the destination wallet is addressed by the player's account id:

curl -i -X POST \
  https://sandbox-api.pathly.io/transfers \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: dep_2026-06-25_peter_01' \
  -d '{
    "source_payment_method": "<PLAYER_BANK_PAYMENT_METHOD_ID>",
    "destination_account": "5b3f0c2e-1d4a-4e8b-9c7a-2f6d8e0a1b22",
    "amount": 5000,
    "currency": "USD",
    "reference": "wallet top-up"
  }'
  • source_payment_method is the player's bank account; destination_account is the player's account (its USD wallet). Both belong to the player (a pull is same-account), and the bank-account source identifies the player as the actor — you act on their behalf because you onboarded them.
  • Pathly infers the pull rail from the source instrument (bank → wallet).
  • amount is in the smallest currency unit (cents).
  • The Idempotency-Key header is required. Replaying the same key returns the original transfer instead of creating a new one.

Response​

POST /transfers is a command and returns no body. A pull 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/a1b2c3d4-...

Read the result from the Location header with GET /transfers/{id}, and/or subscribe to the transfer.* webhooks. The transfer is born pending and the wallet credit is held until the bank settles it (pending → dispatched → settled). Subscribe to transfer.settled / transfer.returned (see webhooks) to learn the outcome instead of polling.

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