QR Decode API

Fafanua misimbo ya QR ya wafanyabiashara ya EMV ili kupata taarifa za malipo kwa miamala laini.

Fafanua Msimbo wa QR

Pata taarifa za malipo kutoka kwa string ya msimbo wa EMV QR.


POST /business/decode-qr

Mwili wa Ombi

Sehemu	Aina	Inahitajika	Maelezo
`qrString`	string	Ndiyo	String ya data ya msimbo wa EMV QR

Miundo ya QR Inayoungwa Mkono

EMV Standard: Lipa na M-Pesa (Kenya)
TIPS: Tanzania Instant Payment System
TANQR: Tanzania QR Code Standard

Miundo yote inayoungwa mkono inafuata vipimo vya EMVCo Merchant-Presented QR Code.

Mfano wa Ombi — EMV QR ya Kenya


curl -X POST https://api.test.wakapay.io/business/decode-qr \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "qrString": "00020101021128370008ke.go.qr010801888880020504000053031045802KE5912KPLC PREPAID6006KITALE62470114KE123456789012280703LPMN0315017123456789012341630444F1"
  }'


const response = await fetch("https://api.test.wakapay.io/business/decode-qr", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    qrString:
      "00020101021128370008ke.go.qr010801888880020504000053031045802KE5912KPLC PREPAID6006KITALE62470114KE123456789012280703LPMN0315017123456789012341630444F1",
  }),
});
 
const data = await response.json();
console.log(data);

Jibu


{
  "amount": null,
  "channel": "Safaricom",
  "countryCode": "KE",
  "currency": "KES",
  "isStatic": true,
  "merchantName": "",
  "tillNumber": "01888880"
}

Sehemu za Jibu

Sehemu	Aina	Maelezo
`amount`	number \| null	Kiasi (null kwa QR ya static, thamani kwa QR ya dynamic)
`channel`	string	Mtandao wa malipo (Safaricom, CRDB, Vodacom, n.k.)
`countryCode`	string	Msimbo wa nchi (KE, TZ, n.k.)
`currency`	string	Msimbo wa sarafu (KES, TZS, n.k.)
`isStatic`	boolean	true = QR ya static (kiasi hakijawekwa), false = QR ya dynamic na kiasi kilichowekwa
`merchantName`	string	Jina la mfanyabiashara kutoka msimbo wa QR (linaweza kuwa tupu)
`tillNumber`	string	Nambari ya till au ya mfanyabiashara iliyotolewa kutoka kwa QR

Aina za Misimbo ya QR

Misimbo ya QR ya Static

Misimbo ya QR ya static haina kiasi kilichojazwa awali. Wateja wanaingiza kiasi wakati wa malipo.


{
  "amount": null,
  "isStatic": true,
  "tillNumber": "01888880"
}

Matumizi: Nambari za till, vituo vya wafanyabiashara ambapo viasi vinatofautiana kwa kila muamala.

Misimbo ya QR ya Dynamic

Misimbo ya QR ya dynamic ina kiasi maalum cha kulipwa.


{
  "amount": 1500,
  "isStatic": false,
  "tillNumber": "01888880"
}

Matumizi: Ankara, bili, vitu vya bei iliyowekwa.

Muundo wa Msimbo wa EMV QR

Msimbo wa QR wa majaribio unafafanuliwa kama ifuatavyo:

String ya QR:


00020101021128370008ke.go.qr010801888880020504000053031045802KE5912KPLC PREPAID6006KITALE62470114KE123456789012280703LPMN0315017123456789012341630444F1

Maelezo:

00020101 — Kiashiria cha muundo wa payload (toleo la EMV)
0211 — Mbinu ya kuanza
2837... — Taarifa ya akaunti ya mfanyabiashara (ina nambari ya till)
5802KE — Msimbo wa nchi (Kenya)
5912KPLC PREPAID — Jina la mfanyabiashara
6006KITALE — Mji wa mfanyabiashara

Matumizi

Fafanua na Onyesha Taarifa


async function decodeAndDisplayQR(qrCodeData) {
  const response = await fetch(
    "https://api.test.wakapay.io/business/decode-qr",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ qrString: qrCodeData }),
    },
  );
 
  const data = await response.json();
 
  // Display to user
  console.log("Channel:", data.channel);
  console.log("Till Number:", data.tillNumber);
  console.log("Country:", data.countryCode);
  console.log("Currency:", data.currency);
 
  if (data.isStatic) {
    console.log("Amount: Customer will enter amount");
  } else {
    console.log("Fixed Amount:", data.amount, data.currency);
  }
 
  return data;
}

Toa Nambari ya Till kwa Malipo


async function payToQRCode(qrString, amount) {
  // Step 1: Decode QR code
  const decodeResponse = await fetch(
    "https://api.test.wakapay.io/business/decode-qr",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ qrString: qrString }),
    },
  );
 
  const qrData = await decodeResponse.json();
 
  if (qrData.channel === "Safaricom" && qrData.countryCode === "KE") {
    // Step 2: Extract till number (remove leading zeros)
    const tillNumber = qrData.tillNumber.replace(/^0+/, "");
 
    // Step 3: Use amount from QR if dynamic, otherwise use provided amount
    const paymentAmount = qrData.isStatic ? amount : qrData.amount;
 
    // Step 4: Verify the 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: qrData.countryCode,
          type: "till",
          lipaNumber: tillNumber,
        }),
      },
    );
 
    const verifyData = await verifyResponse.json();
 
    if (!verifyData.verified) {
      throw new Error("Till number verification failed");
    }
 
    // Step 5: Process 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: qrData.currency,
          amount: paymentAmount,
          receiverLipaNumber: tillNumber,
          payoutCountry: qrData.countryCode,
          businessReference: `QR-PAY-${Date.now()}`,
          // ... other required fields
        }),
      },
    );
 
    return await paymentResponse.json();
  }
 
  throw new Error("Unsupported QR code type");
}

Thibitisha QR Kabla ya Malipo


async function validateQRCode(qrString) {
  try {
    const response = await fetch(
      "https://api.test.wakapay.io/business/decode-qr",
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${token}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ qrString: qrString }),
      },
    );
 
    const data = await response.json();
 
    return {
      valid: true,
      channel: data.channel,
      tillNumber: data.tillNumber,
      amount: data.amount,
      isStatic: data.isStatic,
      currency: data.currency,
    };
  } catch (error) {
    return {
      valid: false,
      error: error.message,
    };
  }
}

Majibu ya Makosa

422 — String ya QR Isiyo Sahihi


{
  "code": 0,
  "error": "unsupported or malformed QR payload"
}

Sababu:

String ya QR si muundo halali wa EMV
String ya QR imeharibika au haijakamilika
String ya QR haitokei katika mitandao inayoungwa mkono

422 — qrString Inakosekana


{
  "code": 0,
  "error": "unsupported or malformed QR payload"
}

400 — JSON Iliyoharibika


{
  "code": 0,
  "error": "invalid payload"
}

401 — Hakuna Authorization


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

Mitandao ya Malipo Inayoungwa Mkono

Nchi	Mtandao	Jina la Channel	Aina ya QR
Kenya (KE)	M-Pesa	Safaricom	EMV
Tanzania (TZ)	M-Pesa, Tigo, Airtel	Mbalimbali	TIPS/TANQR
Uganda (UG)	MTN, Airtel	Mbalimbali	EMV
Afrika Kusini (ZA)	Mbalimbali	Mbalimbali	EMV

Mbinu Bora

Thibitisha kabla ya malipo — Daima fafanua na uthibitishe QR kabla ya kushughulikia malipo
Shughulikia bendera ya isStatic — Angalia ikiwa kiasi kimejumuishwa au kinahitaji kuingizwa
Toa nambari ya till kwa usahihi — Ondoa sufuri za mwanzo kutoka tillNumber (mfano, “01888880” → “888880”)
Thibitisha baada ya kufafanua — Tumia kiungo cha verify-payment kuthibitisha till/paybill ni halali
Shughulikia makosa kwa unyeti — Toa ujumbe wazi kwa misimbo ya QR isiyo sahihi
Onyesha taarifa za mfanyabiashara — Onyesha channel na tillNumber kwa mtumiaji kwa uthibitisho

Majaribio

Msimbo wa QR wa TESTENV

Tumia msimbo huu wa QR kwa kujaribu katika mazingira ya majaribio:


00020101021128370008ke.go.qr010801888880020504000053031045802KE5912KPLC PREPAID6006KITALE62470114KE123456789012280703LPMN0315017123456789012341630444F1

Matokeo yaliyofafanuliwa:

Nambari ya Till: 01888880 (tumia 888880 kwa malipo)
Channel: Safaricom
Nchi: KE
Sarafu: KES
Static: true

Baada ya kufafanua, unaweza kuthibitisha na kulipa kwa till 888880 kwa kutumia viungo vya verify-payment na payout/payment.

Yanayohusiana

Uthibitishaji wa Mpokeaji — Thibitisha nambari za till zilizofafanuliwa
Payouts — Payment — Lipa kwa nambari za till/paybill zilizofafanuliwa
Kushughulikia Makosa — Shughulikia makosa ya kufafanua QR