Create payout request

POST

payout_requests

curl --request POST \
  --url https://api.example.com/v1/payout_requests

<?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))

}

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

Creates a payout request for a partner, just as if they had requested it in the partner portal. The same program rules apply: the payout threshold, disabled payout requests, and EU self-billing. The request is created with the status 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

*Provide at least one: 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.

The payout amount is always the partner’s full available balance in 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 gateway you send, or else the partner’s preferred payout method. If the partner has no preferred payout method, the request fails.
Payment details: payout_settings from 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.

If there are no payment details for the gateway, the request fails. Details you send are used only for this payout request. The partner’s saved payout settings are never changed.

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
}

See the payout request object for the response fields.

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.

Create payout request

curl --request POST \
  --url https://api.example.com/v1/payout_requests

<?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))

}

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
}

Overview

Program

Partners

Customers

Transactions

Payout requests

Leads

Referral links

Coupons

Promotion codes

Webhooks

Refer-a-friend

Newsletter referral

Create payout request

Endpoint

Request body

How the gateway and payment details are chosen

Request

Response

Error responses

​Endpoint

​Request body

​How the gateway and payment details are chosen

​Request

​Response

​Error responses

Endpoint

Request body

How the gateway and payment details are chosen

Request

Response

Error responses