Transactions API

Query and manage transaction history and status.

Get Transaction

Retrieve transaction details by your business reference.


GET /business/transactions/{businessReference}

Path Parameters

Parameter	Type	Required	Description
`businessReference`	string	Yes	Your unique transaction reference

Example Request


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);

Get Transaction Response


{
  "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"
}

Response Fields

Field	Type	Description
`wakapayReference`	string	Wakapay transaction ID
`businessReference`	string	Your reference for tracking
`status`	string	Transaction status
`senderAmount`	number	Amount debited from sender
`senderCurrency`	string	Sender’s currency
`receiverAmount`	number	Amount received by recipient
`receiverCurrency`	string	Receiver’s currency
`createdAt`	string	Transaction creation timestamp (ISO 8601)
`updatedAt`	string	Last update timestamp (ISO 8601)

List Transactions

Retrieve a list of transactions for a time range.


GET /business/transactions

Query Parameters

Parameter	Type	Required	Description
`from`	string	Yes	Start timestamp (ISO 8601 format)
`to`	string	Yes	End timestamp (ISO 8601 format)
`status`	string	No	Filter by status: `termination_pending`, `termination_success`, `termination_failure`

Example Request - Date Range


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);

List Transactions Response


{
  "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"
}

Example Request - Filter by Status


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);

Response - Empty Range


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

Transaction Status Codes

Status	Description	Final
`termination_pending`	Transaction initiated, awaiting completion	No
`termination_success`	Successfully delivered to recipient	Yes
`termination_failure`	Transaction failed	Yes

Use Cases

Poll Transaction Status


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);

Generate Daily Report


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);

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);

List All Successful Transactions


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",
);

Error Responses

404 - Transaction Not Found


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

401 - No Authorization


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

200 - Empty Result (Missing Parameters)

If from and to parameters are missing, the API returns an empty result:


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

Date Format Requirements

All date parameters must be in ISO 8601 format:

Valid formats:

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

Examples:


// 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"

Best Practices

Use specific date ranges - Smaller date ranges return faster
Filter by status - Use status parameter to get only relevant transactions
Poll with delays - When polling status, wait 2-5 seconds between requests
Handle missing transactions - Check for 404 errors when querying by reference
Cache transaction data - Store completed transactions locally to reduce API calls

Real Test Data Examples

From the actual test results on April 12, 2026:

Successful Mobile Money Transfer


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

Returns:


{
  "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"
}

Successful Till Payment


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

Returns:


{
  "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"
}

Successful Paybill Payment


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

Returns:


{
  "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"
}

Payouts - Create transactions
Error Handling - Handle transaction errors

Transactions API

Get Transaction

Path Parameters

Example Request

Get Transaction Response

Response Fields

List Transactions

Query Parameters

Example Request - Date Range

List Transactions Response

Example Request - Filter by Status

Response - Empty Range

Transaction Status Codes

Use Cases

Poll Transaction Status

Generate Daily Report

Reconciliation

List All Successful Transactions

Error Responses

404 - Transaction Not Found

401 - No Authorization

200 - Empty Result (Missing Parameters)

Date Format Requirements

Best Practices

Real Test Data Examples

Successful Mobile Money Transfer

Successful Till Payment

Successful Paybill Payment

Related