PAYOUTS

Create a payout

POSThttps://production.dutchapi.co/v1/payouts

Sends money to a mobile money wallet or bank account. The amount plus the Dutch fee is debited from your wallet immediately; a failed payout is returned to your balance.

🔒Send the project API key as a Bearer token and your Business ID with this call.

Requires an Idempotency-Key header. Repeating a request with the same key returns the original payout and never pays twice.

If payout approval is switched on for your organization, the response is 202 with status awaiting_approval, and an approver must confirm it in the dashboard.

Subscribe to payout.completed and payout.failed webhooks, or poll GET /v1/payouts/{id}.

Body Params

amountnumberrequired

Amount to send, in the source currency. Greater than 0.

currencystringrequired

Source wallet currency: USD, XAF, GHS, ZAR, NGN, RWF, UGX or KES.

railstringrequired

mobile_money or bank, where that rail is supported: CM/RW/CD/CI/SN/TZ/ZM mobile money; GH/KE/UG mobile money or bank; NG/ZA bank.

recipient.namestringrequired

Recipient full name (2 to 100 characters).

recipient.accountstringrequired

Mobile number in international format, or bank account number.

recipient.countrystringrequired

ISO 3166 alpha-2 payout destination: CM, GH, UG, KE, NG, RW, ZA, CD, TZ, ZM, SN or CI. Only the rail listed for each country is accepted.

recipient.bankCodestringoptional

Required for bank unless recipient.bank is sent. The public developer API has no bank-list endpoint; obtain the code from your business dashboard or support.

recipient.bankstringoptional

Bank name (required for bank unless recipient.bankCode is sent).

recipient.networkstringoptional

Mobile money network, for example MTN MoMo.

markupPercentnumberoptional

Your own markup as a percentage of the amount (0 to 50). Reported in fees, never debited.

markupFixednumberoptional

Your own fixed markup in the request currency. Reported in fees, never debited.

referencestringoptional

Your own reference, 4 to 64 characters (letters, digits, - _ : .). Must be unique.

descriptionstringoptional

Up to 140 characters.

fundstringoptional

Only balance is available. Just-in-time funding is coming soon.

Responses

{
  "id": "pyt_8f2c1a",
  "object": "payout",
  "kind": "disbursement",
  "status": "processing",
  "amount": 40000,
  "currency": "XAF",
  "fee": 300,
  "description": "Payout to Ada Obi",
  "created_at": "2026-10-13T09:30:00.000Z",
  "completed_at": null,
  "failure_reason": null,
  "funding": "balance",
  "rail": "bank",
  "recipient": {
    "name": "Ada Obi",
    "account": "******6789",
    "country": "NG"
  },
  "receive": {
    "amount": 88978.6,
    "currency": "NGN",
    "rate": 2.2244
  },
  "fees": {
    "currency": "XAF",
    "rule": "fixed",
    "ruleDetail": "Under 50,000 XAF: 300 XAF fixed",
    "dutchFee": 300,
    "markup": 100,
    "totalFee": 400
  }
}

{
  "error": "idempotency_key_required",
  "message": "Send an Idempotency-Key header."
}

Errors

Status	error	Meaning
400	`idempotency_key_required`	Send an Idempotency-Key header.
400	`valid_amount_required`	amount must be a positive number.
400	`unsupported_currency`	currency must be one of USD, XAF, GHS, ZAR, NGN, RWF, UGX or KES.
402	`insufficient_funds`	The wallet balance is too low.
403	`limits_not_set`	No live limit is enabled for this currency (Dashboard, Limits & safety).
422	`over_per_request_limit`	The amount is above the per-request limit.
422	`over_daily_limit`	The daily limit would be exceeded.
423	`money_movement_paused`	The kill switch is on.
409	`duplicate_reference`	That reference was already used.
409	`request_in_progress`	A request with the same Idempotency-Key is still running.
422	`idempotency_key_reused`	The Idempotency-Key was used with a different request.
422	`unsupported_payout_rail`	That bank or mobile-money rail is not supported in the requested country.
422	`payout_rejected`	Dutch API could not complete the payout; the amount was returned.

Updated 2026

Did this page help you?

PreviousQuote a payout NextRetrieve a payout

Language

CredentialsBearer

curl --request POST --url "https://production.dutchapi.co/v1/payouts" \
  --header "Authorization: Bearer $DUTCH_PROJECT_KEY" \
  --header "X-Business-Id: $DUTCH_BUSINESS_ID" \
  --header "Idempotency-Key: create-payout-0001" \
  --header "Content-Type: application/json" \
  --data '{"amount":40000,"currency":"XAF","rail":"mobile_money","recipient":{"name":"Jean Mbarga","account":"+237670000001","country":"CM","network":"MTN MoMo"},"reference":"order-1042","description":"Supplier payment"}'

const res = await fetch("https://production.dutchapi.co/v1/payouts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.DUTCH_PROJECT_KEY,
    "X-Business-Id": process.env.DUTCH_BUSINESS_ID,
    "Idempotency-Key": "create-payout-0001",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"amount": 40000, "currency": "XAF", "rail": "mobile_money", "recipient": {"name": "Jean Mbarga", "account": "+237670000001", "country": "CM", "network": "MTN MoMo"}, "reference": "order-1042", "description": "Supplier payment"})
});
console.log(await res.json());

require "net/http"
require "json"

uri = URI("https://production.dutchapi.co/v1/payouts")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('DUTCH_PROJECT_KEY')}"
req["X-Business-Id"] = ENV.fetch("DUTCH_BUSINESS_ID")
req["Idempotency-Key"] = "create-payout-0001"
req["Content-Type"] = "application/json"
req.body = "{\"amount\":40000,\"currency\":\"XAF\",\"rail\":\"mobile_money\",\"recipient\":{\"name\":\"Jean Mbarga\",\"account\":\"+237670000001\",\"country\":\"CM\",\"network\":\"MTN MoMo\"},\"reference\":\"order-1042\",\"description\":\"Supplier payment\"}"
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

<?php
$ch = curl_init("https://production.dutchapi.co/v1/payouts");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("DUTCH_PROJECT_KEY"),
    "X-Business-Id: " . getenv("DUTCH_BUSINESS_ID"),
    "Idempotency-Key: create-payout-0001",
    "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => '{"amount":40000,"currency":"XAF","rail":"mobile_money","recipient":{"name":"Jean Mbarga","account":"+237670000001","country":"CM","network":"MTN MoMo"},"reference":"order-1042","description":"Supplier payment"}',
]);
echo curl_exec($ch);

import os, requests, json

res = requests.request(
    "POST",
    "https://production.dutchapi.co/v1/payouts",
    headers={
        "Authorization": "Bearer " + os.environ["DUTCH_PROJECT_KEY"],
        "X-Business-Id": os.environ["DUTCH_BUSINESS_ID"],
        "Idempotency-Key": "create-payout-0001",
    },
    json=json.loads("{\"amount\":40000,\"currency\":\"XAF\",\"rail\":\"mobile_money\",\"recipient\":{\"name\":\"Jean Mbarga\",\"account\":\"+237670000001\",\"country\":\"CM\",\"network\":\"MTN MoMo\"},\"reference\":\"order-1042\",\"description\":\"Supplier payment\"}")
)
print(res.json())

Response

Click `Show example` to see an example response. Nothing is sent from this page: endpoints are live, so run real requests from your own code with small amounts.