Payouts API

Tuma malipo kwa nambari za till/paybill na pochi za pesa za simu kote Afrika.

Uhamishaji wa Pesa za Simu (Mobile Money)

Anzisha malipo ya nje kwa pochi ya pesa za simu.


POST /business/payout/transfer

Mwili wa Ombi la Pesa za Simu

Sehemu	Aina	Inahitajika	Maelezo
`senderCurrency`	string	Ndiyo	Msimbo wa sarafu ya mtumaji (USD, EUR, n.k.)
`receiverCurrency`	string	Ndiyo	Msimbo wa sarafu ya mpokeaji (KES, TZS, UGX, ZAR)
`amount`	number	Ndiyo	Kiasi cha kutuma katika sarafu ya mpokeaji
`senderFirstName`	string	Ndiyo	Jina la kwanza la mtumaji
`senderLastName`	string	Ndiyo	Jina la familia la mtumaji
`senderDob`	string	Ndiyo	Tarehe ya kuzaliwa ya mtumaji (YYYY-MM-DD)
`senderIdType`	string	Ndiyo	Aina ya kitambulisho: `passport`, `national_id`, `driving_license`
`senderIdNumber`	string	Ndiyo	Nambari ya kitambulisho ya mtumaji
`senderNationality`	string	Ndiyo	Uraia wa mtumaji (msimbo wa nchi wa herufi 2)
`senderTelephoneNo`	string	Ndiyo	Nambari ya simu ya mtumaji na msimbo wa nchi
`receiverFirstName`	string	Ndiyo	Jina la kwanza la mpokeaji
`receiverLastName`	string	Ndiyo	Jina la familia la mpokeaji
`receiverPhone`	string	Ndiyo	Nambari ya simu ya mpokeaji na msimbo wa nchi
`relationship`	string	Ndiyo	Uhusiano na mpokeaji (mfano, “Family”, “Business”)
`payoutCountry`	string	Ndiyo	Msimbo wa nchi ya kufikia (KE, TZ, UG, ZA)
`purposeOfTransfer`	string	Ndiyo	Madhumuni (angalia thamani halali hapa chini)
`sourceOfFunds`	string	Ndiyo	Chanzo cha fedha (angalia thamani halali hapa chini)
`businessReference`	string	Ndiyo	Rejea yako ya kipekee ya muamala

Mfano wa Ombi — Pesa za Simu Kenya


curl -X POST https://api.test.wakapay.io/business/payout/transfer \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "senderCurrency": "USD",
    "receiverCurrency": "KES",
    "amount": 100.0,
    "senderFirstName": "Alice",
    "senderLastName": "Smith",
    "senderDob": "1985-03-15",
    "senderIdType": "passport",
    "senderIdNumber": "AB1234567",
    "senderNationality": "TZ",
    "senderTelephoneNo": "+255712345678",
    "receiverFirstName": "John",
    "receiverLastName": "Doe",
    "receiverPhone": "+254700000001",
    "relationship": "Family",
    "payoutCountry": "KE",
    "purposeOfTransfer": "family_support",
    "sourceOfFunds": "salary",
    "businessReference": "TEST-TRANSFER-KE-001"
  }'


const response = await fetch(
  "https://api.test.wakapay.io/business/payout/transfer",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      senderCurrency: "USD",
      receiverCurrency: "KES",
      amount: 100.0,
      senderFirstName: "Alice",
      senderLastName: "Smith",
      senderDob: "1985-03-15",
      senderIdType: "passport",
      senderIdNumber: "AB1234567",
      senderNationality: "TZ",
      senderTelephoneNo: "+255712345678",
      receiverFirstName: "John",
      receiverLastName: "Doe",
      receiverPhone: "+254700000001",
      relationship: "Family",
      payoutCountry: "KE",
      purposeOfTransfer: "family_support",
      sourceOfFunds: "salary",
      businessReference: "TEST-TRANSFER-KE-001",
    }),
  },
);
 
const data = await response.json();
console.log(data);

Jibu la Pesa za Simu (201 Created)


{
  "businessReference": "TEST-TRANSFER-KE-001",
  "receiverAmount": 100,
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "senderCurrency": "USD",
  "status": "termination_success",
  "totalDebited": 0.7906976744186047,
  "wakapayReference": "0ad0a4a6-364b-11f1-8c14-0242ac120008"
}

Sehemu za Jibu

Sehemu	Aina	Maelezo
`wakapayReference`	string	Kitambulisho cha muamala cha Wakapay
`businessReference`	string	Rejea yako kwa ufuatiliaji
`status`	string	Hali ya muamala (termination_success, termination_pending, termination_failure)
`senderAmount`	number	Kiasi kilichokatwa kutoka pochi ya mtumaji
`senderCurrency`	string	Sarafu ya mtumaji
`receiverAmount`	number	Kiasi alichopokea mpokeaji
`receiverCurrency`	string	Sarafu ya mpokeaji
`totalDebited`	number	Jumla ya kiasi kilichokatwa (pamoja na ada)

Malipo kwa Paybill / Till

Anzisha malipo kwa nambari ya Paybill au Till.


POST /business/payout/payment

Tofauti kati ya Till na Paybill:

Till (Lipa Number) — Hakuna rejea ya akaunti inayohitajika. Malipo yanaenda moja kwa moja kwa nambari ya till.
Paybill — Inahitaji rejea ya akaunti (receiverAccount). Malipo yanaenda kwa nambari ya paybill na rejea maalum ya akaunti kwa ufuatiliaji.

Mwili wa Ombi la Till/Paybill

Sehemu	Aina	Inahitajika	Maelezo
`type`	string	Ndiyo	Aina ya malipo: `paybill` au `till`
`senderCurrency`	string	Ndiyo	Msimbo wa sarafu ya mtumaji (USD, EUR, n.k.)
`receiverCurrency`	string	Ndiyo	Msimbo wa sarafu ya mpokeaji (KES, TZS, UGX, ZAR)
`amount`	number	Ndiyo	Kiasi cha kutuma katika sarafu ya mpokeaji
`senderFirstName`	string	Ndiyo	Jina la kwanza la mtumaji
`senderLastName`	string	Ndiyo	Jina la familia la mtumaji
`senderDob`	string	Ndiyo	Tarehe ya kuzaliwa ya mtumaji (YYYY-MM-DD)
`senderIdType`	string	Ndiyo	Aina ya kitambulisho: `passport`, `national_id`, `driving_license`
`senderIdNumber`	string	Ndiyo	Nambari ya kitambulisho ya mtumaji
`senderNationality`	string	Ndiyo	Uraia wa mtumaji (msimbo wa nchi wa herufi 2)
`senderTelephoneNo`	string	Ndiyo	Nambari ya simu ya mtumaji na msimbo wa nchi
`receiverFirstName`	string	Ndiyo	Jina la kwanza la mpokeaji
`receiverLastName`	string	Ndiyo	Jina la familia la mpokeaji
`receiverLipaNumber`	string	Ndiyo	Nambari ya Paybill au Till
`receiverAccount`	string	Sharti	Akaunti/rejea ya paybill (inahitajika kwa paybill, acha kwa till)
`relationship`	string	Ndiyo	Uhusiano na mpokeaji (mfano, “Family”, “Business”)
`payoutCountry`	string	Ndiyo	Msimbo wa nchi ya kufikia (KE, TZ, UG, ZA)
`purposeOfTransfer`	string	Ndiyo	Madhumuni (angalia thamani halali hapa chini)
`sourceOfFunds`	string	Ndiyo	Chanzo cha fedha (angalia thamani halali hapa chini)
`businessReference`	string	Ndiyo	Rejea yako ya kipekee ya muamala

Mfano wa Ombi — Malipo ya Till


curl -X POST https://api.test.wakapay.io/business/payout/payment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "till",
    "senderCurrency": "USD",
    "receiverCurrency": "KES",
    "amount": 100.0,
    "senderFirstName": "Alice",
    "senderLastName": "Smith",
    "senderDob": "1985-03-15",
    "senderIdType": "passport",
    "senderIdNumber": "AB1234567",
    "senderNationality": "TZ",
    "senderTelephoneNo": "+255712345678",
    "receiverFirstName": "John",
    "receiverLastName": "Doe",
    "receiverLipaNumber": "888880",
    "relationship": "Family",
    "payoutCountry": "KE",
    "purposeOfTransfer": "family_support",
    "sourceOfFunds": "salary",
    "businessReference": "TEST-PAYMENT-KE-TILL-001"
  }'


const response = await fetch(
  "https://api.test.wakapay.io/business/payout/payment",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "till",
      senderCurrency: "USD",
      receiverCurrency: "KES",
      amount: 100.0,
      senderFirstName: "Alice",
      senderLastName: "Smith",
      senderDob: "1985-03-15",
      senderIdType: "passport",
      senderIdNumber: "AB1234567",
      senderNationality: "TZ",
      senderTelephoneNo: "+255712345678",
      receiverFirstName: "John",
      receiverLastName: "Doe",
      receiverLipaNumber: "888880",
      relationship: "Family",
      payoutCountry: "KE",
      purposeOfTransfer: "family_support",
      sourceOfFunds: "salary",
      businessReference: "TEST-PAYMENT-KE-TILL-001",
    }),
  },
);
 
const data = await response.json();
console.log(data);

Jibu la Till (201 Created)


{
  "businessReference": "TEST-PAYMENT-KE-TILL-001",
  "receiverAmount": 100,
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "senderCurrency": "USD",
  "status": "termination_success",
  "totalDebited": 0.7906976744186047,
  "wakapayReference": "3454311f-364b-11f1-8c14-0242ac120008"
}

Mfano wa Ombi — Malipo ya Paybill


curl -X POST https://api.test.wakapay.io/business/payout/payment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "paybill",
    "senderCurrency": "USD",
    "receiverCurrency": "KES",
    "amount": 100.0,
    "senderFirstName": "Alice",
    "senderLastName": "Smith",
    "senderDob": "1985-03-15",
    "senderIdType": "passport",
    "senderIdNumber": "AB1234567",
    "senderNationality": "TZ",
    "senderTelephoneNo": "+255712345678",
    "receiverFirstName": "John",
    "receiverLastName": "Doe",
    "receiverLipaNumber": "123456",
    "receiverAccount": "ABC123",
    "relationship": "Family",
    "payoutCountry": "KE",
    "purposeOfTransfer": "family_support",
    "sourceOfFunds": "salary",
    "businessReference": "TEST-PAYMENT-KE-PAYBILL-001"
  }'

Jibu — Paybill (201 Created)


{
  "businessReference": "TEST-PAYMENT-KE-PAYBILL-001",
  "receiverAmount": 100,
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "senderCurrency": "USD",
  "status": "termination_success",
  "totalDebited": 0.7906976744186047,
  "wakapayReference": "3487eae9-364b-11f1-8c14-0242ac120008"
}

Thamani za Hali ya Muamala

Hali	Maelezo
`termination_pending`	Muamala umeanzishwa, unasubiri kukamilika
`termination_success`	Muamala umekamilika kwa mafanikio
`termination_failure`	Muamala umeshindwa

Madhumuni ya Uhamishaji — Thamani Halali

Thamani zote halali za sehemu ya purposeOfTransfer:

family_support — Msaada wa familia na remittances
education — Gharama za elimu
business_payment — Malipo yanayohusiana na biashara
medical — Gharama za matibabu
investment — Madhumuni ya uwekezaji
construction — Gharama za ujenzi
rent — Kodi na nyumba
general — Madhumuni ya jumla
fuel — Mafuta na nishati
repairs — Matengenezo na ukarabati
gift — Zawadi
personal_care — Gharama za huduma za kibinafsi
food_and_groceries — Chakula na vyakula
transport — Usafiri
travel — Gharama za safari
shopping — Ununuzi
entertainment — Burudani
donations — Michango ya hisani
other — Madhumuni mengine

Chanzo cha Fedha — Thamani Halali

Thamani zote halali za sehemu ya sourceOfFunds:

salary — Mshahara wa ajira
savings — Akiba ya kibinafsi
business_income — Mapato ya biashara
sale_of_assets — Mauzo ya mali
investment_income — Mapato ya uwekezaji
other — Vyanzo vingine

Vitambulisho vya Majaribio vya TESTENV

Nambari za Simu za Majaribio (Pesa za Simu)

Nchi	Nambari ya Simu	Hali	Jina la Onyesho
Kenya (KE)	`+254700000001`	Imethibitishwa, malipo yamefanikiwa	Amina Mjema
Tanzania (TZ)	`+255700000001`	Imethibitishwa, hakuna kiwango cha FX	Amina Mjema

Nambari za Lipa za Majaribio (Till/Paybill)

Nchi	Aina	Nambari	Rejea ya Akaunti	Hali
Kenya (KE)	Till	`888880`	-	Imethibitishwa, malipo yamefanikiwa
Kenya (KE)	Paybill	`123456`	ABC123	Imethibitishwa, malipo yamefanikiwa
Tanzania (TZ)	Till	`600000`	-	Imethibitishwa, hakuna kiwango cha FX
Tanzania (TZ)	Paybill	`700000`	ABC123	Imethibitishwa, hakuna kiwango cha FX

Kumbuka: Kiwango cha FX cha USD→KES tu ndio kimewekwa katika TESTENV. Malipo ya TZS yatashindwa na kosa la “rate USD_TZS not configured”.

Majibu ya Makosa

400 — Sehemu Inayohitajika Inakosekana


{
  "code": 0,
  "error": "receiverPhone is required"
}


{
  "code": 0,
  "error": "receiverLipaNumber is required"
}

400 — purposeOfTransfer Isiyo Sahihi


{
  "code": 0,
  "error": "purposeOfTransfer must be one of: [family_support, education, business_payment, medical, investment, construction, rent, general, fuel, repairs, gift, personal_care, food_and_groceries, transport, travel, shopping, entertainment, donations, other]"
}

400 — sourceOfFunds Isiyo Sahihi


{
  "code": 0,
  "error": "sourceOfFunds must be one of: [salary, savings, business_income, sale_of_assets, investment_income, other]"
}

404 — Kiwango cha FX Hakijawekwa


{
  "code": 0,
  "error": "rate USD_TZS not configured"
}

409 — Rejea Iliyorudiwa


{
  "code": 0,
  "error": "duplicate reference"
}

412 — Salio Halitoshi


{
  "code": 0,
  "error": "insufficient available balance"
}

422 — Akaunti Haifanyi Kazi


{
  "code": 0,
  "error": "account not active"
}

Kumbuka: Nambari za simu zisizo za majaribio katika TESTENV zitarudisha kosa hili.

Matumizi

Tuma Uhamishaji wa Pesa za Simu


async function sendMobileMoneyTransfer(phone, amount, currency, countryCode) {
  // Step 1: Verify recipient
  const verifyResponse = await fetch(
    "https://api.test.wakapay.io/business/verify-transfer",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        countryCode: countryCode,
        phoneNumber: phone,
      }),
    },
  );
 
  const verifyData = await verifyResponse.json();
 
  if (!verifyData.verified) {
    throw new Error("Recipient not verified");
  }
 
  console.log(`Sending to: ${verifyData.displayName}`);
 
  // Step 2: Check FX rate
  const rateResponse = await fetch(
    `https://api.test.wakapay.io/business/rate?from=USD&to=${currency}`,
    {
      headers: { Authorization: `Bearer ${token}` },
    },
  );
 
  const rateData = await rateResponse.json();
  console.log(`FX Rate: ${rateData.rate}`);
 
  // Step 3: Send transfer
  const transferResponse = await fetch(
    "https://api.test.wakapay.io/business/payout/transfer",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        senderCurrency: "USD",
        receiverCurrency: currency,
        amount: amount,
        senderFirstName: "Alice",
        senderLastName: "Smith",
        senderDob: "1985-03-15",
        senderIdType: "passport",
        senderIdNumber: "AB1234567",
        senderNationality: "TZ",
        senderTelephoneNo: "+255712345678",
        receiverFirstName: verifyData.displayName.split(" ")[0],
        receiverLastName: verifyData.displayName.split(" ")[1] || "User",
        receiverPhone: phone,
        relationship: "Family",
        payoutCountry: countryCode,
        purposeOfTransfer: "family_support",
        sourceOfFunds: "salary",
        businessReference: `TRF-${Date.now()}`,
      }),
    },
  );
 
  return await transferResponse.json();
}
 
// Usage
await sendMobileMoneyTransfer("+254700000001", 100, "KES", "KE");

Tuma Malipo ya Till


async function sendTillPayment(tillNumber, amount, currency, countryCode) {
  // Step 1: Verify till number
  const verifyResponse = await fetch(
    "https://api.test.wakapay.io/business/verify-payment",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        countryCode: countryCode,
        type: "till",
        lipaNumber: tillNumber,
      }),
    },
  );
 
  const verifyData = await verifyResponse.json();
 
  if (!verifyData.verified) {
    throw new Error("Till number not verified");
  }
 
  console.log(`Paying to: ${verifyData.displayName}`);
 
  // Step 2: Send payment
  const paymentResponse = await fetch(
    "https://api.test.wakapay.io/business/payout/payment",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        type: "till",
        senderCurrency: "USD",
        receiverCurrency: currency,
        amount: amount,
        senderFirstName: "Alice",
        senderLastName: "Smith",
        senderDob: "1985-03-15",
        senderIdType: "passport",
        senderIdNumber: "AB1234567",
        senderNationality: "TZ",
        senderTelephoneNo: "+255712345678",
        receiverFirstName: "Merchant",
        receiverLastName: "Name",
        receiverLipaNumber: tillNumber,
        relationship: "Business",
        payoutCountry: countryCode,
        purposeOfTransfer: "business_payment",
        sourceOfFunds: "business_income",
        businessReference: `TILL-${Date.now()}`,
      }),
    },
  );
 
  return await paymentResponse.json();
}
 
// Usage
await sendTillPayment("888880", 100, "KES", "KE");

Mbinu Bora

Daima tumia rejea za kipekee — Inazuia malipo ya marudufu (kosa la 409)
Thibitisha wapokeaji kwanza — Tumia viungo vya verify-transfer au verify-payment
Angalia viwango vya FX — Hakikisha jozi ya sarafu imewekwa kabla ya malipo ya sarafu mbalimbali
Onyesha matokeo ya uthibitishaji — Onyesha displayName kwa mtumiaji kwa uthibitisho
Shughulikia makosa kwa unyeti — Tekeleza ushughulikiaji sahihi wa makosa kwa misimbo yote ya makosa
Tumia nambari za TESTENV kwa majaribio — Tumia vitambulisho vya majaribio vilivyotolewa katika mazingira ya majaribio
Jumuisha receiverAccount kwa paybill — Sehemu inayohitajika kwa malipo ya paybill

Nchi Zinazoungwa Mkono

KE — Kenya
TZ — Tanzania
UG — Uganda
ZA — Afrika Kusini

Yanayohusiana

Uthibitishaji wa Mpokeaji — Thibitisha wapokeaji kabla ya kutuma
Miamala — Angalia hali ya malipo
Kushughulikia Makosa — Shughulikia makosa ya malipo ya nje