Cancel Payout
curl --request POST \
--url https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel"
headers = {"X-API-Key": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "<string>",
"account_id": "<string>",
"beneficiary_id": "<string>",
"payout_destination_id": "<string>",
"network": "<string>",
"txn_hash": "<string>",
"amount": "<string>",
"currency": "<string>",
"payment_rail": {},
"amount_in_usd": "<string>",
"funding_source": {},
"platform_fee": {},
"status": "<string>",
"uetr": "<string>",
"tracking_details": {
"uetr": {},
"imad": {},
"omad": {},
"trace_number": {}
},
"initiated_at": "<string>",
"submitted_at": "<string>",
"completed_at": "<string>",
"failed_at": "<string>",
"failed_reason": "<string>",
"voided_at": "<string>",
"voided_reason": "<string>",
"note": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}Payouts
Cancel Payout
Cancel a pending payout and release its held funds and fees
POST
/
v1
/
accounts
/
{account_id}
/
payouts
/
{payout_id}
/
cancel
Cancel Payout
curl --request POST \
--url https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel"
headers = {"X-API-Key": "<api-key>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/payouts/{payout_id}/cancel")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "<string>",
"account_id": "<string>",
"beneficiary_id": "<string>",
"payout_destination_id": "<string>",
"network": "<string>",
"txn_hash": "<string>",
"amount": "<string>",
"currency": "<string>",
"payment_rail": {},
"amount_in_usd": "<string>",
"funding_source": {},
"platform_fee": {},
"status": "<string>",
"uetr": "<string>",
"tracking_details": {
"uetr": {},
"imad": {},
"omad": {},
"trace_number": {}
},
"initiated_at": "<string>",
"submitted_at": "<string>",
"completed_at": "<string>",
"failed_at": "<string>",
"failed_reason": "<string>",
"voided_at": "<string>",
"voided_reason": "<string>",
"note": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
}Cancels a payout with a status of
pending or pending_approval. Supports both trading account withdrawals and virtual account-funded payouts.
Cancellation Behavior
- The payout status changes to
cancelled. - Any active approval requests are cancelled.
- Held funds and fees are released back to their original balances.
- Cancellation is final. A new payout must be created to initiate the payment again.
Request
No request body orIdempotency-Key header is required.
Cancelling an already-cancelled payout returns 200 OK with the existing payout object. No additional funds are released or duplicate notifications sent.
Requires an API key with write access to the payments scope.
Path Parameters
string
required
The account’s external ID (starts with
acct_)string
required
The payout’s external ID (starts with
po_). Must belong to this account.Response
Returns200 with the payout in the same flat shape as Get Payout, with status set to cancelled.
Subscribed webhook endpoints receive payout.failed with data.status set to cancelled.
string
Payout identifier (starts with
po_)string
Always returns
"payout"string
Account ID (starts with
acct_)string
Beneficiary ID (starts with
bene_). null only on payouts Hop booked manually on your behalf.string
Payout destination ID (starts with
dest_). null only on payouts Hop booked manually on your behalf.string
Blockchain network for a crypto payout, otherwise
nullstring
Blockchain transaction hash for a crypto payout, otherwise
null. It appears once the payout is on chain, so it is null on a payout that has not been submitted yet.string
Payout amount (decimal)
string
Currency code
string | null
Selected payout rail, using the lowercase values listed in Create Payout. Returned from creation onward when a rail was selected.
null means no explicit selection, including on historical payouts. This field records the selection, not confirmation of the rail actually used by the provider.string
Amount converted to USD, or
null when no rate was availableobject
Balance funding the payout, always present:
{"type": "trading_account"} for a withdrawal, {"type": "virtual_account", "virtual_account_id": "va_…"} for a payoutobject
Platform fee charged on top of
amount (currency, amount), or null when nonestring
Payout status, one of eight values:
pending: funded and queued, awaiting submissionpending_approval: waiting for approval in your portal under an approval policy (optional)processing: submitted for processingcompleted: processed by the bank or payout providerfailed: the payout could not be funded or was rejected; any held funds are released back to the originating balancecancelled: cancelled before submission; the payout hold is releasedreturned: the payment is returned by the recipient’s bankvoided: a completed payout is reversed
pending → pending_approval | processing | completed | failed | cancelled; pending_approval → pending | cancelled; processing → completed | failed; completed → returned | voided. failed, cancelled, returned and voided are terminal.Cancel Payout accepts pending and pending_approval and releases held funds and fees back to their original balances.string
SWIFT UETR (unique end-to-end transaction reference) for a wire, or
null. Also available as tracking_details.uetr; this top-level field remains for compatibility.object
Payment-network tracking identifiers, populated as they become available. The object is always present; unavailable or inapplicable identifiers are
null. The same object is included in payout webhooks.string
ISO 8601 timestamp when the payout was initiated
string
ISO 8601 timestamp when Hop sent the payment command to the provider, or
nullstring
ISO 8601 timestamp when the payout completed, or
nullstring
ISO 8601 timestamp when the payout failed, or
nullstring
Reason for failure, or
nullstring
ISO 8601 timestamp when the payout was voided, or
nullstring
Reason the payout was voided, or
nullstring
Note carried on the payout, or
nullstring
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Actor that created the payout: the API key id (starts with
ak_), or hop_admin for a manual payoutstring
Actor that last updated the payout, or
nullErrors
| Status | code | When |
|---|---|---|
403 | ACCESS_DENIED | The API key lacks write access on the payments scope |
404 | RESOURCE_NOT_FOUND | The account or payout is unknown, or the payout belongs to another account |
409 | BUSINESS_RULE_VIOLATION | The payout is no longer eligible for cancellation, including payouts in processing, completed, failed, returned or voided |
422 | APPROVAL_CONCURRENT_UPDATE | The payout changed concurrently; retrieve the payout and retry if it is still in pending or pending_approval |
Request Example
curl -X POST "https://api.hopnow.io/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/payouts/po_r4ft5s7cuvimpoloqd8gwksw/cancel" \
-H "X-API-Key: your_api_key" \
-H "X-Signature: hmac_signature" \
-H "X-Timestamp: 1234567890" \
-H "X-Nonce: abc123"
Response Example
{
"id": "po_r4ft5s7cuvimpoloqd8gwksw",
"object": "payout",
"account_id": "acct_ka44qsvpo8q3wtzuwfqf0h6u",
"beneficiary_id": "bene_9gt1ummgx127biovlurm9mq2",
"payout_destination_id": "dest_7h3n5q8v2c6b1m4x9z0j5k2l",
"amount": "100.00",
"currency": "USD",
"payment_rail": null,
"amount_in_usd": "100.00",
"funding_source": {"type": "trading_account"},
"platform_fee": null,
"status": "cancelled",
"uetr": null,
"tracking_details": {
"uetr": null,
"imad": null,
"omad": null,
"trace_number": null
},
"network": null,
"txn_hash": null,
"initiated_at": "2026-01-15T10:00:00Z",
"submitted_at": null,
"completed_at": null,
"failed_at": null,
"failed_reason": "The payout was cancelled. Please contact support for more information.",
"voided_at": null,
"voided_reason": null,
"note": "Monthly payment",
"created": "2026-01-15T10:00:00Z",
"updated": "2026-01-15T10:01:00Z",
"created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
"updated_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q"
}