Create payout request
curl --request POST \
--url https://api.example.com/v1/payout_requestsimport requests
url = "https://api.example.com/v1/payout_requests"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v1/payout_requests', 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.example.com/v1/payout_requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$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.example.com/v1/payout_requests"
req, _ := http.NewRequest("POST", url, nil)
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.example.com/v1/payout_requests")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/payout_requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"data": {
"id": 555,
"partner": "partner_123",
"status": "requested",
"amount": 200.0,
"amount_units": "usd",
"payout_gateway": "paypal",
"created_by": "api",
"created_at": "2026-09-29T10:15:00.000000Z",
"updated_at": "2026-09-29T10:15:00.000000Z"
},
"status": 1
}
Payout requests
Create payout request
Request a payout of a partner’s earned commissions on their behalf
POST
/
v1
/
payout_requests
Create payout request
curl --request POST \
--url https://api.example.com/v1/payout_requestsimport requests
url = "https://api.example.com/v1/payout_requests"
response = requests.post(url)
print(response.text)const options = {method: 'POST'};
fetch('https://api.example.com/v1/payout_requests', 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.example.com/v1/payout_requests",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
]);
$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.example.com/v1/payout_requests"
req, _ := http.NewRequest("POST", url, nil)
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.example.com/v1/payout_requests")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v1/payout_requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
response = http.request(request)
puts response.read_body{
"data": {
"id": 555,
"partner": "partner_123",
"status": "requested",
"amount": 200.0,
"amount_units": "usd",
"payout_gateway": "paypal",
"created_by": "api",
"created_at": "2026-09-29T10:15:00.000000Z",
"updated_at": "2026-09-29T10:15:00.000000Z"
},
"status": 1
}
Endpoint
POST https://api.partnero.com/v1/payout_requests
requested and created_by: "api". You get the usual new payout request notification. To continue, approve it.
Request body
Partner identification| Parameter | Type | Required | Description |
|---|---|---|---|
partner.id | string | Yes* | Partner ID |
partner.key | string | Yes* | Any referral key belonging to the partner |
partner.email | string | Yes* | Partner’s email address |
id, key or email.
Payout fields
| Parameter | Type | Required | Description |
|---|---|---|---|
amount_units | string | Yes | Currency to pay out, e.g. usd. The partner must have a payout available in this currency. |
gateway | string | No | paypal, wise, crypto or venmo. Defaults to the partner’s preferred payout method. |
payout_settings | object | No | Payment details for this payout only (see below). Defaults to the partner’s saved settings for the gateway. |
reward_ids | array | No | Pay out only these commissions. Allowed only when commission selection is enabled for the program. |
amount_units, or the total of reward_ids if you send them. You can’t set the amount directly.
Payout settings fields
payout_settings is a flat object with the fields of the gateway. Fields that don’t belong to the gateway are ignored.
| Gateway | Fields |
|---|---|
paypal | username (required, PayPal email), name, address, tax_id |
crypto | wallet_address (required), type, name |
venmo | name (required), recipient_type (USER_HANDLE by default, EMAIL or PHONE), and the matching user_handle, email or phone (required) |
wise | Not supported. The partner’s saved Wise bank details are always used, and payout_settings is ignored. |
How the gateway and payment details are chosen
- Gateway: the
gatewayyou send, or else the partner’s preferred payout method. If the partner has no preferred payout method, the request fails. - Payment details:
payout_settingsfrom the request, if given (not for Wise). Otherwise, the settings the partner saved for that gateway. You can use any gateway the partner has saved settings for, even if it isn’t their preferred one. - Wise: the partner’s saved bank details for their preferred bank currency are used.
Request
- Preferred method
- PayPal with details
- Wise
- Crypto
- Selected commissions
curl --location 'https://api.partnero.com/v1/payout_requests' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"partner": {
"id": "partner_123"
},
"amount_units": "usd"
}'
curl --location 'https://api.partnero.com/v1/payout_requests' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"partner": {
"id": "partner_123"
},
"amount_units": "usd",
"gateway": "paypal",
"payout_settings": {
"username": "[email protected]",
"name": "Jane Doe",
"address": "1 Main St, Vilnius",
"tax_id": "LT123456789"
}
}'
curl --location 'https://api.partnero.com/v1/payout_requests' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"partner": {
"email": "[email protected]"
},
"amount_units": "eur",
"gateway": "wise"
}'
curl --location 'https://api.partnero.com/v1/payout_requests' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"partner": {
"key": "ref_123"
},
"amount_units": "usd",
"gateway": "crypto",
"payout_settings": {
"type": "btc",
"wallet_address": "bc1q..."
}
}'
curl --location 'https://api.partnero.com/v1/payout_requests' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"partner": {
"id": "partner_123"
},
"amount_units": "usd",
"reward_ids": [101, 102]
}'
Response
{
"data": {
"id": 555,
"partner": "partner_123",
"status": "requested",
"amount": 200.0,
"amount_units": "usd",
"payout_gateway": "paypal",
"created_by": "api",
"created_at": "2026-09-29T10:15:00.000000Z",
"updated_at": "2026-09-29T10:15:00.000000Z"
},
"status": 1
}
Error responses
Errors return{"status": 0, "message": "..."}. Validation errors also include errors, keyed by field (for example payout_settings.username).
| Status | Error | Solution |
|---|---|---|
| 404 | Partner not found | Check the partner id, key or email is correct for this program |
| 422 | Validation error | Check required fields, gateway, and payout_settings for the gateway. This error is also returned when no payout is available in amount_units. |
| 422 | Partner is not active | Only active partners can request payouts |
| 422 | Payout requests are disabled for this program or partner. | Enable payout requests in the program or partner settings |
| 422 | Partner must complete tax & billing details before a payout can be requested. | The partner must complete their billing profile (EU self-billing programs) |
| 422 | Selecting specific commissions is not enabled for this program. | Remove reward_ids, or enable commission selection |
| 422 | Partner does not have a preferred payout gateway. | Send gateway |
| 422 | Partner must set payout settings for the “wise” payout gateway. | Send payout_settings (not for Wise), or ask the partner to save their payout settings |
Retrying is safe. If the same request is sent twice at the same time, the second one sees the already-reduced balance and fails, so the partner’s commissions can’t be paid out twice.
Was this page helpful?
