Payouts

Send money to bank accounts and mobile money wallets via Chapa. Before creating a payout, query the available destinations to get the correct destination_id and required fields.

List Destinations

GET /api/payouts/destinations

Returns the available payout destinations (banks, mobile money providers) for a given currency. Use the returned id values as the destination_id when creating payouts.

Query Parameters

Parameter	Type	Default	Description
`currency`	string	`ETB`	Currency code to get destinations for

List payout destinations

curl "https://pay.phoenixverse.io/api/payouts/destinations?currency=ETB" \
  -H "Authorization: Bearer <token>"

Response

200 OK

{
  "data": [
    {
      "id": "cbe_abyssinia",
      "name": "Abyssinia Bank",
      "currency": "ETB",
      "fields": [
        {
          "name": "account_number",
          "label": "Account Number",
          "type": "string",
          "required": true
        },
        {
          "name": "account_name",
          "label": "Account Holder Name",
          "type": "string",
          "required": true
        }
      ]
    },
    {
      "id": "telebirr",
      "name": "Telebirr",
      "currency": "ETB",
      "fields": [
        {
          "name": "account_number",
          "label": "Phone Number",
          "type": "string",
          "required": true
        },
        {
          "name": "account_name",
          "label": "Account Holder Name",
          "type": "string",
          "required": true
        }
      ]
    },
    {
      "id": "mpesa",
      "name": "M-Pesa",
      "currency": "ETB",
      "fields": [
        {
          "name": "account_number",
          "label": "Phone Number",
          "type": "string",
          "required": true
        },
        {
          "name": "account_name",
          "label": "Account Holder Name",
          "type": "string",
          "required": true
        }
      ]
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	Destination identifier. Use this as `destination_id` when creating a payout.
`name`	string	Human-readable name of the bank or provider
`currency`	string	Currency code
`fields`	array	List of required input fields for this destination

Each item in fields describes an input your user must provide:

Field	Type	Description
`name`	string	Field key to use in the payout `fields` object
`label`	string	Human-readable label for the field
`type`	string	Data type (always `"string"`)
`required`	boolean	Whether the field is required

The list of destinations and their required fields are determined by the PSP. They may change when the PSP updates their supported banks or providers. Always fetch destinations dynamically rather than hard-coding them.

Create Payout

POST /api/payouts

Creates a new outbound payout to a bank account or mobile money wallet.

Request Body

Field	Type	Required	Description
`reference_id`	string	Yes	Your unique identifier for this payout. Must be unique within your tenant.
`amount`	string	Yes	Payout amount as a decimal string (e.g., `"5000.00"`).
`currency`	string	Yes	Currency code (e.g., `ETB`).
`destination_id`	string	Yes	The destination identifier from List Destinations (e.g., `"cbe_abyssinia"`, `"telebirr"`).
`fields`	object	No	Account details required by the destination. See the `fields` array from List Destinations for required keys.

Examples

Payout to bank account

curl -X POST https://pay.phoenixverse.io/api/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "payout-78901",
    "amount": "5000.00",
    "currency": "ETB",
    "destination_id": "cbe_abyssinia",
    "fields": {
      "account_number": "1000123456789",
      "account_name": "Abebe Kebede"
    }
  }'

Payout to mobile money

curl -X POST https://pay.phoenixverse.io/api/payouts \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "payout-78902",
    "amount": "2500.00",
    "currency": "ETB",
    "destination_id": "telebirr",
    "fields": {
      "account_number": "+251911234567",
      "account_name": "Abebe Kebede"
    }
  }'

Response

201 Created

{
  "id": "01912e4c-9d5e-7def-ac12-3456789012cd",
  "reference_id": "payout-78901",
  "type": "payout",
  "status": "pending",
  "psp": "chapa",
  "requested_amount": "5000.00",
  "received_amount": null,
  "currency": "ETB",
  "destination_id": "cbe_abyssinia",
  "inserted_at": "2026-03-11T12:30:00Z",
  "updated_at": "2026-03-11T12:30:00Z"
}

Response Fields

Field	Type	Description
`id`	string (UUID v7)	Unique payment identifier
`reference_id`	string	Your reference ID from the request
`type`	string	Always `"payout"` for payouts
`status`	string	Initial status, typically `"pending"`
`psp`	string	The PSP handling this payout
`requested_amount`	string	The payout amount you requested
`received_amount`	string or null	The actual amount transferred (populated when settled)
`currency`	string	The currency code
`destination_id`	string	The destination used for this payout
`inserted_at`	string (ISO 8601)	When the record was created
`updated_at`	string (ISO 8601)	When the record was last updated

Errors

Status	Error	Cause
`400`	`"missing required parameter: destination_id"`	A required field is missing or empty
`422`	`"no_psp_configured"`	No PSP is configured for the requested currency
`422`	`"has already been taken"`	The `reference_id` already exists for your tenant

Get Payout

GET /api/payouts/:id

Retrieve a single payout by its Phoenix Pay UUID.

Get payout by ID

curl https://pay.phoenixverse.io/api/payouts/01912e4c-9d5e-7def-ac12-3456789012cd \
  -H "Authorization: Bearer <token>"

200 OK

{
  "id": "01912e4c-9d5e-7def-ac12-3456789012cd",
  "reference_id": "payout-78901",
  "type": "payout",
  "status": "settled",
  "psp": "chapa",
  "requested_amount": "5000.00",
  "received_amount": "5000.00",
  "currency": "ETB",
  "destination_id": "cbe_abyssinia",
  "inserted_at": "2026-03-11T12:30:00Z",
  "updated_at": "2026-03-11T12:45:00Z"
}

Errors

Status	Error	Cause
`404`	`"not_found"`	No payout with this ID exists for your tenant

Get Payout by Reference

GET /api/payouts/ref/:reference_id

Retrieve a payout using your original reference_id.

Get payout by reference ID

curl https://pay.phoenixverse.io/api/payouts/ref/payout-78901 \
  -H "Authorization: Bearer <token>"

The response format is identical to Get Payout.

Errors

Status	Error	Cause
`404`	`"not_found"`	No payout with this reference ID exists for your tenant

List Payouts

GET /api/payouts

Retrieve a paginated list of payouts for your tenant. Supports the same filtering options as deposits.

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`25`	Results per page (max 100)
`status`	string	-	Filter by status (e.g., `settled`, `pending`, `failed`)
`currency`	string	-	Filter by currency code
`from`	string (date)	-	Filter payouts created on or after this date (ISO 8601 date)
`to`	string (date)	-	Filter payouts created on or before this date (ISO 8601 date)
`search`	string	-	Search by reference ID (partial match)

List all payouts

curl "https://pay.phoenixverse.io/api/payouts?page=1&limit=10" \
  -H "Authorization: Bearer <token>"

Response

200 OK

{
  "data": [
    {
      "id": "01912e4c-9d5e-7def-ac12-3456789012cd",
      "reference_id": "payout-78901",
      "type": "payout",
      "status": "settled",
      "psp": "chapa",
      "requested_amount": "5000.00",
      "received_amount": "5000.00",
      "currency": "ETB",
      "destination_id": "cbe_abyssinia",
      "inserted_at": "2026-03-11T12:30:00Z",
      "updated_at": "2026-03-11T12:45:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 1,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

Results are sorted by creation date, newest first.

Both from and to date parameters must be provided together for date filtering to take effect. Providing only one will be ignored.

Payouts

On this page