The Ezypay subscription model allows integrators to control their billing schedules using Ezypay's system, simplifying the integration process - leaving the complex billing logic and scheduling to be handled by Ezypay. This allows you to focus on other key functionalities of your platform.

Pre-requisites

Customer created

Before billing, ensure the customer is created in Ezypay and the unique customer ID is available. Please refer to Customer Creation for more details.

Payment method collected

Ensure at least one payment method is collected and linked to the customer. Please refer to Payment Method Collection for more details.

Get started

Create a plan

Use Create Plan API to create a plan.

Provide the amount and name in the request body to create a dummy plan.
Retrieve the id of the created plan, which will be used for creating subscriptions. Multiple subscriptions can share the same plan.

{
  "amount": {
    "currency": "AUD",
    "value": 75.25
  },
  "name": "high_st_monthly_plan"
}

{
    "id": "df23b8bf-c50f-4bdc-9017-de3729833f9f",
    "status": "ACTIVE",
    "name": "high_st_monthly_plan",
    "memo": null,
    "accountingCode": null,
    "amount": {
        "currency": "AUD",
        "value": 75.25,
        "type": null
    },
    "tax": {
        "rate": 10.00
    },
    "setupPayments": null,
    "intervalUnit": "WEEK",
    "interval": 1,
    "billingStart": "IMMEDIATE",
    "billingStartValue": null,
    "billingEnd": "ONGOING",
    "billingEndValue": null,
    "firstBilling": "FULL_AMOUNT",
    "recurringBillingDay": null,
    "failedPaymentHandling": {
        "initialAction": "CONTINUE",
        "autoRetry": true,
        "retryInDays": 1,
        "maximumFailedAttempts": 5
    },
    "metadata": null,
    "createdOn": "2024-11-21T10:43:48.489"
}

Create a subscription

Use Create Subscription API to create a plan.

Use the planId from the created plan and customerId to create a subscription.
Define specific billing details in the request. Any unspecified details will inherit settings from the plan.
Retrieve and store the id of the created subscription for future subscription management.

{
    "customerId": "040d43eb-425d-4ca0-b5fd-4bc81c1650ff",
    "planId": "df23b8bf-c50f-4bdc-9017-de3729833f9f",
    "paymentMethodToken": "59cc560b-a260-4cc1-9383-134c51071edf",
    "intervalUnit": "month",
    "billingStart": "immediate",
    "interval": 1,
    "firstBilling": "prorate",
    "amount": {
        "currency": "AUD",
        "value": 220.33,
        "type": null
    }
}

{
    "id": "53f006d7-c6a5-446c-a809-03df032c7735",
    "customerId": "040d43eb-425d-4ca0-b5fd-4bc81c1650ff",
    "planId": "df23b8bf-c50f-4bdc-9017-de3729833f9f",
    "name": "high_st_monthly_plan",
    "status": "ACTIVE",
    "startDate": "2024-11-21",
    "endDate": null,
    "paymentMethodToken": "59cc560b-a260-4cc1-9383-134c51071edf",
    "accountingCode": null,
    "amount": {
        "currency": "AUD",
        "value": 220.33,
        "type": null
    },
    "tax": {
        "rate": 10.00
    },
    "nextBillingDate": "2024-12-21",
    "nextFutureInvoice": {
        "subscriptionId": "53f006d7-c6a5-446c-a809-03df032c7735",
        "date": "2024-12-21",
        "cycleStartDate": "2024-12-21",
        "cycleEndDate": "2025-01-20",
        "items": [
            {
                "description": "Standard Master/Visa Fee",
                "amount": {
                    "currency": "AUD",
                    "value": 3.14,
                    "type": null
                },
                "tax": {
                    "rate": 10.00
                },
                "id": "47f5c942-4810-4cd2-9644-8346d6ec7dc9",
                "type": "transaction_fee",
                "discounted": {
                    "currency": "AUD",
                    "value": 0.00,
                    "type": null
                },
                "accountingCode": null
            },
            {
                "description": "high_st_monthly_plan",
                "amount": {
                    "currency": "AUD",
                    "value": 220.33,
                    "type": null
                },
                "tax": {
                    "rate": 10.00
                },
                "id": "d0c431ba-315d-4434-9f25-bd59b47dadd8",
                "type": "subscription_payment",
                "discounted": {
                    "currency": "AUD",
                    "value": 0.00,
                    "type": null
                },
                "accountingCode": null
            }
        ],
        "amount": {
            "currency": "AUD",
            "value": 223.47,
            "type": null
        },
        "totalTax": {
            "currency": "AUD",
            "value": 20.32,
            "type": null
        }
    },
    "interval": 1,
    "intervalUnit": "MONTH",
    "totalPaid": {
        "currency": "AUD",
        "value": 215.59,
        "type": null
    },
    "totalBillingCycles": 1,
    "remainingToPay": null,
    "remainingBillingCycles": null,
    "endTargetAmount": null,
    "endTargetBillingCycles": null,
    "cancelledDate": null,
    "failedPaymentHandling": null,
    "failedAttemptsCount": 0,
    "totalPastDue": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "totalDiscounted": {
        "currency": "AUD",
        "value": 0.00,
        "type": null
    },
    "metadata": null,
    "createdOn": "2024-11-21T00:04:30.372",
    "autoPayment": true,
    "setupPayments": null,
    "paymentMethodInvalidReason": null,
    "paymentMethodInvalidDescription": null,
    "paymentMethodInvalid": false
}

Set up a webhook to receive updates on invoice and subscription statuses.
1. invoice_created - Invoice created by the subscription engine.
2. invoice_paid - Payment success.
3. invoice_past_due Payment failed.
4. subscription_payment_stopped - Subscription billing stops.
5. susbscription_payment_reactivate - Stopped subscription resumes billing

Best practice

Use a dummy plan for all subscription

A planId is mandatory when creating a subscription. To simplify management, create a dummy plan without specific billing details. Define subscription-specific billing details during the subscription creation step. This reduces the need to maintain both plans and subscriptions.

Plan vs subscription

What is a plan?

A plan serves as a template for subscriptions, containing billing details to be inherited by the subscription when created. Merchants can create multiple plans according to their needs, but at least one plan is required to set up customer subscriptions. Multiple subscriptions can use the same plan.

What is a subscription?

The 'subscription' is the actual billing instruction for a customer. Each subscription can only be tied to one customer and will inherit the billing details from the plan. However, subscription configuration will override the plan. For example, if a plan is updated, the existing customer's subscriptions will not be affected as they remain grandfathered to the previous plan's terms that were agreed on during signup. Plan updates will only be effective for customers' subscriptions created after the update.