# Sign the request first — see Authentication for x-timestamp, x-nonce and x-signature
curl -X POST "https://api.sbx.hopnow.io/va/v1/accounts/acct_3mnq7c1e6a2b4f3c9b8d2e5a/payments" \
-H "x-api-key: $API_KEY" \
-H "x-timestamp: $TIMESTAMP" \
-H "x-nonce: $NONCE" \
-H "x-signature: $SIGNATURE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"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"
}'
{
"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"
}
{
"id": "apo_5tg9m9p4q1w8e5r3t6y0u2i4"
}
Payments
Create Payment
Send funds to a beneficiary’s payment destination, debiting a virtual account
POST
/
va
/
v1
/
accounts
/
{account_id}
/
payments
# Sign the request first — see Authentication for x-timestamp, x-nonce and x-signature
curl -X POST "https://api.sbx.hopnow.io/va/v1/accounts/acct_3mnq7c1e6a2b4f3c9b8d2e5a/payments" \
-H "x-api-key: $API_KEY" \
-H "x-timestamp: $TIMESTAMP" \
-H "x-nonce: $NONCE" \
-H "x-signature: $SIGNATURE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"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"
}'
{
"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"
}
{
"id": "apo_5tg9m9p4q1w8e5r3t6y0u2i4"
}
Outgoing payments send funds to a beneficiary’s payment destination, funded from a virtual account, with an optional platform fee. Routes are account-scoped (
Sends funds to a beneficiary’s payment destination, debiting a virtual account. The order starts at
/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. |
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.
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.
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
string
required
Id of the account (
acct_…) the payment is created under.Headers
string
required
Unique key for this payment create. Re-using a key for the same account returns the previously created payment.
Request Body
string
required
Id of the source virtual account (
va_…) to debit.string
required
Id of the beneficiary (
bene_…).string
required
Id of the beneficiary’s payment destination (
dest_…).decimal
required
Recipient amount, in the destination currency. Must be greater than 0.
enum
required
One of
wire, ach, fedwire, spei, pix, manual. Must be among the destination’s supported payment_methods.enum
required
One of
supplier_or_vendor_payment, between_own_entities, salary_or_payroll, trade_settlement, tax_payment, other.string | null
Private note for your platform, up to 500 characters. Not visible to the receiving bank.
string | null
Bank-visible memo, up to 140 characters (SWIFT MT103 Field 70).
datetime | null
Recorded for your reference only. Scheduled dispatch is not yet available, so a future timestamp does not delay the payment — it dispatches once it reaches
pending either way, and scheduled_dispatched_at stays null. Talk to Hop before relying on scheduling.decimal
Add-on platform fee, ≥ 0, default 0. Held in addition to
amount and collected on settlement.If
platform_fee_amount > 0, fee collection must be enabled for the currency (contact Hop). A wire payment also incurs a Hop SWIFT wire-out fee, held when the payment is created and debited on settlement. amount + platform_fee_amount, plus that wire-out fee, must not exceed the source account balance — so a payment can be rejected for insufficient balance even when the amount and platform fee alone would fit. Failures return 422.The payment destination must be denominated in the same currency as the source virtual account; there is no FX on this route, and a mismatch returns 422 with error code CURRENCY_MISMATCH.Response
Returns 200 with the new payment’sid. Use Get Payment to retrieve the full object, including review status and the debit receipt.
string
Id of the new payment (
apo_…).# Sign the request first — see Authentication for x-timestamp, x-nonce and x-signature
curl -X POST "https://api.sbx.hopnow.io/va/v1/accounts/acct_3mnq7c1e6a2b4f3c9b8d2e5a/payments" \
-H "x-api-key: $API_KEY" \
-H "x-timestamp: $TIMESTAMP" \
-H "x-nonce: $NONCE" \
-H "x-signature: $SIGNATURE" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"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"
}'
{
"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"
}
{
"id": "apo_5tg9m9p4q1w8e5r3t6y0u2i4"
}