Skip to main content

​
Overview

The Mobile Payout API lets you send funds directly to a recipient’s mobile money wallet. Use the preview endpoint first to see fee breakdowns, then call initiate to execute the transfer.

​
Preview Mobile Payout

Calculate fees and preview the payout before committing. 
POST /v1/payouts/mobile/preview

​
Authentication

Authorization: Bearer {{api_key}}

​
Request Headers

HeaderValue
Acceptapplication/json
Content-Typeapplication/json

​
Request Body

FieldTypeRequiredDescription
amountintegerrequiredAmount to send in the specified currency
currencystringrequiredCurrency code (e.g., TZS)
phone_numberstringrequiredRecipient’s phone number (e.g., 07XXXXXXXX)
metadataobjectoptionalArbitrary key-value pairs for your reference,
maximum of 3 items with length of less that 100 characters each

​
Example Request

curl -X POST https://pesahub.test/api/v1/payouts/mobile/preview \
  -H "Authorization: Bearer {{api_key}}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500,
    "currency": "TZS",
    "phone_number": "07XXXXXXXX",
    "metadata": {
      "order_id": "order_001",
      "note": "Payment for services"
    }
  }'

const response = await fetch('https://pesahub.test/api/v1/payouts/mobile/preview', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 1500,
    currency: 'TZS',
    phone_number: '07XXXXXXXX',
    metadata: {
      order_id: 'order_001',
      note: 'Payment for services',
    },
  }),
});

​
Initiate Mobile Payout

Execute the mobile money transfer to the recipient. 
POST /v1/payouts/mobile

​
Request Body

Same fields as the preview endpoint.
FieldTypeRequiredDescription
amountintegerrequiredAmount to send
currencystringrequiredCurrency code (e.g., TZS)
phone_numberstringrequiredRecipient’s phone number
metadataobjectoptionalArbitrary key-value pairs for your reference,
max of 3 items with length of less than 100 characters each

​
Example Request

curl -X POST https://pesahub.test/api/v1/payouts/mobile \
  -H "Authorization: Bearer {{api_key}}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "TZS",
    "phone_number": "07XXXXXXXX",
    "metadata": {
      "order_id": "order_001",
      "note": "Payment for services"
    }
  }'

const response = await fetch('https://pesahub.test/api/v1/payouts/mobile', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Accept': 'application/json',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 1000,
    currency: 'TZS',
    phone_number: '07XXXXXXXX',
    metadata: {
      order_id: 'order_001',
      note: 'Payment for services',
    },
  }),
});
Always run a preview before initiating a payout to confirm fees and ensure the recipient details are correct.