Skip to main content
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
  1. 1You
    Record who you are paying, with self_owned set correctlyPOST/accounts/{aid}/beneficiariesbene_
  2. 2You
    Add the bank account or wallet under the beneficiaryPOST/beneficiaries/{bid}/payout-destinationsdest_
  3. 3Hop
  4. 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.
  5. 5Hop
  6. 6You
    Approve in the Hop portal when your organization has an approval policyportal
  7. 7Hop
    Submits the payout to the bank or payout providerstatus: processing
  8. 8Bank
    Credits the fundssettlement
  9. 9Hop
    Reports the outcomepayout.completed · payout.failed
  10. 10Bank
    May return the funds days or weeks laterreturn
  11. 11You
    Re-read completed payouts for returns; there is no eventGET/accounts/{aid}/payouts/{id}status: returned
  12. 12You
    Reconcile per virtual account and date windowGET/accounts/{aid}/payouts?virtual_account_id=va_…
Cancel payouts in pending or pending_approval through Cancel Payout. Cancellation releases held funds and fees back to their original balances. No event fires on processing or returned. A platform_fee is released on failed or cancelled and kept on returned.

Troubleshooting