DocsAPI ReferencePlayground
Dashboard

Subscriptions

Create recurring payment schedules for subscription billing, membership fees, loan repayments, and other periodic charges.

Overview

The Subscriptions API enables automatic recurring payments at configurable intervals. Features include:

  • Flexible billing frequencies (daily, weekly, monthly, quarterly, yearly)
  • Configurable anchor day for monthly+ frequencies
  • Automatic retry on failed charges
  • Pause and resume capabilities
  • Charge history tracking
  • Webhook notifications for all subscription events

Billing Frequencies

FrequencyDescriptionAnchor Day
DAILYCharges every dayN/A
WEEKLYCharges every 7 daysN/A
BIWEEKLYCharges every 14 daysN/A
MONTHLYCharges once per month1-28
QUARTERLYCharges every 3 months1-28
YEARLYCharges once per year1-28

Subscription Lifecycle

StatusDescription
ACTIVESubscription is active and charges will be processed
PAUSEDTemporarily paused, no charges will be made
CANCELLEDPermanently cancelled by user/merchant
EXPIREDEnd date reached, subscription completed
FAILEDMax retries exceeded, requires attention

API Reference

Create Subscription

Create a new recurring payment subscription.

Get Subscription

Retrieve details of a specific subscription.

List Subscriptions

List all subscriptions with optional filters.

Update Subscription

Update subscription details. Only active or paused subscriptions can be updated.

Pause Subscription

Temporarily pause a subscription. No charges will be made while paused.

Resume Subscription

Resume a paused subscription.

Cancel Subscription

Permanently cancel a subscription.

Get Subscription Charges

Retrieve the charge history for a subscription.

Code Examples

Create Monthly Membership (JavaScript)

create-subscription.js
1async function createMembershipSubscription(userWalletId, merchantWalletId, plan) {
2  const API_KEY = process.env.WASAAPAY_API_KEY;
3  const BASE_URL = 'https://api.wasaapay.com/api/v1/partner';
4

5  const plans = {
6    basic: { name: 'Basic Membership', amount: 499 },
7    premium: { name: 'Premium Membership', amount: 999 },
8    enterprise: { name: 'Enterprise Membership', amount: 2999 },
9  };
10

11  const selectedPlan = plans[plan];
12  if (!selectedPlan) {
13    throw new Error('Invalid plan');
14  }
15

16  // Start on the 1st of next month
17  const startDate = new Date();
18  startDate.setMonth(startDate.getMonth() + 1);
19  startDate.setDate(1);
20  startDate.setHours(0, 0, 0, 0);
21

22  const response = await fetch(`${BASE_URL}/subscriptions`, {
23    method: 'POST',
24    headers: {
25      'Content-Type': 'application/json',
26      'X-API-Key': API_KEY,
27      'X-Idempotency-Key': `sub_${userWalletId}_${plan}_${Date.now()}`,
28    },
29    body: JSON.stringify({
30      sourceWalletId: userWalletId,
31      destinationWalletId: merchantWalletId,
32      name: selectedPlan.name,
33      amount: selectedPlan.amount,
34      frequency: 'MONTHLY',
35      startDate: startDate.toISOString(),
36      anchorDay: 1, // Charge on 1st of each month
37      externalReference: `MEMBER-${userWalletId}`,
38      metadata: { plan, signupDate: new Date().toISOString() }
39    }),
40  });
41

42  const result = await response.json();
43

44  if (!result.success) {
45    throw new Error(result.message);
46  }
47

48  console.log(`Subscription created: ${result.data.reference}`);
49  console.log(`First charge: ${result.data.nextChargeAt}`);
50

51  return result.data;
52}
53

54// Create premium subscription
55createMembershipSubscription('wallet_user123', 'wallet_merchant456', 'premium')
56  .then(sub => console.log('Subscription ID:', sub.id))
57  .catch(console.error);

Webhooks

Subscribe to events to track subscription lifecycle changes. See Webhooks documentation for setup.

Subscription Events

EventDescription
subscription.createdNew subscription created
subscription.charge.completedRecurring charge was successful
subscription.charge.failedRecurring charge failed
subscription.pausedSubscription was paused
subscription.resumedSubscription was resumed
subscription.cancelledSubscription was cancelled
subscription.expiredSubscription reached end date

Best Practices