Recurring Billing

Create Subscriptionsanchor

To create a subscription, you only need a stored payment_method_token and a plan_id. 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 payment_method_token. Here's an example:

  1. Ruby
result = gateway.subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "the_plan_id"
)

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 accountanchor

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.

  1. Ruby
result = gateway.subscription.create(
  :payment_method_token => "the_token",
  :plan_id => "silver_plan_gbp",
  :merchant_account_id => "gbp_account"
)

Overriding plan detailsanchor

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

You can override the following plan details:

Transaction flowanchor

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:

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 daysanchor

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 notificationsanchor

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.


Next Page: Managing Subscriptions →