Converge provides a set of features that allows users to handle recurring charges. Merchants are allowed to use a stored card resource to process each of their payment increments automatically when the interval between them has elapsed. If the merchant chooses to use resources provided by Converge (e.g., stored cards, plans, subscriptions, and shoppers), Converge will manage the payment processing schedule.
Implementing plans and subscriptions is ideal for the following:
- For businesses in the software as a service (SaaS) or service as a product (SaaP) markets that need to collect recurring payments from customers.
- For businesses that collect payments for their product or service in multiple installments.
Back Office UI
Create a Plan
A plan provides a template that is used to pay for products and services and is created by the merchant. When a customer subscribes to a plan (e.g., a gym membership or online course), a merchant can set up the frequency of payments based on the customer's preferences.
- Click the Recurring menu item.
- Click the Plans tab.
- Click the New Plan button. The New Subscription Plan window appears.
- Enter the Plan Name.
- In the Pricing section, enter the Subscription Amount.
- If you have an initial rate that is different from the subscription amount, do the following:
- Toggle the Introductory Rate button and enter the Introductory Amount.
- Enter how many times the initial rate will be applied in the Introductory Billing Period field.
- In the Billing Frequency section, select the Billing Frequency from the dropdown list. Depending on your selection, enter the number of times that the bill will occur in the fields that appear.
- Select an option on how the plan will end. Options are the following:
- End subscription after X billing periods - If selected, enter the number of billing periods in the field.
- End when cancelled or scheduled - If selected, the plan will remain active until a subscription is cancelled or if an end date is specified when creating the subscription.
- Click the Create Plan button to save your plan.
Depending on your account settings, you may need to select a currency for the subscription amount and the introductory amount. If your account is set to use only one currency, the default currency will be used.
Create a Subscription
A subscription associates a shopper with a plan. The subscription provides details about how and when the shopper will be billed.
- Click the Recurring menu item.
- Click the Subscriptions tab.
- Click the New Subscription button. The New Subscription form appears.
- Select the Subscription Plan from the dropdown list.
- In the Scheduling section, enter the date of the First Payment or click the calendar icon to select the date. Additional fields appear after making your selection and they vary depending on the selected subscription plan.
- If the selected subscription plan has a fixed number of bills, the other fields will be populated and you may proced to the next step. If the selected subscription plan has no fixed number of bills, toggle the Specify subscription end terms button to set an end date to the subscriptionand do one of the following:
- Select the Choose end date option then enter the End Date. You may also click the calendar icon to select the date.
- Select the Set number of payments option then enter the number of Total Payments.
Note that not if an end date is not set, the payment will recur indefinitely until it is manually cancelled.
- In the Customer section, search for the subscribing customer by doing one of the following:
- In the Search for a customer field, enter a part of the customer's name and select the customer from the results.
- Select the customer from the Search for a customer dropdown list.
- Select the card to be used from the Payment Method dropdown list.
- To email the receipt to the customer, select the Email Receipt checkbox. A separate receipt will be emailed for each transaction.
- Click the Create Subscription button to save the subscription.
API Integration
Converge API Resources: Plans, Subscriptions
Create Plan
- Send a Create Plan POST request to the /plans endpoint.
- In your request, set the following parameters:
- name - The name of the plan. This is required.
- billingInterval - The time period between bills. This is required. It contains the following fields:
- -timeUnit - The time unit used for the billing cycle. Valid values are the following: day, week, month, year.
- -count - The number of times the time unit will repeat until the next billing cycle.
- total - The total amount for each bill. This does not include introductory bills. This is required. It contains the following fields:
- -amount - The actual value of the bill.
- -currencyCode - The ISO 4217 three-letter currency code.
- billCount - The total number of billing cycles. This includes any introductory bills.
- initialTotal - The introductory bill. It contains the following fields:
- -amount - The actual value of the introductory bill.
- -currencyCode - The ISO 4217 three-letter currency code.
- initialTotalBillCount - The number of times the introductory bill will be applied. Note that this is not added to the total number of billing cycles as that already accounts for it. It should also have a lower value than than the total number of billing cycles.
- isSubscribable - If set to true (default), new subscriptions can be added to the plan. Cancelled subscriptions can also be reactivated. If set to false, new subscriptions cannot be added and cancelled subscriptions cannot be reactivated.
- Wait for the response from the /plans endpoint. In the response, take note of the following:
- id - The plan resource ID. This is used for retrieving and updating the plan.
- href - The plan resource URL. This is used for associating the plan with a subscription.
Create Subscription
- Send a Create Subscription POST request to the /subscriptions endpoint.
- In your request, set the following parameters:
- plan - The plan resource URL. This is obtained from a successful Create Plan response.This is required.
- doSendReceipt - If set to true, receipt for every transaction will be sent to the customer's email. If set to false, receipts will not be emailed.
- storedCard - The stored card resource URL. This must be associated with a shopper. This is required.
- billCount - The total number of bills. This can only be set if it is not yet defined in the plan associated with the subscription.
- timeZoneID - The IANA Timezone Database Name of the first billing date. It indicates exactly when to charge the card associated with the subscription. This is required.
- firstBillAt - The first billing date. This is required.
- Wait for the response from the /subscriptions endpoint. In the response, take note of the following:
- id - The subscription resource ID. This is used for retrieving and updating the subscription.
- href - The subscription resource URL.
Examples
The following is an example of a JSON request for creating a one-year plan that includes a one-month introductory rate.
POST "https://uat.api.converge.eu.elavonaws.com/plans"
{
"name": "Monthly Software License",
"billingInterval": {
"timeUnit": "month",
"count": 1
},
"total": {
"amount": "5.00",
"currencyCode": "EUR"
},
"billCount": 12,
"initialTotal": {
"amount": "2.50",
"currencyCode": "EUR"
},
"initialTotalBillCount": 1
}The following is an example of a successful JSON response to the request above.
{
"href": "https://uat.api.converge.eu.elavonaws.com/plans/ry2t4kh4gkrk3h7vq9wx36794gvp",
"id": "ry2t4kh4gkrk3h7vq9wx36794gvp",
"createdAt": "2022-04-04T19:52:00.274Z",
"modifiedAt": "2022-04-04T19:52:00.274Z",
"deletedAt": null,
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/XrDXRBh9YHxwqQTj2Cmq7j49",
"planList": "https://uat.api.converge.eu.elavonaws.com/plan-lists/XrDXRBh9YHxwqQTj2Cmq7j49",
"name": "Monthly Software License",
"description": null,
"billingInterval": {
"timeUnit": "month",
"count": 1
},
"total": {
"amount": "5.00",
"currencyCode": "EUR"
},
"billCount": 12,
"initialTotal": {
"amount": "2.50",
"currencyCode": "EUR"
},
"initialTotalBillCount": 1,
"shopperStatement": null,
"isSubscribable": true,
"customReference": null,
"customFields": null
}The following is an example of a JSON request for adding a subscription to a plan for 12 billing cycles. This assumes that a stored card is already created. For more information, see the Create Stored Card in the Pay with a Stored Card/Shopper page.
POST "https://uat.api.converge.eu.elavonaws.com/subscriptions"
{
"plan": "https://uat.api.converge.eu.elavonaws.com/plans/ry2t4kh4gkrk3h7vq9wx36794gvp",
"doSendReceipt": true,
"storedCard": "https://uat.api.converge.eu.elavonaws.com/stored-cards/g9fw9kg2fjfcdm62rb2f38cqmx9m",
"timeZoneId": "Europe/London",
"firstBillAt": "2022-04-22"
}The following is an example of a successful JSON response to the request above.
{
"href": "https://uat.api.converge.eu.elavonaws.com/subscriptions/dtdfj7bg8jbj86jcd63c66fm949p",
"id": "dtdfj7bg8jbj86jcd63c66fm949p",
"createdAt": "2022-04-04T20:02:17.178Z",
"modifiedAt": "2022-04-04T20:02:17.178Z",
"merchant": "https://uat.api.converge.eu.elavonaws.com/merchants/XrDXRBh9YHxwqQTj2Cmq7j49",
"plan": "https://uat.api.converge.eu.elavonaws.com/plans/ry2t4kh4gkrk3h7vq9wx36794gvp",
"shopper": "https://uat.api.converge.eu.elavonaws.com/shoppers/pbrcccxy9pgk4qfdcbhf88w97hxv",
"account": "https://uat.api.converge.eu.elavonaws.com/accounts/XrDXRBh9YHxwqQTj2Cmq7j49",
"debtorAccount": null,
"doSendReceipt": "true",
"storedCard": "https://uat.api.converge.eu.elavonaws.com/stored-cards/g9fw9kg2fjfcdm62rb2f38cqmx9m",
"billCount": 12,
"timeZoneId": "Europe/London",
"firstBillAt": "2022-04-22",
"nextBillAt": "2022-04-22",
"previousBillAt": null,
"finalBillAt": "2023-03-22",
"cancelRequestedAt": null,
"cancelAfterBillNumber": null,
"nextBillNumber": 1,
"subscriptionState": "active",
"failureCount": 0,
"customReference": null,
"customFields": null
}
For more request and response examples, and for the complete and detailed list of parameters, see the Plans Resource and the Subscriptions resource.