Transactions API

Uliza na simamia historia na hali ya miamala.

Pata Muamala

Pata maelezo ya muamala kwa rejea yako ya biashara.


GET /business/transactions/{businessReference}

Vigezo vya Njia (Path)

Kigezo	Aina	Inahitajika	Maelezo
`businessReference`	string	Ndiyo	Rejea yako ya kipekee ya muamala

Mfano wa Ombi


curl https://api.test.wakapay.io/business/transactions/TEST-TRANSFER-KE-001 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"


const response = await fetch(
  "https://api.test.wakapay.io/business/transactions/TEST-TRANSFER-KE-001",
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  },
);
 
const data = await response.json();
console.log(data);

Jibu la Pata Muamala


{
  "businessReference": "TEST-TRANSFER-KE-001",
  "createdAt": "2026-04-12T12:09:50Z",
  "receiverAmount": 100,
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "senderCurrency": "USD",
  "status": "termination_success",
  "updatedAt": "2026-04-12T12:09:51Z",
  "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
`senderAmount`	number	Kiasi kilichokatwa kutoka kwa mtumaji
`senderCurrency`	string	Sarafu ya mtumaji
`receiverAmount`	number	Kiasi alichopokea mpokeaji
`receiverCurrency`	string	Sarafu ya mpokeaji
`createdAt`	string	Muhuri wa muda wa kuundwa kwa muamala (ISO 8601)
`updatedAt`	string	Muhuri wa muda wa sasisho la mwisho (ISO 8601)

Orodhesha Miamala

Pata orodha ya miamala kwa muda fulani.


GET /business/transactions

Vigezo vya Hoja (Query)

Kigezo	Aina	Inahitajika	Maelezo
`from`	string	Ndiyo	Muhuri wa muda wa kuanza (muundo wa ISO 8601)
`to`	string	Ndiyo	Muhuri wa muda wa kumaliza (muundo wa ISO 8601)
`status`	string	Hapana	Chuja kwa hali: `termination_pending`, `termination_success`, `termination_failure`

Mfano wa Ombi — Mfumo wa Tarehe


curl "https://api.test.wakapay.io/business/transactions?from=2026-04-12T00:00:00Z&to=2026-04-12T23:59:59Z" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"


const params = new URLSearchParams({
  from: "2026-04-12T00:00:00Z",
  to: "2026-04-12T23:59:59Z",
});
 
const response = await fetch(
  `https://api.test.wakapay.io/business/transactions?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  },
);
 
const data = await response.json();
console.log(data);

Jibu la Orodhesha Miamala


{
  "from": "2026-04-12T00:00:00Z",
  "items": [
    {
      "businessReference": "TEST-PAYMENT-KE-PAYBILL-001",
      "createdAt": "2026-04-12T12:11:26Z",
      "receiverAmount": 100,
      "receiverCurrency": "KES",
      "senderAmount": 0.7751937984496124,
      "senderCurrency": "USD",
      "status": "termination_success",
      "updatedAt": "2026-04-12T12:11:26Z",
      "wakapayReference": "3487eae9-364b-11f1-8c14-0242ac120008"
    },
    {
      "businessReference": "TEST-PAYMENT-KE-TILL-001",
      "createdAt": "2026-04-12T12:11:25Z",
      "receiverAmount": 100,
      "receiverCurrency": "KES",
      "senderAmount": 0.7751937984496124,
      "senderCurrency": "USD",
      "status": "termination_success",
      "updatedAt": "2026-04-12T12:11:26Z",
      "wakapayReference": "3454311f-364b-11f1-8c14-0242ac120008"
    },
    {
      "businessReference": "TEST-TRANSFER-KE-001",
      "createdAt": "2026-04-12T12:09:50Z",
      "receiverAmount": 100,
      "receiverCurrency": "KES",
      "senderAmount": 0.7751937984496124,
      "senderCurrency": "USD",
      "status": "termination_success",
      "updatedAt": "2026-04-12T12:09:51Z",
      "wakapayReference": "0ad0a4a6-364b-11f1-8c14-0242ac120008"
    }
  ],
  "to": "2026-04-12T23:59:59Z"
}

Mfano wa Ombi — Chuja kwa Hali


curl "https://api.test.wakapay.io/business/transactions?from=2026-04-12T00:00:00Z&to=2026-04-12T23:59:59Z&status=termination_success" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"


const params = new URLSearchParams({
  from: "2026-04-12T00:00:00Z",
  to: "2026-04-12T23:59:59Z",
  status: "termination_success",
});
 
const response = await fetch(
  `https://api.test.wakapay.io/business/transactions?${params}`,
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  },
);
 
const data = await response.json();
console.log(data);

Jibu — Mfumo Tupu


{
  "from": "2026-01-01T00:00:00Z",
  "items": [],
  "to": "2026-01-02T00:00:00Z"
}

Misimbo ya Hali ya Muamala

Hali	Maelezo	Ya Mwisho
`termination_pending`	Muamala umeanzishwa, unasubiri kukamilika	Hapana
`termination_success`	Imewasilishwa kwa mafanikio kwa mpokeaji	Ndiyo
`termination_failure`	Muamala umeshindwa	Ndiyo

Matumizi

Uliza Hali ya Muamala (Polling)


async function waitForCompletion(businessReference, maxWaitTime = 60000) {
  const startTime = Date.now();
  const pollInterval = 2000; // Poll every 2 seconds
 
  while (Date.now() - startTime < maxWaitTime) {
    const response = await fetch(
      `https://api.test.wakapay.io/business/transactions/${businessReference}`,
      {
        headers: { Authorization: `Bearer ${token}` },
      },
    );
 
    const data = await response.json();
 
    const status = data.status;
 
    // Check if transaction reached final status
    if (status === "termination_success" || status === "termination_failure") {
      return data;
    }
 
    // Wait before next poll
    await new Promise((resolve) => setTimeout(resolve, pollInterval));
  }
 
  throw new Error("Transaction status check timed out");
}
 
// Usage
const result = await waitForCompletion("TEST-TRANSFER-KE-001");
console.log("Final status:", result.status);

Tengeneza Ripoti ya Kila Siku


async function generateDailyReport(date) {
  const fromDate = new Date(date);
  fromDate.setHours(0, 0, 0, 0);
 
  const toDate = new Date(date);
  toDate.setHours(23, 59, 59, 999);
 
  const params = new URLSearchParams({
    from: fromDate.toISOString(),
    to: toDate.toISOString(),
    status: "termination_success",
  });
 
  const response = await fetch(
    `https://api.test.wakapay.io/business/transactions?${params}`,
    {
      headers: { Authorization: `Bearer ${token}` },
    },
  );
 
  const data = await response.json();
 
  // Calculate summary
  const summary = {
    date: date,
    totalTransactions: data.items.length,
    totalSent: 0,
    totalReceived: 0,
    byCurrency: {},
  };
 
  data.items.forEach((txn) => {
    summary.totalSent += txn.senderAmount;
    summary.totalReceived += txn.receiverAmount;
 
    if (!summary.byCurrency[txn.receiverCurrency]) {
      summary.byCurrency[txn.receiverCurrency] = {
        count: 0,
        amount: 0,
      };
    }
 
    summary.byCurrency[txn.receiverCurrency].count++;
    summary.byCurrency[txn.receiverCurrency].amount += txn.receiverAmount;
  });
 
  return summary;
}
 
// Usage
const report = await generateDailyReport("2026-04-12");
console.log(report);

Upatanishi (Reconciliation)


async function reconcileTransactions(expectedTransactions) {
  const results = {
    matched: [],
    missing: [],
    statusMismatch: [],
  };
 
  for (const expected of expectedTransactions) {
    try {
      const response = await fetch(
        `https://api.test.wakapay.io/business/transactions/${expected.reference}`,
        {
          headers: { Authorization: `Bearer ${token}` },
        },
      );
 
      if (response.status === 404) {
        results.missing.push(expected);
        continue;
      }
 
      const actual = await response.json();
 
      if (actual.status !== expected.expectedStatus) {
        results.statusMismatch.push({
          expected,
          actual: {
            status: actual.status,
            amount: actual.receiverAmount,
          },
        });
      } else {
        results.matched.push(actual);
      }
    } catch (error) {
      results.missing.push(expected);
    }
  }
 
  return results;
}
 
// Usage
const expectedTransactions = [
  { reference: "TEST-TRANSFER-KE-001", expectedStatus: "termination_success" },
  {
    reference: "TEST-PAYMENT-KE-TILL-001",
    expectedStatus: "termination_success",
  },
];
 
const reconciliation = await reconcileTransactions(expectedTransactions);
console.log("Matched:", reconciliation.matched.length);
console.log("Missing:", reconciliation.missing.length);
console.log("Status mismatch:", reconciliation.statusMismatch.length);

Orodhesha Miamala Yote Iliyofanikiwa


async function listSuccessfulTransactions(fromDate, toDate) {
  const params = new URLSearchParams({
    from: fromDate,
    to: toDate,
    status: "termination_success",
  });
 
  const response = await fetch(
    `https://api.test.wakapay.io/business/transactions?${params}`,
    {
      headers: { Authorization: `Bearer ${token}` },
    },
  );
 
  const data = await response.json();
 
  console.log(`Found ${data.items.length} successful transactions`);
 
  data.items.forEach((txn) => {
    console.log(
      `${txn.businessReference}: ${txn.receiverAmount} ${txn.receiverCurrency} - ${txn.status}`,
    );
  });
 
  return data.items;
}
 
// Usage
await listSuccessfulTransactions(
  "2026-04-12T00:00:00Z",
  "2026-04-12T23:59:59Z",
);

Majibu ya Makosa

404 — Muamala Haupo


{
  "code": 0,
  "error": "transaction not found"
}

401 — Hakuna Authorization


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

200 — Matokeo Tupu (Vigezo Vinakosekana)

Ikiwa vigezo vya from na to vinakosekana, API inarudisha matokeo tupu:


{
  "from": "",
  "items": [],
  "to": ""
}

Mahitaji ya Muundo wa Tarehe

Vigezo vyote vya tarehe lazima viwe katika muundo wa ISO 8601:

Miundo halali:

2026-04-12T00:00:00Z (eneo la saa la UTC)
2026-04-12T12:30:45Z
2026-04-12T23:59:59Z

Mifano:


// Start of day
const fromDate = new Date("2026-04-12");
fromDate.setHours(0, 0, 0, 0);
const from = fromDate.toISOString(); // "2026-04-12T00:00:00.000Z"
 
// End of day
const toDate = new Date("2026-04-12");
toDate.setHours(23, 59, 59, 999);
const to = toDate.toISOString(); // "2026-04-12T23:59:59.999Z"

Mbinu Bora

Tumia mifumo maalum ya tarehe — Mifumo midogo ya tarehe inarudi haraka
Chuja kwa hali — Tumia kigezo cha status kupata miamala husika tu
Polling na vichelevu — Unapouliza hali, subiri sekunde 2-5 kati ya maombi
Shughulikia miamala isiyopo — Angalia makosa ya 404 unapouliza kwa rejea
Hifadhi data ya muamala — Hifadhi miamala iliyokamilika kienyeji ili kupunguza simu za API

Mifano ya Data Halisi ya Majaribio

Kutoka matokeo halisi ya majaribio mnamo Aprili 12, 2026:

Uhamishaji wa Pesa za Simu Uliofanikiwa


curl https://api.test.wakapay.io/business/transactions/TEST-TRANSFER-KE-001 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Inarudisha:


{
  "businessReference": "TEST-TRANSFER-KE-001",
  "createdAt": "2026-04-12T12:09:50Z",
  "receiverAmount": 100,
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "senderCurrency": "USD",
  "status": "termination_success",
  "updatedAt": "2026-04-12T12:09:51Z",
  "wakapayReference": "0ad0a4a6-364b-11f1-8c14-0242ac120008"
}

Malipo ya Till Yaliyofanikiwa


curl https://api.test.wakapay.io/business/transactions/TEST-PAYMENT-KE-TILL-001 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Inarudisha:


{
  "businessReference": "TEST-PAYMENT-KE-TILL-001",
  "createdAt": "2026-04-12T12:11:25Z",
  "receiverAmount": 100,
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "senderCurrency": "USD",
  "status": "termination_success",
  "updatedAt": "2026-04-12T12:11:26Z",
  "wakapayReference": "3454311f-364b-11f1-8c14-0242ac120008"
}

Malipo ya Paybill Yaliyofanikiwa


curl https://api.test.wakapay.io/business/transactions/TEST-PAYMENT-KE-PAYBILL-001 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Inarudisha:


{
  "businessReference": "TEST-PAYMENT-KE-PAYBILL-001",
  "createdAt": "2026-04-12T12:11:26Z",
  "receiverAmount": 100,
  "receiverCurrency": "KES",
  "senderAmount": 0.7751937984496124,
  "senderCurrency": "USD",
  "status": "termination_success",
  "updatedAt": "2026-04-12T12:11:26Z",
  "wakapayReference": "3487eae9-364b-11f1-8c14-0242ac120008"
}

Yanayohusiana

Payouts — Unda miamala
Kushughulikia Makosa — Shughulikia makosa ya muamala