Subscription payments

Subscriptions are a feature that allows you to create recurring payments for your customer. For example, collecting periodic fees for products or services provided by you.

The following will describe the features and functionality of subscriptions.

Features

Frequency

Subscriptions can be created to perform recurring payments with one of many frequency options:

• weekly
• fortnightly
• monthly
• quarterly (every 3 months)
• biannually (every 6 months)
• annually

Trial periods

When creating a subscription, you can optionally defer the first payment for a period of up to 31 days. This allows for trial periods, where your customer can try your product or service with no upfront payment. A date is simply provided to indicate when the subscription should first attempt payment.

Automatic cancellation

A subscription can be configured to cancel itself and stop further payments when a fixed date is provided.

Suspending subscriptions

If the need arises, subscriptions can be suspended so that recurring payments are put on hold.

Email communication

Subscriptions can be optionally configured to email both yourself and/or your customer to inform them when a subscription payment is successful or has failed. Emailing yourself is a convenient way of knowing if failed subscriptions need to be addressed with your customer. Being optional parameters means you can alternatively opt to perform your own communications if you prefer.

Creating a subscription

Card payment sourced subscriptions

Subscriptions can currently only be created using cards (credit, debit) as a payment source. The first thing that needs to be done to create a subscription is to create a card payment source and obtain a PaymentSourceId. You can refer to our documentation on collecting card payment sources for customers.

Steps

1. Create an order using the Create Order API and collect the orderId . This order ideally contains details pertaining to the subscription. The payment amount on the order must match the recurring payment amount of the intended subscription.
2. Collect card details and a PaymentSourceId . Note that if the card was saved to a customer, you will need that customer identifier (e.g. cust_ZKy_D3Z0TgavdMag ) when creating the subscription.
3. Create the subscription using the Create Subscription API, like below:

POST https://api.au.meetapril.io/subscriptions
Authorization: Bearer MERCHANT_SECRET_KEY
Content-Type: application/json

{
  "CreateSubscription": {
    "referenceCustomerId": "MY_CUSTOMER_12345",
    "customerId": "cust_ZKy_D3Z0TgavdMag",
    "orderId": "ordr_YsYb2aA_LFtLu_uq",
    "subscriptionAmount": {
      "amount": 6000,
      "currency": "AUD"
    },
    "paymentSourceId": "psrc_ZKy_D3Z0TgavdMal",
    "frequency": "monthly",
    "communications": {
      "emailOnSuccess": "accounts@example.com",
      "emailOnFailure": "accounts@example.com",
      "emailCustomerOnSuccess": "bob@example.com",
      "emailCustomerOnFailure": "bob@example.com"
    }
  }
}

{
  "subscriptionId": "subs_YsYb8ILpAnwGzfCv",
  "merchantId": "mcht_Ybf__sYSbienZWLk",
  "customerId": "cust_ZKy_D3Z0TgavdMag",
  "referenceCustomerId": "MY_CUSTOMER_12345",
  "orderId": "ordr_YsYb2aA_LFtLu_uq",
  "subscriptionAmount": 60000,
  "subscriptionCurrency": "AUD",
  "paymentMethodDescription": "Visa ****4242 11/2023",
  "state": "created",
  "stateUpdates": [
    {
      "state": "created",
      "updatedAt": "2022-07-06T23:34:08.046Z"
    }
  ],
  "frequency": "monthly",
  "nextPaymentScheduledAt": "2022-07-06T23:34:08.046Z",
  "cancelScheduledAt": null,
  "transactions": [],
  "communications": {
    "emailOnSuccess": "accounts@example.com",
    "emailOnFailure": "accounts@example.com",
    "emailCustomerOnSuccess": "bob@example.com",
    "emailCustomerOnFailure": "bob@example.com"
  },
  "createdAt": "2022-07-06T23:34:08.046Z",
  "updatedAt": "2022-07-06T23:34:08.046Z"
}

The above example creates a monthly $60 subscription that would initially be in the created state. This subscription is for a temporary or one-time use PaymentSourceId, so customerId can be set to null. Additionally, the subscription has been created with a referenceCustomerId of MY_CUSTOMER_12345. This is your reference to your customer. It could be an ID, name, email, etc.

Finally, the subscription has been configured

1. to email both successful and failed payments to an email address you own (e.g. accounts@example.com ), and
2. to email both successful and failed payments to the customer at bob@example.com .

With the subscription validated and successfully created, the next step is to activate it and potentially collect your first payment.

Activation

To activate the subscription, use the Update Subscription API call with the ActivateSubscription action. This API has the following parameters:

• trialUntil : Optionally set this if you want the first subscription to be executed at the provided timestamp. The date and time must be within 31 days from today.
• cancelScheduledAt : Optionally set this if you want the subscription to auto-cancel itself after the provided date.

PATCH https://api.au.meetapril.io/subscriptions/subs_YsYb8ILpAnwGzfCv
Authorization: Bearer MERCHANT_SECRET_KEY
Content-Type: application/json

{
  "ActivateSubscription": {
    "trialUntil": null,
    "cancelScheduledAt": "2022-09-06T11:00:00.000Z"
  }
}

{
  "subscriptionId": "subs_YsYb8ILpAnwGzfCv",
  "merchantId": "mcht_Ybf__sYSbienZWLk",
  "customerId": "cust_ZKy_D3Z0TgavdMag",
  "referenceCustomerId": "MY_CUSTOMER_12345",
  "orderId": "ordr_YsYb2aA_LFtLu_uq",
  "subscriptionAmount": 60000,
  "subscriptionCurrency": "AUD",
  "paymentMethodDescription": "Visa ****4242 11/2023",
  "state": "active",
  "stateUpdates": [
    {
      "state": "created",
      "updatedAt": "2022-07-06T23:34:08.046Z"
    },
    {
      "state": "active",
      "updatedAt": "2022-07-07T00:09:54.983Z"
    }
  ],
  "frequency": "monthly",
  "nextPaymentScheduledAt": "2022-08-07T00:09:54.983Z",
  "cancelScheduledAt": "2022-09-06T11:00:00.000Z",
  "transactions": [
    {
      "transactionId": "tran_YsYkWYLpAnwGzfC1",
      "status": "paid",
      "createdAt": "2022-07-07T00:10:01.986Z"
    }
  ],
  "communications": {
    "emailOnSuccess": "accounts@example.com",
    "emailOnFailure": "accounts@example.com",
    "emailCustomerOnSuccess": "bob@example.com",
    "emailCustomerOnFailure": "bob@example.com"
  },
  "createdAt": "2022-07-06T23:34:08.046Z",
  "updatedAt": "2022-07-07T00:09:54.983Z"
}

In this example, we won't start a trial. This means upon submitting this request, a payment of $60 will attempt to be collected. If successful, the subscription will be updated and returned (see JSON response). If payment fails, an HTTP 400 error is returned. In the section API error handling, it is documented further how to handle errors like this.

This subscription is now in an active state and shows when the next payment is scheduled to recur (nextPaymentScheduledAt). Additionally, because a cancellation date was provided that will occur before the subsequent payment, the subscription will become cancelled afterwards. The subscription JSON response provides details of all processed payments in the transactions array.

Re-activation

If a recurring payment fails, a subscription transitions to the inactive state. If you want the subscription to continue, simply use the Activation API with the subscriptionId again to reactivate—either as a payment now or as a new trial.

Active Lifecycle

During the active life of a subscription, it can only transition to three other states:

• inactive : the subscription has had a failed recurring payment. In this state, the subscription requires re-activation using the Activation API.
• paused : this state is applied using the Suspending feature
• cancelled : this is a terminating state applied using the Cancel API

Those state changes are illustrated below:

Retrieving subscriptions

To retrieve subscriptions, simply perform a GET request like this:

GET https://api.au.meetapril.io/subscriptions?state=inactive,cancelled
Authorization: Bearer MERCHANT_SECRET_KEY
Content-Type: application/json

This will return a paged result of matched results (the page count is indicated in the response header). In this case, the query will find all subscriptions where the state is currently inactive or cancelled. You can query using the following comma-separated list parameters:

• state
• subscriptionId
• merchantId
• customerId
• referenceCustomerId
• orderId

Modifying subscriptions

Subscriptions can be modified in the following ways. Note, a cancelled subscription can no longer be changed.

Suspending

To suspend an active subscription, the following PATCH API request is submitted:

PATCH https://api.au.meetapril.io/subscriptions/subs_YsYb8ILpAnwGzfCv
Authorization: Bearer MERCHANT_SECRET_KEY
Content-Type: application/json

{
  "UpdateSubscriptionStatus": {
    "toStatus": "suspended"
  }
}

To continue the subscription again, submit a similar request with the toStatus active.

Consider these two examples to understand how suspending works.

Example 1

Assume that a weekly subscription was meant to recur on Monday and was suspended 24 hours before on Sunday. If it were reactivated on Friday, it would instantly attempt payment to collect what was due on Monday. If payment was successful, the next payment would be on the following Monday.

Example 2

Assume that a monthly subscription was to recur on May 1st and was suspended on April 30th. If it were reactivated on August 2nd, it would instantly attempt payment to collect what was due for May, June, July, and August.

Both these examples demonstrate that suspending a subscription does not stop payments that were expected to be collected when it was active. In most cases, we don't recommend suspending subscriptions for long periods of time if this is not the desired behaviour. We recommend that when the period of suspending is not known or will likely extend the period of the subscription frequency, cancelling and re-creating a subscription is preferable.

Changing the schedule

To change the next scheduled payment and optionally set a cancellation schedule, the following PATCH API request is submitted:

PATCH https://api.au.meetapril.io/subscriptions/subs_YsYb8ILpAnwGzfCv
Authorization: Bearer MERCHANT_SECRET_KEY
Content-Type: application/json

{
  "UpdateSubscriptionSchedule": {
    "nextPaymentScheduledAt": "2022-07-15T00:00:00.000Z",
    "cancelScheduledAt": null
  }
}

cancelScheduledAt is an optional field. However, if it is omitted or set to null, it will clear an existing cancellation on the subscription. To retain the cancellation, you must re-submit the date and time.

Changing the card payment source

To change the card payment source for a subscription, the following PATCH API request is submitted:

PATCH https://api.au.meetapril.io/subscriptions/subs_YsYb8ILpAnwGzfCv
Authorization: Bearer MERCHANT_SECRET_KEY
Content-Type: application/json

{
  "UpdateSubscriptionPaymentSource": {
    "paymentSourceId": "psrc_X40XPc5wIyDaND_V",
    "customerId": "cust_ZKy_D3Z0TgavdMag"
  }
}

In this example, because the card belongs to a customer, the customer identifier must be set in the optional customerId field.

Changing the communications

To change who and when emails are sent, the following PATCH request API is submitted:

PATCH https://api.au.meetapril.io/subscriptions/subs_YsYb8ILpAnwGzfCv
Authorization: Bearer MERCHANT_SECRET_KEY
Content-Type: application/json

{
  "UpdateSubscriptionCommunications": {
    "communications": {
      "emailOnSuccess": "accounts@example.com",
      "emailOnFailure": "accounts@example.com",
      "emailCustomerOnFailure": "alice@example.com"
    }
  }
}

In this example, we retain the email communications for accounts@example.com, but change it so that alice@example.com is only emailed when a subscription has failed.

Cancel

To cancel and terminate a subscription, the following PATCH request API is submitted:

PATCH https://api.au.meetapril.io/subscriptions/subs_YsYb8ILpAnwGzfCv
Authorization: Bearer MERCHANT_SECRET_KEY
Content-Type: application/json

{
  "CancelSubscription": {}
}

API error handling

The following table defines the potential errors you can encounter when creating, activating, or modifying subscriptions. In some cases, additional detail is provided in the error JSON response.

Charge Failure Codes

Refunds

Refunding is performed at the transaction level using the CreateRefund action on the Update Transaction API. To fully or partially refund one recurring payment, select the transactionId from the transactions array on the subscription and use it as input with the refunds call.

PATCH https://api.au.meetapril.io/transactions/tran_YsYkWYLpAnwGzfC1
Authorization: Bearer MERCHANT_SECRET_KEY
Content-Type: application/json

{
  "CreateRefund": {
    "refundAmount": 1200
  }
}