Before you start
You need three things from Hop, issued together when your organization’s KYC is approved:
You also need:
readaccess onaccounts, andwriteaccess onpaymentsandwebhooks.- A sandbox trading account with enough USD for the
100.00payout and any fees. Use Simulate Payin to fund it. - A running HTTPS webhook receiver that can verify Hop’s signature.
- Python 3 with
httpxinstalled.
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
2. Create a beneficiary
A beneficiary is who you are paying. Useself_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 areactive 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
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 sameIdempotency-Key if you retry this request; see Idempotency.
Python
pending payout is funded and queued; the money has not left yet.
6. Track the payout
Your endpoint receivespayout.completed when the payout completes, or payout.failed if it fails or is cancelled before release. You can also poll its status:
Python
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.