Flow 5: Pay out - HopNow API

A beneficiary and its payout destination are created once and reused.

See the Create Payout API reference for request parameters and examples.

↳ Funding source decides which balance pays and who may be paid: from a virtual account it is a payout, from the trading account a withdrawal. Third parties are paid from a virtual account. The trading account may only pay a beneficiary marked self_owned. Mint the Idempotency-Key and store it with your payout record before calling.

Youthe API callerHopautomaticBankpayee’s bank

1You
Record who you are paying, with self_owned set correctlyPOST/accounts/{aid}/beneficiariesbene_
2You
Add the bank account or wallet under the beneficiaryPOST/beneficiaries/{bid}/payout-destinationsdest_
3Hop
Bank destinations are active at once. Wallet destinations are pending until Hop approves themactive · pending
4You
Create the payout, naming the funding source, with an Idempotency-KeyPOST/accounts/{aid}/payoutspo_
1. 4a
  Withdrawal: funding_source.type is trading_account. The beneficiary must be self_owned. Omit method.
2. 4b
  Payout: funding_source.type is virtual_account. Any active beneficiary. Include a top-level method for the selected payment rail.
5Hop
Holds the amount and any fee; the payout is pending, or pending_approval under a policypayout.created
6You
Approve in the Hop portal when your organization has an approval policyportal
7Hop
Submits to the provider once review and approval have clearedstatus: processing
8Bank
Credits the fundssettlement
9Hop
Reports the outcomepayout.completed · payout.failed
10Bank
May return the funds days or weeks laterreturn
11You
Re-read completed payouts for returns; there is no eventGET/accounts/{aid}/payouts/{id}status: returned
12You
Reconcile per virtual account and date windowGET/accounts/{aid}/payouts?virtual_account_id=va_…

Known gaps: there is no cancel endpoint, so a payout waiting for Hop review cannot be withdrawn through the API. No event fires on processing or returned. pending covers both “awaiting Hop review” and “approved, queued”. A platform_fee is released on failed or cancelled and kept on returned.

Troubleshooting

Signal	Meaning	Do this
Wallet destination is `pending`	Wallets are not created immediately: a new wallet often appears as `pending` first, and then automatically transitions to an `active` state. The activation process can take several minutes.	Wait for `payout_destination.updated`, or poll Get Payout Destination.
Wallet destination turns `disabled`	The Wallet cannot be used and the state is final; the event carries the new status.	Pay to another destination; a rejected wallet cannot be paid.
`422 INSUFFICIENT_FUNDS` on create	The account had insufficient funds to transfer to the recipient. The payout is recorded as `failed` .	Fund the balance and retry with a new key.
`422 TRADING_ACCOUNT_REQUIRES_SELF_OWNED_BENEFICIARY`	A withdrawal from the trading account went to a beneficiary that is not `self_owned`.	Fund the payout from a virtual account, or mark the beneficiary `self_owned` if it is your own account or wallet.
`404` for a beneficiary or destination you know exists	It is not `active`; disabled records return `404` on Create Payout.	Create a new beneficiary or destination.
Payout stuck in `pending`	Payouts will remain in this state until a final response has been received from our processing partners.	Check the portal, then Get Payout.
`payout.failed` with `data.status: cancelled`	If for any reason our processing partners are unable to successfully complete the payout, the payout will transition to failed, and funds will remain in your account	Create a new payout.

​Troubleshooting

Troubleshooting