Discontinued

Subscription payments are available to current subscription API users only.

Subscription Payments

Scenario

Subscription payments - where a payment is charged to a payer on a regular schedule (weekly, monthly, yearly, etc).

Example

You are a SaaS (software as a service) platform that wants to charge your customers a recurring monthly fee for the use of your software or service.

Key Concepts

WePay provides the following objects as part of it's subscription feature:

  • Subscription Plan: This object represents the template for individual subscriptions. An example would be "Gold Plan: $40.00/month". Anyone signing up for the "Gold" Subscription plan would be charged $40 per month and their subscription would be linked to this plan.
  • Subscription: This object represents the individual subscription that a payer would subscribe to. The subscription object tracks what payer is subscribed, their payment details, what subscription plan they are using.
  • Subscription Charge: This object represents an individual payment as part of a subscription. If someone signed up for the "Gold Plan: $40/month", then a subscription payment object would be created each month that represented the $40 charge to that payer.

There are two options for signing up payers for subscriptions:

  • Iframe - Iframe uses the /subscription/create API call to obtain a subscription_uri which can be used to sign up the payer for a subscription. This method lets you use WePay's pre-built and optimized form to collect credit card information. This method minimizes necessary PCI compliance, because information is shared securely between the browser and WePay.
  • Tokenization - Tokenization uses WePay's tokenization.js to obtain a credit card token which can submitted to the /subscription/create call. This method lets you use your own form to collect credit card information. As there is exposure to developer error or fraud, there is more PCI compliance required than there is with iframe.

Solutions

Summary

  1. Create a Subscription Plan.
  2. Make the /subscription/create call.
  3. Embed the resulting subscription_uri in an iframe so the payer can enter their payment details.
  4. Track the subscription payments.

Detailed Example

Step 1:

To create a subscription plan for one of your merchants, you can make the /subscription_plan/create call.

You generally only need to do this once. Multiple subscribers can all be using the same plan. So if you have "Gold" and "Silver" plans, you can have multiple subscribers who are subscribed to each plan. The amount each subscriber is charged is determined by the plan.

  • 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 = "STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20";

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

    $wepay = new WePay($access_token);

    // create the subscription plan
    $response = $wepay->request('subscription_plan/create', array(
        'account_id'        => $account_id,
        'name'              => 'gold',
        'short_description' => 'The best plan with great perks',
        'period'            => 'monthly',
        'amount'            => 19.99
    ));

    // display the response
    print_r($response);
?>
curl https://stage.wepayapi.com/v2/subscription_plan/create \
	-H "Authorization: Bearer STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20" \
	-d "account_id=123456789" \
	-d "name=gold" \	
	-d "short_description=The best plan with great perks" \	
	-d "period=monthly" \
	-d "amount=19.99"
				
# WePay Ruby SDK - http://git.io/a_c2uQ
require 'wepay'

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

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

# create the subscription plan
response = wepay.call('/subscription_plan/create', access_token, {
    :account_id         => account_id,
    :name               => 'gold',
    :short_description  => 'The best plan with great perks',
    :period             => 'monthly',
    :amount             => 19.99
})

# display the response
p response
# WePay Python SDK - http://git.io/v7Y1jA
from wepay import WePay

# application settings
account_id = 123456789
access_token = 'STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20'
production = False

# set production to True for live environments
wepay = WePay(production, access_token)

# create the subscription plan
response = wepay.call('/subscription_plan/create', {
    'account_id': account_id,
    'name': 'gold',
    'short_description': 'The best plan with great perks',
    'period': 'monthly',
    'amount': 19.99
})

# display the response
print response

Step 2:

When someone wants to subscribe to one of your plans, make the /subscription/create call to get a subscription_id and subscription_uri.

  • PHP
  • cURL
  • Ruby
  • Python
<?php
    // create the subscription
    $response = $wepay->request('subscription/create', array(
        'subscription_plan_id'  => 12345,
        'redirect_uri'          => 'http://example.com/success/',
        'mode'                  => 'iframe'
    ));

    // display the response
    print_r($response);
?>
curl https://stage.wepayapi.com/v2/subscription/create \
	-H "Authorization: Bearer STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20" \
	-d "subscription_plan_id=12345" \
	-d "name=http://example.com/success/" \	
	-d "mode=iframe"
				
# create the subscription
response = wepay.call('/subscription/create', access_token, {
    :subscription_plan_id  => 12345,
    :redirect_uri          => 'http://example.com/success/',
    :mode                  => 'iframe'
})

# display the response
p response
# create the subscription
response = wepay.call('/subscription/create', {
    'subscription_plan_id': 12345,
    'name': 'http://example.com/success/',
    'mode': 'iframe'
})

# display the response
print response

Step 3:

Embed the subscription_uri from step 3 into an iframe on your site so the payer can enter their payment details and confirm the subscription.

<div id="wepay_subscription_container"></div>
<script type="text/javascript" src="https://www.wepay.com/min/js/iframe.wepay.js"></script>
<script type="text/javascript">
    WePay.iframe_checkout("wepay_subscription_container", "https://stage.wepay.com/api/subscription/12345");
</script>

Step 4:

Once the payer has completed the subscription flow, they will be automatically charged every period (monthly, yearly, etc - whatever you set in the subscription plan). You can view the status of the subscription in the app dashboard, or with the /subscription call. You can also sign up for IPNs for the subscription.