> ## 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.

# Create Payment

> Send funds to a beneficiary's payment destination, debiting a virtual account

Outgoing payments send funds to a beneficiary's payment destination, funded from a virtual account, with an optional platform fee. Routes are account-scoped (`/accounts/{account_id}/…`); the account must belong to your organization. Fee-collection accounts managed by Hop are not accessible via these routes (404).

| Enum             | Values                                                                                                                |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| `PaymentStatus`  | `pending_review` → `pending` → `processing` → `settled`; terminal `failed`, `rejected`, `returned`                    |
| `PaymentPurpose` | `supplier_or_vendor_payment`, `between_own_entities`, `salary_or_payroll`, `trade_settlement`, `tax_payment`, `other` |
| `PaymentMethod`  | `wire`, `ach`, `fedwire`, `spei`, `pix`, `manual`                                                                     |

| Status           | Meaning                                                                          |
| ---------------- | -------------------------------------------------------------------------------- |
| `pending_review` | Created, awaiting configured approval. Funds held on the source virtual account. |
| `pending`        | Approval complete or not required; waiting to be submitted for processing.       |
| `processing`     | Submitted for processing; in flight.                                             |
| `settled`        | Settlement confirmed; platform fee collected.                                    |
| `failed`         | Terminal — submission/settlement failed; holds released.                         |
| `rejected`       | Terminal — rejected by Hop; holds released.                                      |
| `returned`       | Terminal — returned before or after settlement.                                  |

<Note>
  Approvals and settlement are not client-driven. Hop performs state transitions (approve/reject/settle/fail/reverse); clients observe the resulting status and balance changes through this API.
</Note>

<Note>
  **Platform fee semantics:** the platform fee is part of payment creation — not a separate API. The fee is held on the source virtual account at create, collected on settlement, and released back to the source balance on reject, fail, or pre-settle reversal. A post-settle reversal returns the payment amount but does not auto-refund a collected fee.
</Note>

Sends funds to a beneficiary's payment destination, debiting a virtual account. The order starts at `pending_review` when configured approval is required, or `pending` when approval is not required; `amount` — plus `platform_fee_amount` if set — is held on the source virtual account until the payment settles or fails.

## Path Parameters

<ParamField path="account_id" type="string" required>
  Id of the account (`acct_…`) the payment is created under.
</ParamField>

## Headers

<ParamField header="Idempotency-Key" type="string" required>
  Unique key for this payment create. Re-using a key for the same account returns the previously created payment.
</ParamField>

## Request Body

<ParamField body="virtual_account_id" type="string" required>
  Id of the source virtual account (`va_…`) to debit.
</ParamField>

<ParamField body="beneficiary_id" type="string" required>
  Id of the beneficiary (`bene_…`).
</ParamField>

<ParamField body="payment_destination_id" type="string" required>
  Id of the beneficiary's payment destination (`dest_…`).
</ParamField>

<ParamField body="amount" type="decimal" required>
  Recipient amount, in the destination currency. Must be greater than 0.
</ParamField>

<ParamField body="payment_method" type="enum" required>
  One of `wire`, `ach`, `fedwire`, `spei`, `pix`, `manual`. Must be among the destination's supported `payment_methods`.
</ParamField>

<ParamField body="payment_purpose" type="enum" required>
  One of `supplier_or_vendor_payment`, `between_own_entities`, `salary_or_payroll`, `trade_settlement`, `tax_payment`, `other`.
</ParamField>

<ParamField body="note" type="string | null">
  Private note for your platform, up to 500 characters. Not visible to the receiving bank.
</ParamField>

<ParamField body="reference" type="string | null">
  Bank-visible memo, up to 140 characters (SWIFT MT103 Field 70).
</ParamField>

<ParamField body="transfer_at" type="datetime | null">
  `null` dispatches the payment once it reaches `pending`. A future timestamp schedules dispatch at that time.
</ParamField>

<ParamField body="platform_fee_amount" type="decimal">
  Add-on platform fee, ≥ 0, default 0. Held in addition to `amount` and collected on settlement.
</ParamField>

<Warning>
  If `platform_fee_amount` > 0, fee collection must be enabled for the currency (contact Hop), and `amount + platform_fee_amount` must not exceed the source account balance; otherwise the request fails with 422.
</Warning>

## Response

Returns 200 with the new payment's `id`. Use [Get Payment](/va/payments/get-payment) to retrieve the full object, including review status and the debit receipt.

<ResponseField name="id" type="string">
  Id of the new payment (`apo_…`).
</ResponseField>

<RequestExample>
  ```json Request theme={null}
  {
    "virtual_account_id": "va_77q2m9p4q1w8e5r3t6y0u2i4",
    "beneficiary_id": "bene_2aq7c1e6a2b4f3c9b8d2e5a1",
    "payment_destination_id": "dest_9kp7c1e6a2b4f3c9b8d2e5a1",
    "amount": "1000.00",
    "payment_method": "wire",
    "payment_purpose": "supplier_or_vendor_payment",
    "reference": "Invoice 42",
    "platform_fee_amount": "25.00"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "apo_5tg9m9p4q1w8e5r3t6y0u2i4"
  }
  ```
</ResponseExample>