DocsAPI ReferencePlayground
Dashboard

Scheduled Payments

Schedule payments to execute automatically at a future date and time. Perfect for bill payments, payroll, or any planned disbursements.

Overview

The Scheduled Payments API allows you to create payments that will be automatically processed at a specified future time. Features include:

  • Schedule transfers, withdrawals, or bill payments
  • Specify exact date and time with timezone support
  • Update or cancel scheduled payments before execution
  • Receive webhooks when payments are processed
  • Track payment status from scheduled to completed

Payment Lifecycle

StatusDescription
SCHEDULEDPayment is scheduled and waiting for execution time
PROCESSINGPayment is being executed
COMPLETEDPayment was successful
FAILEDPayment execution failed
CANCELLEDPayment was cancelled before execution

API Reference

Create Scheduled Payment

Schedule a new payment for future execution. The payment will be automatically processed at the specified time.

Get Scheduled Payment

Retrieve details of a specific scheduled payment.

List Scheduled Payments

List all scheduled payments with optional filters.

Update Scheduled Payment

Update a scheduled payment before it's processed. Only payments with status SCHEDULED can be updated.

Cancel Scheduled Payment

Cancel a scheduled payment. Only payments with status SCHEDULED can be cancelled.

Code Examples

Schedule a Payroll Transfer (JavaScript)

schedule-payroll.js
1async function schedulePayrollTransfer(walletId, recipientAccount, amount, payDate) {
2  const API_KEY = process.env.WASAAPAY_API_KEY;
3  const BASE_URL = 'https://api.wasaapay.com/api/v1/partner';
4

5  const response = await fetch(`${BASE_URL}/scheduled-payments`, {
6    method: 'POST',
7    headers: {
8      'Content-Type': 'application/json',
9      'X-API-Key': API_KEY,
10      'X-Idempotency-Key': `payroll_${payDate}_${recipientAccount}`,
11    },
12    body: JSON.stringify({
13      sourceWalletId: walletId,
14      type: 'TRANSFER',
15      amount: amount,
16      scheduledAt: payDate, // ISO 8601 format
17      timezone: 'Africa/Nairobi',
18      destinationAccountNumber: recipientAccount,
19      externalReference: `PAYROLL-${new Date().toISOString().slice(0,7)}`,
20      metadata: {
21        paymentType: 'salary',
22        payPeriod: new Date(payDate).toISOString().slice(0,7)
23      }
24    }),
25  });
26

27  const result = await response.json();
28

29  if (!result.success) {
30    throw new Error(result.message);
31  }
32

33  console.log(`Payment scheduled: ${result.data.reference}`);
34  console.log(`Will execute at: ${result.data.scheduledAt}`);
35

36  return result.data;
37}
38

39// Schedule salary for the 25th at 9 AM
40const payDate = new Date();
41payDate.setDate(25);
42payDate.setHours(9, 0, 0, 0);
43

44schedulePayrollTransfer(
45  'wallet_abc123',
46  '0712345678',
47  50000,
48  payDate.toISOString()
49).catch(console.error);

Webhooks

Receive notifications when scheduled payments are processed. See the Webhooks documentation for setup.

Scheduled Payment Events

EventDescription
scheduled_payment.createdA new scheduled payment was created
scheduled_payment.processingPayment execution has started
scheduled_payment.completedPayment was successfully processed
scheduled_payment.failedPayment execution failed
scheduled_payment.cancelledPayment was cancelled

Best Practices