Skip to main content
Create a sandbox payout from your trading account to your own bank account, then track its status. This is a withdrawal; the API uses the same payout object for withdrawals and virtual-account payouts.

Before you start

You need three things from Hop, issued together when your organization’s KYC is approved: You also need:
  • read access on accounts, and write access on payments and webhooks.
  • A sandbox trading account with enough USD for the 100.00 payout and any fees. Use Simulate Payin to fund it.
  • A running HTTPS webhook receiver that can verify Hop’s signature.
  • Python 3 with httpx installed.

Set up the client

Run the following examples in order in the same Python session or script. Replace the four credential and ID placeholders below. This helper signs and sends each request; Authentication explains the signing scheme and includes JavaScript and cURL examples.
Python

1. Check the funding balance

Get Balances returns the available funds in your trading account.
Python
Check that the available USD balance covers the payout and any fees before continuing.

2. Create a beneficiary

A beneficiary is who you are paying. Use self_owned: True for this withdrawal: funds from the trading account can only go to an account you own. The example uses a fictional individual and bank account for sandbox testing.
Python

3. Add a payout destination

A payout destination is the bank account or wallet under that beneficiary. This example adds a USD bank account; bank destinations are active immediately.
Python

4. Register a webhook endpoint

Register for completion and failure events before creating the payout. Replace the example URL with your running HTTPS receiver:
Python
Store secret before you discard the response; it is not returned again. Configure your receiver to verify deliveries as described in Webhook security before continuing. Events emitted before the endpoint is registered are not delivered to it later.

5. Create the payout

Create Payout uses the beneficiary and destination IDs returned above. Keep the same Idempotency-Key if you retry this request; see Idempotency.
Python
A pending payout is funded and queued; the money has not left yet.

6. Track the payout

Your endpoint receives payout.completed when the payout completes, or payout.failed if it fails or is cancelled before release. You can also poll its status:
Python
A successful payout moves pending → processing → completed. Match the webhook’s data.id to PAYOUT_ID to reconcile it with your request. For retries and failed requests, see Failure and recovery.