Documentation

Recurring Billing Flow

What is recurring billing?

Paymentwall supports recurring billing that allows merchants to bill their users based on a specific schedule automatically.

Let’s say a user paid for a 1 month premium subscription using a payment method that supports recurring billing (e.g using a credit card). Paymentwall can then automatically charge the user’s card every month until the subscription expires or until the user cancels the subscription. For alternative payments that don't support recurring billing Paymentwall can send email reminders to users to extend their membership.

Recurring billing is supported by Credit Cards and certain eWallets globally as well as mobile payments in certain European countries. 

How to set up recurring billing?

Step 1. Create a project

Under your Project Tab, choose the “Add Project” button. Enter your project URL and then choose Digital Goods / Subscriptions / One-Time Payments monetization scheme.

If you already added the project to your merchant account, simply go to "Projects" tab, click Project Settings and enter the information mentioned above.

Step 2. Manage recurring payments

• If you’re using Paymentwall for managing product inventory via Products section (Default Widget Call)

        Create a new product:

        Under project tab, go to “Product” section” Choose “Add New Product”. Please note that the “Type” section should be set to Time Based and the “Recurring billing” checkbox needs to be checked.

• If you’re managing product inventory on your end (Flexible Widget Call)

        You need to pass the following parameter to your widget call.
        ag_recurring = 1
        ag_type = subscription
        ag_period_type= This should be product period (year,month,week, day)
        ag_period_length= Value should be the length of the product period (numeric)

How does recurring billing work?

Once a user makes his first payment via a method that supports recurring billing (e.g. credit cards), we sign him up for recurring billing.

Recurring schedule

We will automatically charge the user based on the recurring billing schedule. E.g. if you specify the product length as 1 month, we will charge the user every month. Next payment will happen the same day of the next month. If a payment happens on 30th of January, the next payment will be made in first days of March.

Pingback format

Every time a user is billed, we will send a new pingback. Let’s say for monthly billing, Paymentwall will send a new pingback for every next scheduled payment using the same parameters except for the reference ID. 

Additionally we can add the following custom pingback parameters for your project (for this contact devsupport@paymentwall.com):

• recurring_billing_active -if recurring billing is active for this payment, possible values: 1, 0 
• initial_ref - Reference ID of initial payment
• recurring_payment- if this payment is an automatic recurring payment, possible values: 1, 0

Payment Failures

If a user has insufficient funds or a payment fails for any other reason - Paymentwall will make 2 reattempts (3 attempts in total) to charge the user. Payment Status API  will report that subscription is active and date_next will contain the date of the next attempt.

If all of the attempts fail, Paymentwall will stop the recurring billing.  (Please note that once the recurring stopped, it will no longer process an attempt to charge the user for the next scheduled payment)
For this event Paymentwall will send a pingback with type=14 - (subscription payment failed).

Expiration

By default, users will be charged during at most 1 year. This can be extended by request. Once the last charge happens Paymentwall will send a pingback with pingback type=13 - (subscription expired)

Cancellation

From the moment that the recurring was cancelled either by the merchant or the user, Paymentwall will send a pingback type - 12 (subscription cancellation)

There are a few ways to cancel an existing recurring billing. 

For merchants:

• Cancellation API
• Research & Refund Tool inside of merchant account

For end-users:

• Customer Care - by contacting Paymentwall customer care
• Help Section / End-User area - Users can visit the help section of the payment widget (if it’s accessible by paid users of your website) and cancel it from there. You can place deep links inside of your website to our Help section. Contact devsupport@paymentwall.com for more details

Paymentwall will send a pingback type = 12 ( subscription cancellation) once the user or the merchant cancelled the subscription.

How to provide a direct link for cancelation recurring billing?

In order to directly redirect users to the page where they can cancel recurring billing, merchants use the link below

Request URL:

https://api.paymentwall.com/api/account/recurring-payments/?key=[PROJECT_KEY]&uid=[USER_ID]&widget=c1&sign=[SIGNATURE]&sign_version=[SIGNATURE_VERSION]

Upgrades / Downgrades

If a user wants to upgrade his existing subscription plan to a plan with different duration or different payment amount - merchants can do this via API on behalf of users. This API is supposrted for Credit Cards.
http://www.paymentwall.com/en/documentation/Subscription-Changes---Upgrade-API/1529

What happens if a subscribed user comes to the widget again?

If a user with an existing plan comes to the widget, by default Paymentwall redirects him to his account section where he can see the list of currently active recurring plans and where he can cancel those plans. This logic can be adjusted and instead the payment page can be displayed by default. If an entirely new payment is made by the user and this payment supports recurring billing, the old recurring plan will not be affected in any way. So the user may end up with a few active recurring plans. We don't block such behavior by default, as users may be subscribed for different features.