Recipient Verification API

Thibitisha taarifa za mpokeaji kabla ya kutuma malipo ili kuhakikisha usahihi na kupunguza miamala iliyoshindwa.

Thibitisha Uhamishaji wa Pesa za Simu

Thibitisha nambari ya pochi ya pesa za simu kabla ya uhamishaji.


POST /business/verify-transfer

Mwili wa Ombi

Sehemu	Aina	Inahitajika	Maelezo
`countryCode`	string	Ndiyo	Msimbo wa nchi: `KE`, `TZ`, `UG`, `ZA`
`phoneNumber`	string	Ndiyo	Nambari ya simu yenye kiambishi cha kimataifa

Mfano wa Ombi — Nambari ya TESTENV ya Kenya


curl -X POST https://api.test.wakapay.io/business/verify-transfer \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "countryCode": "KE",
    "phoneNumber": "+254700000001"
  }'


const response = await fetch(
  "https://api.test.wakapay.io/business/verify-transfer",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      countryCode: "KE",
      phoneNumber: "+254700000001",
    }),
  },
);
 
const data = await response.json();
console.log(data);

Jibu


{
  "displayName": "Amina Mjema",
  "receiverPhone": "+254700000001",
  "verified": true
}

Sehemu za Jibu

Sehemu	Aina	Maelezo
`verified`	boolean	Ikiwa mpokeaji amethibitishwa kwa mafanikio
`displayName`	string	Jina lililosajiliwa la mmiliki wa akaunti
`receiverPhone`	string	Nambari ya simu iliyothibitishwa

Nambari za Simu za Majaribio za TESTENV

Tumia nambari hizi za simu kwa kujaribu uhamishaji wa pesa za simu:

Nchi	Nambari ya Simu	Uthibitishaji	Jina la Onyesho
Kenya (KE)	`+254700000001`	verified: true	Amina Mjema
Tanzania (TZ)	`+255700000001`	verified: true	Amina Mjema

Nambari za simu zisizo za majaribio zitarudisha verified: false na displayName tupu katika TESTENV.

Mfano wa Ombi — Nambari ya TESTENV ya Tanzania


curl -X POST https://api.test.wakapay.io/business/verify-transfer \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "countryCode": "TZ",
    "phoneNumber": "+255700000001"
  }'

Jibu — Tanzania


{
  "displayName": "Amina Mjema",
  "receiverPhone": "+255700000001",
  "verified": true
}

Mfano wa Jibu — Nambari Isiyo ya Majaribio


{
  "displayName": "",
  "receiverPhone": "+254712345678",
  "verified": false
}

Thibitisha Malipo (Till/Paybill)

Thibitisha nambari ya Paybill au Till kabla ya malipo.


POST /business/verify-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. Malipo yanaenda kwa nambari ya paybill na rejea maalum ya akaunti kwa ufuatiliaji.

Mwili wa Ombi la Till/Paybill

Sehemu	Aina	Inahitajika	Maelezo
`countryCode`	string	Ndiyo	Msimbo wa nchi: `KE`, `TZ`, `UG`, `ZA`
`type`	string	Ndiyo	Aina ya malipo: `till` au `paybill`
`lipaNumber`	string	Ndiyo	Nambari ya Till au Paybill
`accountReference`	string	Sharti	Rejea ya akaunti (inahitajika kwa paybill, acha kwa till)

Nambari za Lipa za Majaribio za TESTENV

Tumia nambari hizi kwa kujaribu malipo ya till/paybill:

Nchi	Aina	Nambari ya Lipa	Rejea ya Akaunti	Jina la Onyesho
Kenya (KE)	Till	`888880`	-	Ugali Point
Kenya (KE)	Paybill	`123456`	ABC123	Ugali Point Paybill
Tanzania (TZ)	Till	`600000`	-	Ugali Point
Tanzania (TZ)	Paybill	`700000`	ABC123	Ugali Point Paybill

Mfano wa Ombi — Till ya Kenya


curl -X POST https://api.test.wakapay.io/business/verify-payment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "countryCode": "KE",
    "type": "till",
    "lipaNumber": "888880"
  }'


const response = await fetch(
  "https://api.test.wakapay.io/business/verify-payment",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      countryCode: "KE",
      type: "till",
      lipaNumber: "888880",
    }),
  },
);
 
const data = await response.json();
console.log(data);

Jibu — Till


{
  "displayName": "Ugali Point",
  "verified": true
}

Mfano wa Ombi — Paybill ya Kenya


curl -X POST https://api.test.wakapay.io/business/verify-payment \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "countryCode": "KE",
    "type": "paybill",
    "lipaNumber": "123456",
    "accountReference": "ABC123"
  }'

Jibu — Paybill


{
  "displayName": "Ugali Point Paybill",
  "verified": true
}

Hali ya Uthibitishaji

Hali	Maelezo	Hatua
`verified: true`	Mpokeaji yupo na anaweza kupokea malipo	Endelea na malipo
`verified: false`	Mpokeaji hayupo au hafanyi kazi katika TESTENV	Angalia taarifa na ujaribu tena, au amilisha akaunti kwa uzalishaji

Matumizi

Thibitisha Kabla ya Uhamishaji wa Pesa za Simu


async function sendVerifiedTransfer(
  amount,
  currency,
  phoneNumber,
  countryCode,
  reference,
) {
  // 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: phoneNumber,
      }),
    },
  );
 
  const verifyData = await verifyResponse.json();
 
  if (!verifyData.verified) {
    throw new Error("Recipient verification failed");
  }
 
  // Step 2: Use verified name in transfer
  console.log(`Sending to: ${verifyData.displayName}`);
 
  // 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,
        receiverPhone: phoneNumber,
        payoutCountry: countryCode,
        businessReference: reference,
        // ... other required fields
      }),
    },
  );
 
  return await transferResponse.json();
}

Thibitisha Kabla ya Malipo ya Till/Paybill


async function sendVerifiedPayment(
  amount,
  currency,
  lipaNumber,
  type,
  countryCode,
  reference,
) {
  // Step 1: Verify payment recipient
  const verifyPayload = {
    countryCode: countryCode,
    type: type,
    lipaNumber: lipaNumber,
  };
 
  // Add account reference for paybill
  if (type === "paybill") {
    verifyPayload.accountReference = "ABC123";
  }
 
  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(verifyPayload),
    },
  );
 
  const verifyData = await verifyResponse.json();
 
  if (!verifyData.verified) {
    throw new Error("Payment recipient verification failed");
  }
 
  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: type,
        senderCurrency: "USD",
        receiverCurrency: currency,
        amount: amount,
        receiverLipaNumber: lipaNumber,
        payoutCountry: countryCode,
        businessReference: reference,
        // ... other required fields
      }),
    },
  );
 
  return await paymentResponse.json();
}

Majibu ya Makosa

400 — countryCode Inakosekana


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

400 — countryCode Isiyo Sahihi


{
  "code": 0,
  "error": "countryCode must be one of: KE, TZ, UG, ZA"
}

400 — phoneNumber Inakosekana


{
  "code": 0,
  "error": "empty mobile number"
}

400 — Muundo wa Simu Usio Sahihi


{
  "code": 0,
  "error": "phoneNumber must use the correct international prefix for the given countryCode"
}

400 — type Inakosekana (verify-payment)


{
  "code": 0,
  "error": "type must be \"paybill\" or \"till\""
}

400 — type Isiyo Sahihi (verify-payment)


{
  "code": 0,
  "error": "type must be \"paybill\" or \"till\""
}

400 — lipaNumber Inakosekana


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

401 — Hakuna Authorization


{
  "message": "missing value in request header"
}

Mbinu Bora

Daima thibitisha kwanza — Inazuia malipo yaliyoshindwa na kupunguza gharama
Onyesha matokeo ya uthibitishaji — Onyesha displayName kwa mtumiaji kwa uthibitisho
Shughulikia wapokeaji wasiothibitishwa — Onyesha ujumbe wa makosa wazi
Tumia nambari za TESTENV kwa majaribio — Tumia nambari za majaribio zilizotolewa katika mazingira ya majaribio
Jumuisha accountReference kwa paybill — Inahitajika kwa malipo ya aina ya paybill

Nchi Zinazoungwa Mkono

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

Yanayohusiana

Payouts — Payment (Till/Paybill) — Tuma malipo kwa till/paybill iliyothibitishwa
Payouts — Transfer (Mobile Money) — Tuma uhamishaji kwa nambari za simu zilizothibitishwa
Kushughulikia Makosa — Shughulikia makosa ya uthibitishaji