Subscriptions

Before reading this tutorial...

You should be familiar with the following concepts:

Use new Subscriptions API instead

Recurring pre-approvals are an old style of implementing subscriptions with WePay. If you are currently implementing subscriptions, we recommend using the new Subscriptions API.

Subscriptions are a type of pre-approval. You can do a lot of creative things with pre-approvals, but for now we'll just focus on subscriptions. They allow you to charge a customer automatically on a recurring basis.

You can create a subscription in three steps:

Create a pre-approval object to define the subscription (amount, period, etc.) using the /preapproval/create call.
Get the customer’s payment information by sending them to the preapproval_uri returned by the /preapproval/create call.
Send the customer to a confirmation page.

You can do a lot of creative things once a customer has completed a pre-approval, but for now we’ll just focus on subscription billing.

Create a pre-approval object

To create a pre-approval object, make the /preapproval/create call with the appropriate access_token.

API Call:

Parameter	Description
account_id	Identifies the WePay account receiving the payment. For merchants, simply use your account_id For platforms, use the appropriate user's account_id
period	How often you'd like to charge the customer (daily, weekly, monthly, yearly, etc.)
amount	The amount you'll charge the customer every billing cycle
short_description	What the payment is for (e.g. "Premium Plan")
mode	There are two modes: regular - customer is redirected to WePay to complete the pre-approval iframe - customer completes the pre-approval in an iframe window on your site
redirect_uri	Where the customer will be sent after signing up for subscription billing
start_time	When the subscription begins
end_time	When the subscription ends
auto_recur	Set this to true to bill the customer automatically (subscriptions)

PHP
cURL
Ruby
Python

<?php
    // WePay PHP SDK - http://git.io/mY7iQQ
    require 'wepay.php';

    // application settings
    $account_id = 123456789;
    $client_id = 123456789;
    $client_secret = "1a3b5c7d9";
    $access_token = "1a3b5c7d9";

    // change to useProduction for live environments
    Wepay::useStaging($client_id, $client_secret);

    $wepay = new WePay($access_token);

    // create the pre-approval
    $response = $wepay->request('preapproval/create', array(
        'account_id'        => $account_id,
        'period'            => 'monthly',
        'end_time'          => '2013-12-25',
        'amount'            => '19.99',
        'mode'              => 'regular',
        'short_description' => 'A subscription to our magazine.',
        'redirect_uri'      => 'http://example.com/success/',
        'auto_recur'        => 'true'
    ));
    
    // display the response
    print_r($response);
?>

curl https://stage.wepayapi.com/v2/preapproval/create \
	-H "Authorization: Bearer STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20" \
	-d "account_id=123456789" \
	-d "period=monthly" \
	-d "end_time=2013-12-25" \
	-d "amount=19.99" \
	-d "mode=regular" \
	-d "short_description=A subscription to our magazine." \
	-d "redirect_uri=http://example.com/success/" \
	-d "auto_recur=true"

# WePay Ruby SDK - http://git.io/a_c2uQ
require 'wepay'

# application settings
account_id = 123456789
client_id = 123456789
client_secret = '1a3b5c7d9'
access_token = '1a3b5c7d9'

# set _use_stage to false for live environments
wepay = WePay::Client.new(client_id, client_secret, _use_stage = true)

# create the pre-approval
response = wepay.call('/preapproval/create', access_token, {
    :account_id         => account_id,
    :period             => 'monthly',
    :end_time           => '2013-12-25',
    :amount             => '19.99',
    :mode               => 'regular',
    :short_description  => 'A subscription to our magazine.',
    :redirect_uri       => 'http://example.com/success/',
    :auto_recur         => 'true'
})

# display the response
p response

# WePay Python SDK - http://git.io/v7Y1jA
from wepay import WePay

# application settings
account_id = 123456789
access_token = '1a3b5c7d9'
production = False

# set production to True for live environments
wepay = WePay(production, access_token)
        
# create the pre-approval
response = wepay.call('/preapproval/create', {
    'account_id': account_id,
    'period': 'monthly',
    'end_time': '2013-12-25',
    'amount': '19.99',
    'mode': 'regular',
    'short_description': 'A subscription to our magazine.',
    'redirect_uri': 'http://example.com/success/',
    'auto_recur': 'true'
})

# display the response
print response

Response:

Parameter	Description
preapproval_id	The unique ID of the subscription approval
preapproval_uri	The uri for the customer to finish approving the subscription

{
  "preapproval_id":12345,
  "preapproval_uri":"https://stage.wepay.com/api/preapproval/12345/4560de9a"
}

Complete the Pre-Approval

Now that you have the preapproval_id and the preapproval_uri, you should have the customer enter their payment information on the preapproval_uri. You can either redirect them to WePay or keep them on your site.

Redirect to WePay

The easiest way to complete a pre-approval is to redirect the customer to www.wepay.com.

Set the mode parameter in /preapproval/create to regular.
Send the user to the preapproval_uri that you received from the previous step.

The user will see a page like this:

Want to customize this page?

Create a theme and upload a logo to ensure the best user-experience possible.

Learn more about customization

Keep your customer on your site

You can also have customers complete their payments in a secure iframe on your site.

Set the mode parameter in /preapproval/create to iframe
Load WePay’s Javascript library to create the iframe

Paste the following HTML wherever you want the payment form to appear on your page:

<script type="text/javascript" src="https://www.wepay.com/js/iframe.wepay.js">
</script>

<script type="text/javascript">
    WePay.iframe_checkout("preapproval_div_id", "preapproval_uri");
</script>

preapproval_div_id is the ID of the element in which you want to put the iframe.

preapproval_uri is the preapproval_uri that you received in the previous step as a response to the /preapproval/create call.

The iframe looks like this:

Want to customize this iframe?

Change the look and layout of your iframe to increase conversion rates.

Learn more about customization

Learn more about iframe layouts

Confirmation page

Once the customer completes their pre-approval, they’ll be redirected to the redirect_uri that you specified and charged automatically according to the schedule that you defined when you initiated the subscription using the /preapproval/create call.

The preapproval_id will be appended as a url-encoded parameter to the redirect_uri, which will allow you to use the /preapproval call to get payment details to show on your payment confirmation pages.

If you want to receive a notification each time the subscription changes state, you can set up IPNs.

What's
Next?

Looking for something else? See the full list of tutorials