> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.hopnow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Flow 5: Pay out

<div className="hop-lede">A <span className="hop-strong">beneficiary</span> and its <span className="hop-strong">payout destination</span> are created once and reused.</div>

See the [Create Payout API reference](/fx/api-reference/payouts/create-payout) for request parameters and examples.

<div className="hop-flow hop-flow-steps">
  <div className="hop-prereq">↳ <span className="hop-strong">Funding source</span> 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 <code>self\_owned</code>. Mint the <code>Idempotency-Key</code> and store it with your payout record before calling.</div>

  <div className="hop-legend" aria-label="Flow legend">
    <span className="hop-legend-item"><span className="hop-chip hop-chip-platform">You</span>the API caller</span>
    <span className="hop-legend-item"><span className="hop-chip hop-chip-hop">Hop</span>automatic</span>
    <span className="hop-legend-item"><span className="hop-chip hop-chip-customer">Bank</span>payee's bank</span>
  </div>

  <ol className="hop-steps">
    <li className="hop-step-row">
      <span className="hop-step-n">1</span>
      <span className="hop-chip hop-chip-platform">You</span>

      <div className="hop-step-body">
        <a href="/fx/api-reference/beneficiaries/create-beneficiary" className="hop-step-title">Record who you are paying, with self\_owned set correctly</a>
        <span className="hop-step-pills"><span className="hop-pill hop-post"><span className="hop-method">POST</span>/accounts/\{aid}/beneficiaries</span><span className="hop-pill hop-object">bene\_</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">2</span>
      <span className="hop-chip hop-chip-platform">You</span>

      <div className="hop-step-body">
        <a href="/fx/api-reference/payout-destinations/create-destination" className="hop-step-title">Add the bank account or wallet under the beneficiary</a>
        <span className="hop-step-pills"><span className="hop-pill hop-post"><span className="hop-method">POST</span>/beneficiaries/\{bid}/payout-destinations</span><span className="hop-pill hop-object">dest\_</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">3</span>
      <span className="hop-chip hop-chip-hop">Hop</span>

      <div className="hop-step-body">
        <a href="/fx/api-reference/payout-destinations/get-destination" className="hop-step-title">Bank destinations are active at once. Wallet destinations are pending until Hop approves them</a>
        <span className="hop-step-pills"><span className="hop-pill hop-webhook">active · pending</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">4</span>
      <span className="hop-chip hop-chip-platform">You</span>

      <div className="hop-step-body">
        <a href="/fx/api-reference/payouts/create-payout" className="hop-step-title">Create the payout, naming the funding source, with an Idempotency-Key</a>
        <span className="hop-step-pills"><span className="hop-pill hop-post"><span className="hop-method">POST</span>/accounts/\{aid}/payouts</span><span className="hop-pill hop-object">po\_</span></span>

        <ol className="hop-steps hop-steps-sub">
          <li className="hop-step-row">
            <span className="hop-step-n">4a</span>

            <div className="hop-step-body">
              <span className="hop-step-title"><strong>Withdrawal:</strong> <code>funding\_source.type</code> is <code>trading\_account</code>. The beneficiary must be <code>self\_owned</code>. Omit <code>method</code>.</span>
            </div>
          </li>

          <li className="hop-step-row">
            <span className="hop-step-n">4b</span>

            <div className="hop-step-body">
              <span className="hop-step-title"><strong>Payout:</strong> <code>funding\_source.type</code> is <code>virtual\_account</code>. Any active beneficiary. Include a top-level <code>method</code> for the selected payment rail.</span>
            </div>
          </li>
        </ol>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">5</span>
      <span className="hop-chip hop-chip-hop">Hop</span>

      <div className="hop-step-body">
        <a href="/fx/webhooks/events" className="hop-step-title">Holds the amount and any fee; the payout is pending, or pending\_approval under a policy</a>
        <span className="hop-step-pills"><span className="hop-pill hop-webhook">payout.created</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">6</span>
      <span className="hop-chip hop-chip-platform">You</span>

      <div className="hop-step-body">
        <span className="hop-step-title">Approve in the Hop portal when your organization has an approval policy</span>
        <span className="hop-step-pills"><span className="hop-pill hop-rail">portal</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">7</span>
      <span className="hop-chip hop-chip-hop">Hop</span>

      <div className="hop-step-body">
        <span className="hop-step-title">Submits to the provider once review and approval have cleared</span>
        <span className="hop-step-pills"><span className="hop-pill hop-webhook">status: processing</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">8</span>
      <span className="hop-chip hop-chip-customer">Bank</span>

      <div className="hop-step-body">
        <span className="hop-step-title">Credits the funds</span>
        <span className="hop-step-pills"><span className="hop-pill hop-rail">settlement</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">9</span>
      <span className="hop-chip hop-chip-hop">Hop</span>

      <div className="hop-step-body">
        <a href="/fx/webhooks/events" className="hop-step-title">Reports the outcome</a>
        <span className="hop-step-pills"><span className="hop-pill hop-webhook">payout.completed · payout.failed</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">10</span>
      <span className="hop-chip hop-chip-customer">Bank</span>

      <div className="hop-step-body">
        <span className="hop-step-title">May return the funds days or weeks later</span>
        <span className="hop-step-pills"><span className="hop-pill hop-rail">return</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">11</span>
      <span className="hop-chip hop-chip-platform">You</span>

      <div className="hop-step-body">
        <a href="/fx/api-reference/payouts/get-payout" className="hop-step-title">Re-read completed payouts for returns; there is no event</a>
        <span className="hop-step-pills"><span className="hop-pill hop-get"><span className="hop-method">GET</span>/accounts/\{aid}/payouts/\{id}</span><span className="hop-pill hop-webhook">status: returned</span></span>
      </div>
    </li>

    <li className="hop-step-row">
      <span className="hop-step-n">12</span>
      <span className="hop-chip hop-chip-platform">You</span>

      <div className="hop-step-body">
        <a href="/fx/api-reference/payouts/list-payouts" className="hop-step-title">Reconcile per virtual account and date window</a>
        <span className="hop-step-pills"><span className="hop-pill hop-get"><span className="hop-method">GET</span>/accounts/\{aid}/payouts?virtual\_account\_id=va\_…</span></span>
      </div>
    </li>
  </ol>

  <div className="hop-footnote">Known gaps: there is no cancel endpoint, so a payout waiting for Hop review cannot be withdrawn through the API. No event fires on <code>processing</code> or <code>returned</code>. <code>pending</code> covers both "awaiting Hop review" and "approved, queued". A <code>platform\_fee</code> is released on <code>failed</code> or <code>cancelled</code> and kept on <code>returned</code>.</div>
</div>

## 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`](/fx/webhooks/events#payout-destination-payload), or poll [Get Payout Destination](/fx/api-reference/payout-destinations/get-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](/fx/api-reference/payouts/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. |