Create Payout
curl --request POST \
--url https://api.hopnow.io/v1/accounts/{account_id}/payouts \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-API-Key: <api-key>' \
--data '
{
"beneficiary_id": "<string>",
"payout_destination_id": "<string>",
"amount": "<string>",
"currency": "<string>",
"note": "<string>",
"platform_fee": {}
}
'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/payouts"
payload = {
"beneficiary_id": "<string>",
"payout_destination_id": "<string>",
"amount": "<string>",
"currency": "<string>",
"note": "<string>",
"platform_fee": {}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
beneficiary_id: '<string>',
payout_destination_id: '<string>',
amount: '<string>',
currency: '<string>',
note: '<string>',
platform_fee: {}
})
};
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 => "POST",
CURLOPT_POSTFIELDS => json_encode([
'beneficiary_id' => '<string>',
'payout_destination_id' => '<string>',
'amount' => '<string>',
'currency' => '<string>',
'note' => '<string>',
'platform_fee' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hopnow.io/v1/accounts/{account_id}/payouts"
payload := strings.NewReader("{\n \"beneficiary_id\": \"<string>\",\n \"payout_destination_id\": \"<string>\",\n \"amount\": \"<string>\",\n \"currency\": \"<string>\",\n \"note\": \"<string>\",\n \"platform_fee\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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")
.header("Idempotency-Key", "<idempotency-key>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"beneficiary_id\": \"<string>\",\n \"payout_destination_id\": \"<string>\",\n \"amount\": \"<string>\",\n \"currency\": \"<string>\",\n \"note\": \"<string>\",\n \"platform_fee\": {}\n}")
.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::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"beneficiary_id\": \"<string>\",\n \"payout_destination_id\": \"<string>\",\n \"amount\": \"<string>\",\n \"currency\": \"<string>\",\n \"note\": \"<string>\",\n \"platform_fee\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "<string>",
"account_id": "<string>",
"beneficiary_id": "<string>",
"payout_destination_id": "<string>",
"amount": "<string>",
"currency": "<string>",
"amount_in_usd": "<string>",
"platform_fee": {},
"status": "<string>",
"provider": "<string>",
"provider_reference_id": "<string>",
"initiated_at": "<string>",
"submitted_at": "<string>",
"completed_at": "<string>",
"failed_at": "<string>",
"failed_reason": "<string>",
"note": "<string>",
"created": "<string>",
"updated": "<string>"
}Payouts
Create Payout
Send money to a beneficiary’s payout destination
POST
/
v1
/
accounts
/
{account_id}
/
payouts
Create Payout
curl --request POST \
--url https://api.hopnow.io/v1/accounts/{account_id}/payouts \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--header 'X-API-Key: <api-key>' \
--data '
{
"beneficiary_id": "<string>",
"payout_destination_id": "<string>",
"amount": "<string>",
"currency": "<string>",
"note": "<string>",
"platform_fee": {}
}
'import requests
url = "https://api.hopnow.io/v1/accounts/{account_id}/payouts"
payload = {
"beneficiary_id": "<string>",
"payout_destination_id": "<string>",
"amount": "<string>",
"currency": "<string>",
"note": "<string>",
"platform_fee": {}
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
'X-API-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
beneficiary_id: '<string>',
payout_destination_id: '<string>',
amount: '<string>',
currency: '<string>',
note: '<string>',
platform_fee: {}
})
};
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 => "POST",
CURLOPT_POSTFIELDS => json_encode([
'beneficiary_id' => '<string>',
'payout_destination_id' => '<string>',
'amount' => '<string>',
'currency' => '<string>',
'note' => '<string>',
'platform_fee' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>",
"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"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.hopnow.io/v1/accounts/{account_id}/payouts"
payload := strings.NewReader("{\n \"beneficiary_id\": \"<string>\",\n \"payout_destination_id\": \"<string>\",\n \"amount\": \"<string>\",\n \"currency\": \"<string>\",\n \"note\": \"<string>\",\n \"platform_fee\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
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")
.header("Idempotency-Key", "<idempotency-key>")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"beneficiary_id\": \"<string>\",\n \"payout_destination_id\": \"<string>\",\n \"amount\": \"<string>\",\n \"currency\": \"<string>\",\n \"note\": \"<string>\",\n \"platform_fee\": {}\n}")
.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::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"beneficiary_id\": \"<string>\",\n \"payout_destination_id\": \"<string>\",\n \"amount\": \"<string>\",\n \"currency\": \"<string>\",\n \"note\": \"<string>\",\n \"platform_fee\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "<string>",
"object": "<string>",
"account_id": "<string>",
"beneficiary_id": "<string>",
"payout_destination_id": "<string>",
"amount": "<string>",
"currency": "<string>",
"amount_in_usd": "<string>",
"platform_fee": {},
"status": "<string>",
"provider": "<string>",
"provider_reference_id": "<string>",
"initiated_at": "<string>",
"submitted_at": "<string>",
"completed_at": "<string>",
"failed_at": "<string>",
"failed_reason": "<string>",
"note": "<string>",
"created": "<string>",
"updated": "<string>"
}This endpoint requires an
Idempotency-Key header to prevent duplicate payouts.Path Parameters
string
required
The account’s external ID (starts with
acct_)Headers
string
required
Unique key to prevent duplicate payouts (e.g., UUID v4)
Request Body
string
required
Beneficiary external ID (starts with
bene_)string
required
Payout destination external ID (starts with
dest_)string
required
Payout amount (decimal string, must be positive)
string
required
ISO 4217 currency code
string
Optional internal note (max 500 characters)
object
Fee the platform charges its end user, debited from the funding source on top of
amount and credited to the platform’s fee-collection account when the payout completes. Released back if the payout fails or is cancelled; not refunded on a return. Platform customers only (end-customer accounts, feature-flagged); currency must equal the payout currency. Fields: currency (string) and amount (string, > 0, at most the currency’s decimal places).Response
string
Payout identifier (starts with
po_)string
Always returns
"payout"string
Account ID
string
Beneficiary ID
string
Payout destination ID
string
Payout amount (decimal)
string
Currency code
string
Amount converted to USD
object
Platform fee charged on top of
amount (currency, amount), or null when none.string
Payout status:
pending_approval, pending, processing, completed, or failedstring
Payment provider (null until submitted)
string
Provider reference ID
string
ISO 8601 timestamp when payout was initiated
string
ISO 8601 timestamp when payout was submitted to provider
string
ISO 8601 timestamp when payout completed
string
ISO 8601 timestamp when payout failed
string
Reason for failure
string
Optional note
string
ISO 8601 timestamp when created
string
ISO 8601 timestamp when last updated
Response Example
{
"id": "po_1234567890abcdef",
"object": "payout",
"account_id": "acct_1234567890abcdef",
"beneficiary_id": "bene_1234567890abcdef",
"payout_destination_id": "dest_1234567890abcdef",
"amount": "100.00",
"currency": "USD",
"amount_in_usd": "100.00",
"status": "pending_approval",
"provider": null,
"provider_reference_id": null,
"initiated_at": "2024-01-15T10:00:00Z",
"submitted_at": null,
"completed_at": null,
"failed_at": null,
"failed_reason": null,
"note": "Monthly payment",
"created": "2024-01-15T10:00:00Z",
"updated": "2024-01-15T10:00:00Z"
}