Recurring Billing

Create Subscriptions

To create a subscription, you only need a stored paymentMethodToken and a planId. The subscription will be created using the price, trial duration (if any), billing details, and any add-ons or discounts specified within the plan's details.

A subscription can be created using either a payment method token or - under certain conditions - a payment method nonce.

The payment method must be vaulted before you can associate it with a subscription, so it's usually simplest to refer to the payment method using its paymentMethodToken . Here's an example:

Java

SubscriptionRequest request = new SubscriptionRequest()
  .paymentMethodToken("the_token")
  .planId("the_plan_id");

Result<Subscription> result = gateway.subscription().create(request);

However, payment method tokens do not carry any 3D Secure data. If you use 3D Secure and need to apply 3DS to the first transaction of a new subscription, you must create the subscription using a 3DS-enriched payment method nonce .

Specifying merchant account

If you have multiple merchant accounts, you can pass the merchant account ID to specify which merchant account to use to process transactions for the subscription. If a merchant account ID is not passed, we'll use your default merchant account. If you would like to change which merchant account is default, contact us.

Important

The specified merchant account must be in the same currency as the subscription plan, or any attempted subscription transactions will trigger a validation error. If you want to use a merchant account with a different currency, you must create a new plan with the indicated currency.

Java

SubscriptionRequest request = new SubscriptionRequest()
    .paymentMethodToken("the_token")
    .planId("silver_plan_gbp")
    .merchantAccountId("gbp_account");

Result<subscription> result = gateway.subscription().create(request);

Overriding plan details

Certain plan attributes can be overridden when you pass the details you want to change along with the paymentMethodToken and planId.

You can override the following plan details:

Transaction flow

The transaction flow depends on when the subscription is set to start and whether it includes a trial period.

If there is no trial period and the subscription is set to bill immediately:

We'll attempt to charge the customer and submit the transaction for settlement right away
If that transaction attempt is successful:
- The subscription will be created
- Its status will be Active
- You'll receive a successful result that includes a subscription object with its associated transaction details
If that transaction attempt fails:
- No subscription will be created
- You'll receive an error result with information about why the transaction request failed

If there is no trial period and the subscription is set to bill in the future:

The subscription will be created immediately, but its status will be Pending until the first billing date is reached
On the first billing date, we'll attempt to charge the customer and submit the transaction for settlement
If that transaction attempt is successful, the subscription status will change to Active
If that transaction attempt fails, the subscription status will change to Past Due

If the subscription has a trial period:

The subscription will be created and its status will be Active immediately
We'll attempt to charge the customer at the end of the trial period
If that transaction attempt is successful, the subscription status will remain Active
If that transaction attempt fails, the subscription status will change to Past Due

Note

Before setting up trial periods, be sure to read the risks and requirements in the Trial Periods support article.

Check out this diagram to see all of the possible transaction flows for subscriptions.

Subscription days

Each subscription day runs from midnight to midnight in the time zone associated with your gateway account, regardless of the time of day the subscription was created. For example, a subscription created at 11pm in your Control Panel time zone will be in its second day at midnight.

Email notifications

The gateway can send emails to customers based on recurring billing events. You'll need to set up your DNS record to allow the gateway to send email from your domain, and then contact us to enable this feature.