Payouts

A payout sends money out to a recipient — a wallet or a bank account. This is a different thing from a refund, which sends money back to a payer who already paid you. Payouts use a different endpoint, a different lifecycle, and a different set of status values than payments or refunds. Do not mix the two up.

Payout methods

The request body is the same shape for every method — only payout_type and payout_method_data change.

Method	`payout_type`	`payout_method_data`	Required fields
M-Pesa Express	`wallet`	`wallet.m_pesa_express`	—
Airtel Money	`wallet`	`wallet.airtel_money`	—
MTN MoMo	`wallet`	`wallet.momo_mtn`	—
PesaLink	`bank`	`bank.pesa_link`	`account_id`, `bank_code`
Paybill	`bank`	`bank.pay_bill`	`account_id`, `sub_account`
Paytill	`bank`	`bank.pay_till`	`account_id`

MTN MoMo payouts use currency: "EUR". The other five methods use currency: "KES".

The three wallet methods take an empty object, since the recipient is identified by phone and phone_country_code. The three bank methods need their own payout_method_data: PesaLink — payout_type: "bank"

{
  "payout_method_data": {
    "bank": {
      "pesa_link": {
        "account_id": "049384308738",
        "bank_code": "01"
      }
    }
  }
}

For valid bank_code values, see the PesaPay bank codes page. Paybill — payout_type: "bank"

{
  "payout_method_data": {
    "bank": {
      "pay_bill": {
        "account_id": "247247",
        "sub_account": "384539875"
      }
    }
  }
}

Paytill — payout_type: "bank"

{
  "payout_method_data": {
    "bank": {
      "pay_till": {
        "account_id": "247247"
      }
    }
  }
}

The account numbers above are illustrative — replace them with the recipient’s actual paybill, till, or PesaLink account details.

Create and confirm the payout

Send a POST request to /payouts/create with confirm: true. Along with amount, currency, profile_id, phone, and phone_country_code, you choose a payout_type and fill in the matching payout_method_data.Here is a full example for M-Pesa Express:

curl --request POST \
  --url https://api.sandbox.pesaswap.io/payouts/create \
  --header "api-key: {{api_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "amount": 100,
    "profile_id": "{{profile_id}}",
    "currency": "KES",
    "confirm": true,
    "payout_type": "wallet",
    "phone": "{{phone}}",
    "phone_country_code": "254",
    "payout_method_data": {
      "wallet": {
        "m_pesa_express": {}
      }
    }
  }'

const response = await fetch("https://api.sandbox.pesaswap.io/payouts/create", {
  method: "POST",
  headers: {
    "api-key": "{{api_key}}",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 100,
    profile_id: "{{profile_id}}",
    currency: "KES",
    confirm: true,
    payout_type: "wallet",
    phone: "{{phone}}",
    phone_country_code: "254",
    payout_method_data: {
      wallet: {
        m_pesa_express: {},
      },
    },
  }),
});

const payout = await response.json();
console.log(payout);

import requests

response = requests.post(
    "https://api.sandbox.pesaswap.io/payouts/create",
    headers={
        "api-key": "{{api_key}}",
        "Content-Type": "application/json",
    },
    json={
        "amount": 100,
        "profile_id": "{{profile_id}}",
        "currency": "KES",
        "confirm": True,
        "payout_type": "wallet",
        "phone": "{{phone}}",
        "phone_country_code": "254",
        "payout_method_data": {
            "wallet": {
                "m_pesa_express": {}
            }
        },
    },
)

payout = response.json()
print(payout)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.sandbox.pesaswap.io/payouts/create",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "api-key: {{api_key}}",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "amount" => 100,
        "profile_id" => "{{profile_id}}",
        "currency" => "KES",
        "confirm" => true,
        "payout_type" => "wallet",
        "phone" => "{{phone}}",
        "phone_country_code" => "254",
        "payout_method_data" => [
            "wallet" => [
                "m_pesa_express" => new stdClass(),
            ],
        ],
    ]),
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

A successful call returns a 200 with a payout object. The fields that matter right now:

{
  "payout_id": "payout_...",
  "status": "pending",
  "amount": 100,
  "currency": "KES",
  "connector": "..."
}

The payout has been accepted for processing, but it has not necessarily reached the recipient yet.

Poll for the final status

Poll the payout with force_sync=true until the status settles:

curl --request GET \
  --url "https://api.sandbox.pesaswap.io/payouts/{payout_id}?force_sync=true" \
  --header "api-key: {{api_key}}"

const response = await fetch(
  `https://api.sandbox.pesaswap.io/payouts/${payoutId}?force_sync=true`,
  {
    method: "GET",
    headers: {
      "api-key": "{{api_key}}",
    },
  }
);

const payout = await response.json();
console.log(payout);

import requests

response = requests.get(
    f"https://api.sandbox.pesaswap.io/payouts/{payout_id}",
    params={"force_sync": "true"},
    headers={"api-key": "{{api_key}}"},
)

payout = response.json()
print(payout)

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.sandbox.pesaswap.io/payouts/{$payoutId}?force_sync=true",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "api-key: {{api_key}}",
    ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

Status reference

These are the only values status can take on a payout (PayoutStatus):

Status	What it means	What to do
`requires_creation`	The payout has not been created yet.	Keep polling.
`requires_confirmation`	Created but not yet confirmed.	Keep polling.
`requires_payout_method_data`	Missing the data needed for the chosen payout method.	Keep polling.
`requires_fulfillment`	Confirmed and waiting to be fulfilled.	Keep polling.
`requires_vendor_account_creation`	Waiting on a vendor-side account to be created for the recipient.	Keep polling.
`pending`	Accepted and queued for processing.	Keep polling.
`initiated`	Sent to the connector.	Keep polling.
`success`	The payout completed. Money has reached the recipient.	Stop — settled.
`failed`	The payout did not complete.	Stop — failed.
`cancelled`	The payout was cancelled before completion.	Stop — cancelled.
`expired`	The payout was not completed in time and expired.	Stop — expired.
`reversed`	A completed payout was reversed.	Stop — reversed.
`ineligible`	The payout is not eligible to be processed.	Stop — ineligible.

The terminal success value is success, not succeeded. succeeded is a payment status — it does not exist on payouts. Checking for the wrong string is a common source of payouts that look “stuck” when they actually completed.

Common errors

Missing account_id on a bank payout

PesaLink, Paybill, and Paytill all require account_id in payout_method_data.bank. Omitting it fails validation before the payout is even created.

Wallet payout to an unregistered number

If phone is not registered for the wallet named in payout_type (for example, a number with no M-Pesa account), the payout fails at the connector even though the request itself is valid.

Checking for succeeded instead of success

Payout completion is success. Code copied from a payments integration that checks for succeeded will never match and will poll forever.

Next steps

Refunds

Send money back to a payer instead.

Quickstart

The full create-and-poll payment loop.

Wallet payments

M-Pesa, Airtel, and MTN MoMo payments.

About Pesaswap

Payments Guide

Account Setup

Use Cases

Explore Pesaswap

Checklist for Production

FAQ

Payout methods

Status reference

Common errors

Next steps

Refunds

Quickstart

Wallet payments

​Payout methods

​Status reference

​Common errors

​Next steps

Refunds

Quickstart

Wallet payments

Payout methods

Status reference

Common errors

Next steps