.png)
Subscriptions
(Recurring Billing)
Subscriptions allow for setup of a series of automated transactions managed by Moneris. Moneris processes these transactions on the merchant’s behalf according to the schedule agreed upon between the merchant and their customer. This feature is often used for subscription services where the same amount is billed with regular frequency.
1. Moneris-Managed vs. Merchant-Managed Recurring Payments
As the scheduled series created by the Subscriptions endpoints are managed by Moneris, there are important considerations on how it can be used.
Other than the initial payment, configured separately via the field oneTimeAmount, all other payments in the series are set for the same amount via billingAmount. The series amount can be adjusted later if needed, but if your use-case involves a series of transactions where the amounts often differ you may find it easier to manage the series yourself.
The schedule is fixed and several parameters cannot be adjusted afterward. You may extend the series by adding additional payments OR pause the series, to prevent payments from occurring per the schedule until resumed. But you cannot change the type of interval or the frequency between payments; a schedule set for once every 4th month cannot be updated to a schedule for once every 2nd week. If your use-case has irregular intervals without a schedule, you will need to use the main Payment endpoint for each transaction instead.
2. Collect Cardholder Data
Before you can send the server-to-server API call for the payment, you will need to collect credit card details from the cardholder to populate your transaction. Three options are available:
Hosted Tokenization: This Moneris service embeds a box for card data input on your website hosted on Moneris systems and returns a temporary token for use in the payment instead. This protects your website from handling sensitive card data directly and avoids burdens of certification to Payment Card Industry (PCI) compliance.
Merchant Collection: You can collect credit card numbers, expiry dates, and card verification details directly from the cardholder on your website and handle that data throughout the payment process. Doing so requires PCI compliance to ensure the security of the data.
Payment Method On-file: If you have stored a payment method for this cardholder previously, such as a permanent token in the Moneris Vault service or as a Payment Method via our API, you no longer need to collect it again on subsequent transactions and can proceed with next steps. During the API call, you can use these stored methods in place of cardholder input.
3. 3-D Secure Authentication
If you already have 3-D Secure features enabled on your merchant account, see here for steps on implementing it before the payment transaction flow. Link to 3DS overview here.
Moneris recommends performing 3-D Secure Authentication before initiating the payment transaction. This eFraud feature is designed to reduce card not present fraud by making a risk assessment based on transaction and device data while also supporting further risk minimization measures such as a challenge to the cardholder. In some cases, a liability shift takes effect for certain card-not-present fraud-related chargebacks enabling the merchant to provide goods and services with confidence.
4. Creating Subscriptions Schedule
Your server sends a request to Moneris via an API call with the details for the schedule of recurring payments. This call uses the POST /subscriptions endpoint, with important context on the following parameters:
“oneTimeAmount”
Including this field generates an additional payment processed immediately prior to creation of the subscriptions schedule. This payment’s amount can differs from the rest of the series defined by billingAmount. Often oneTimeAmount is used in situations where the first transaction includes additional fees, such as an initial charge for membership of $200 (the one-time amount) before an annual subscription of $60 (the recurring amount)
When this field is omitted, Moneris automatically performs a validation instead to ensure payment method data is valid.
“billingIntervalUnit”
Controls whether the subscription series occurs on a daily (DAY), weekly (WEEK), or monthly (MONTH) basis.
For a monthly series that occurs on the last day of each month, use END_OF_MONTH instead; Moneris will automatically adjust the recur dates to match the last day, whether the month ends on a 28th, 29th, 30th, or 31st. Avoid using MONTH interval units on last days like the 29th, 30th, or 31st of a month, as Moneris systems will be forced to adjust when payments occur on a month without as many days.
“billingIntervalFrequency”
Controls how often payments occur. On a frequency of 1, the payments occur once per day/week/month/end-of-month, while setting the frequency higher causes the schedule to “skip” interval units, such that a frequency of 2 means payments occur every 2nd day/week/month.
“billingIntervalCount”
Controls how many payments will occur in the series.
If you are including a oneTimeAmount in the request body, that additional transaction is separate from the interval count for the series of payments.
Subscriptions rely on a Payment Method within Moneris systems used for each payment in the series. The “paymentMethod” object has a one-of schema for the various different possible payment methods viable for a Subscription schedule. Regardless of the Payment Method used, you must include the “credentialOnFileInformation” object with a “paymentInformation” of FIRST and a “paymentIndicator” of RECURRING.
5. Credential-on-file for subscriptions
Moneris-managed subsequent transactions will adjust the COF data as necessary on your behalf to use “paymentInformation” as SUBSEQUENT.
Learn more about responses with the link below
Moneris returns a response to your server with data on the success or failure of the request. The HTTP response status code and the contents of the “transactionDetails” object in the response body will inform you on the results of the transaction. Note that if the initial one-time payment or card validation decline, you will receive an error for the entire recurring payment series.
6. Subscription Webhooks
Upon a successful Subscription Payment, Moneris will send information to your server with details about the transaction. This is performed via a POST call to “callbackUrl” that you have specified in your Create Subscription request.
Samples
Additional Information
Learn more with the API Definitions
Peruse the endpoints, request/response formats, and authentication methods covered in this scenario.
.svg)