List Payouts
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/payouts \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/payouts"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hopnow.io/v1/accounts/{account_id}/payouts', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
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"
req, _ := http.NewRequest("GET", 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.get("https://api.hopnow.io/v1/accounts/{account_id}/payouts")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/payouts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"object": "<string>",
"beneficiary": {
"id": "<string>",
"object": "<string>",
"beneficiary_type": "<string>",
"title": "<string>",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"display_name": "<string>",
"company_name": "<string>",
"status": "<string>",
"verified": true,
"self_owned": true,
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
},
"payout_destination": {
"id": "<string>",
"object": "<string>",
"country": "<string>",
"type": "<string>",
"label": "<string>",
"currency": "<string>",
"network": "<string>",
"status": "<string>",
"account_name": "<string>",
"swift_code": "<string>",
"routing_number": "<string>",
"bank_name": "<string>",
"bank_address": {},
"correspondent_bank_name": "<string>",
"correspondent_bank_address": {},
"correspondent_bank_swift": "<string>",
"account_holder": "<string>",
"payment_rails": [
{}
],
"account_number_last4": "<string>",
"clabe_last4": "<string>",
"pix_key_last4": "<string>",
"iban_masked": "<string>",
"wallet_address_masked": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
},
"amount": "<string>",
"currency": "<string>",
"payment_rail": {},
"amount_in_usd": "<string>",
"funding_source": {},
"platform_fee": {},
"status": "<string>",
"uetr": "<string>",
"tracking_details": {},
"payout_type": "<string>",
"network": "<string>",
"txn_hash": "<string>",
"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>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Payouts
List Payouts
Retrieve a paginated list of outgoing payments
GET
/
v1
/
accounts
/
{account_id}
/
payouts
List Payouts
curl --request GET \
--url https://api.hopnow.io/v1/accounts/{account_id}/payouts \
--header 'X-API-Key: <api-key>'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/payouts"
headers = {"X-API-Key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};
fetch('https://api.hopnow.io/v1/accounts/{account_id}/payouts', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
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"
req, _ := http.NewRequest("GET", 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.get("https://api.hopnow.io/v1/accounts/{account_id}/payouts")
.header("X-API-Key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.hopnow.io/v1/accounts/{account_id}/payouts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"items": [
{
"id": "<string>",
"object": "<string>",
"beneficiary": {
"id": "<string>",
"object": "<string>",
"beneficiary_type": "<string>",
"title": "<string>",
"first_name": "<string>",
"middle_name": "<string>",
"last_name": "<string>",
"display_name": "<string>",
"company_name": "<string>",
"status": "<string>",
"verified": true,
"self_owned": true,
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
},
"payout_destination": {
"id": "<string>",
"object": "<string>",
"country": "<string>",
"type": "<string>",
"label": "<string>",
"currency": "<string>",
"network": "<string>",
"status": "<string>",
"account_name": "<string>",
"swift_code": "<string>",
"routing_number": "<string>",
"bank_name": "<string>",
"bank_address": {},
"correspondent_bank_name": "<string>",
"correspondent_bank_address": {},
"correspondent_bank_swift": "<string>",
"account_holder": "<string>",
"payment_rails": [
{}
],
"account_number_last4": "<string>",
"clabe_last4": "<string>",
"pix_key_last4": "<string>",
"iban_masked": "<string>",
"wallet_address_masked": "<string>",
"created": "<string>",
"updated": "<string>",
"created_by": "<string>",
"updated_by": "<string>"
},
"amount": "<string>",
"currency": "<string>",
"payment_rail": {},
"amount_in_usd": "<string>",
"funding_source": {},
"platform_fee": {},
"status": "<string>",
"uetr": "<string>",
"tracking_details": {},
"payout_type": "<string>",
"network": "<string>",
"txn_hash": "<string>",
"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>"
}
],
"page": 123,
"size": 123,
"total": 123,
"pages": 123
}Returns the account’s payouts, newest first. There are no sort parameters.
List items are not the same shape as Get Payout: each item nests the full
beneficiary and payout_destination objects instead of their ids, and it carries no account_id (every item belongs to the account in the path).
Voided payouts are Hop reversals of completed payouts, hidden by default so the list totals match what left the account; pass status=voided to list them. cancelled and returned payouts are included by default.
Requires an API key with read access on the payments scope.
Path Parameters
string
required
The account’s external ID (starts with
acct_)Query Parameters
string
Filter by payout status:
pending, pending_approval, processing, completed, failed, cancelled, returned or voided. When omitted, every status except voided is returned.string
Filter by currency code: a supported fiat code (for example
USD, EUR, GBP) or one of USDC, USDTstring
Return only payouts funded by this virtual account (starts with
va_, and must belong to this account). An unknown or foreign id returns 404, not an empty page. There is no filter for withdrawals alone; select on funding_source.type client-side.string
Filter payouts created on or after this date (ISO 8601, inclusive)
string
Filter payouts created before this date (ISO 8601, exclusive)
integer
default:"1"
Page number (minimum 1)
integer
default:"10"
Items per page (1-100)
Response
array
Payout objects, newest first, with nested beneficiary and destination details
Show Payout Fields
Show Payout Fields
string
Payout identifier (starts with
po_)string
Always returns
"payout"object
Beneficiary summary, or
null on a payout Hop booked manuallyShow Beneficiary Fields
Show Beneficiary Fields
string
Beneficiary identifier (starts with
bene_)string
Always returns
"beneficiary"string
Beneficiary type,
individual or businessstring
Title (for example
Mr, Ms, Dr), or nullstring
First name, or
nullstring
Middle name, or
nullstring
Last name, or
nullstring
Display name, or
nullstring
Company name, or
nullstring
Beneficiary status
boolean
Whether the beneficiary is verified
boolean
Whether the beneficiary is the account holder’s own bank account at another institution. Only a
self_owned beneficiary can be paid from the trading account: withdrawals go to your own accounts.string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Actor that created the beneficiary
string
Actor that last updated the beneficiary, or
nullobject
Payout destination summary, or
null on a payout Hop booked manually. This summary omits account_type and beneficiary_id. Read Get Destination for those.Show Payout Destination Fields
Show Payout Destination Fields
string
Destination identifier (starts with
dest_)string
Always returns
"payout_destination"string
Payout country (ISO 3166-1 alpha-2)
string
Destination type,
bank_account or walletstring
Destination label, or
nullstring
Currency the destination pays out in
string
Blockchain network for a wallet destination, otherwise
nullstring
Destination status
string
Account holder name, or
nullstring
SWIFT/BIC code, or
nullstring
Bank routing number, or
nullstring
Receiving bank name, or
nullobject
Receiving bank address, or
nullstring
Correspondent bank name, or
nullobject
Correspondent bank address, or
nullstring
Correspondent bank SWIFT code, or
nullstring
Account holder, where it differs from
account_name; otherwise nullarray
Payout rails Hop derived from the destination details
string
Account number masked as
**** + last 4, or nullstring
CLABE masked as
**** + last 4, or nullstring
PIX key masked as
**** + last 4, or nullstring
IBAN masked as first 4 +
**** + last 4, or nullstring
Wallet address masked as first 6 +
**** + last 4, or nullstring
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
string
Actor that created the destination
string
Actor that last updated the destination, or
nullstring
Payout amount (decimal)
string
Currency code
string | null
Selected payout rail, using the values in Create Payout.
null means no explicit selection, including on historical payouts. This is separate from payout_destination.payment_rail and does not confirm the provider’s actual execution rail.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:
pending, pending_approval, processing, completed, failed, cancelled, returned or voided. See Get Payout for what each means and how they transition.string
SWIFT UETR (unique end-to-end transaction reference) for a wire, or
null. Also returned in tracking_details.uetr.object
Payment-network identifiers:
uetr for SWIFT, imad and omad for Fedwire, and trace_number for ACH. The object is always present; each identifier is null until available or when inapplicable.string
Payout type:
standard or manual (booked by Hop)string
Blockchain network for a crypto payout, otherwise
nullstring
Blockchain transaction hash for a crypto payout, otherwise
nullstring
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
nullinteger
Current page number
integer
Items per page
integer
Total number of items
integer
Total number of pages
Errors
| Status | code | When |
|---|---|---|
404 | RESOURCE_NOT_FOUND | virtual_account_id is unknown or belongs to another account |
422 | VALIDATION_ERROR | status or currency is not one of the accepted values, or page/size is out of range |
Request Example
curl "https://api.hopnow.io/v1/accounts/acct_ka44qsvpo8q3wtzuwfqf0h6u/payouts?status=completed&size=10" \
-H "X-API-Key: your_api_key" \
-H "X-Signature: hmac_signature" \
-H "X-Timestamp: 1234567890" \
-H "X-Nonce: abc123"
Response Example
{
"items": [
{
"id": "po_r4ft5s7cuvimpoloqd8gwksw",
"object": "payout",
"beneficiary": {
"id": "bene_9gt1ummgx127biovlurm9mq2",
"object": "beneficiary",
"beneficiary_type": "individual",
"title": "Mr",
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"display_name": "John Doe",
"company_name": null,
"status": "active",
"verified": true,
"self_owned": false,
"created": "2026-01-10T00:00:00Z",
"updated": "2026-01-10T00:00:00Z",
"created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
"updated_by": null
},
"payout_destination": {
"id": "dest_7h3n5q8v2c6b1m4x9z0j5k2l",
"object": "payout_destination",
"country": "US",
"type": "bank_account",
"label": "Operating account",
"currency": "USD",
"network": null,
"status": "active",
"account_name": "John Doe",
"swift_code": null,
"routing_number": "021000021",
"bank_name": "JPMorgan Chase",
"bank_address": null,
"correspondent_bank_name": null,
"correspondent_bank_address": null,
"correspondent_bank_swift": null,
"account_holder": null,
"payment_rails": ["swift"],
"account_number_last4": "****7890",
"clabe_last4": null,
"pix_key_last4": null,
"iban_masked": null,
"wallet_address_masked": null,
"created": "2026-01-10T00:00:00Z",
"updated": "2026-01-10T00:00:00Z",
"created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
"updated_by": null
},
"amount": "100.00",
"currency": "USD",
"payment_rail": "fedwire",
"amount_in_usd": "100.00",
"funding_source": {"type": "virtual_account", "virtual_account_id": "va_2w9e4r7t1y5u8i3o6p0a5s2d"},
"platform_fee": null,
"status": "completed",
"uetr": null,
"tracking_details": {
"uetr": null,
"imad": "20260115BANK00000000001",
"omad": "20260115BANK00000000002",
"trace_number": null
},
"payout_type": "standard",
"network": null,
"txn_hash": null,
"initiated_at": "2026-01-15T10:00:00Z",
"submitted_at": "2026-01-15T10:02:00Z",
"completed_at": "2026-01-15T10:05:00Z",
"failed_at": null,
"failed_reason": null,
"voided_at": null,
"voided_reason": null,
"note": "Monthly payment",
"created": "2026-01-15T10:00:00Z",
"updated": "2026-01-15T10:05:00Z",
"created_by": "ak_3f7k9m2p5r8t1v4x6z0b3n5q",
"updated_by": null
}
],
"page": 1,
"size": 10,
"total": 1,
"pages": 1
}