WePay Developer

Conditional payments

Before reading this tutorial...

You should be familiar with the following concepts:

Conditional payments allow you to get the customer’s authorization to charge them at some point in the future, without charging them up front. Crowdfunding platforms, for example, may only want to charge donors if the total amount pledged exceeds a "tipping point".

You can create a conditional payment in three steps:

  1. Create a pre-approval object to define the conditional payment (amount, expiration, etc.) using the /preapproval/create call
  2. Get the customer's payment information by sending them to the preapproval_uri returned by the /preapproval/create call.
  3. Charge the customer once the conditions are met

Conditional payments or delayed payouts?

With conditional payments, you don’t charge the customer up-front, you just get their permission to charge them in the future. If you want to charge the customer up-front, read the charge a customer tutorial. If you want to charge customers up-front and restrict access to the funds for a period of time, read the delayed payouts tutorial.

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 Set this parameter to "once" (without the quotes). For recurring payments, view our /preapproval/create API call specifications.
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 The uri the payer will be redirected to after approving the preapproval.
  • PHP
  • cURL
  • Ruby
  • Python
    // 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'            => 'once',
        'amount'            => '19.99',
        'mode'              => 'regular',
        'short_description' => 'A subscription to our magazine.',
        'redirect_uri'      => 'http://example.com/success/',
    // display the response
curl https://stage.wepayapi.com/v2/preapproval/capture \
	-H "Authorization: Bearer STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20" \
	-d "account_id=123456789" \
	-d "period=once" \
	-d "amount=19.99" \
	-d "mode=regular" \
	-d "short_description=A subscription to our magazine." \
	-d "redirect_uri=http://example.com/success/"
# WePay Ruby SDK - http://git.io/a_c2uQ
require 'WePay_API_v2_Ruby_SDK.rb'

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

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

# create the pre-approval
response = wepay.call('/preapproval/create', access_token, {
    :account_id         => account_id,
    :period             => 'once',
    :amount             => '19.99',
    :mode               => 'regular',
    :short_description  => 'A subscription to our magazine.',
    :redirect_uri       => 'http://example.com/success/',

# 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': 'once',
    'amount': '19.99',
    'mode': 'regular',
    'short_description': 'A subscription to our magazine.',
    'redirect_uri': 'http://example.com/success/'

# display the response
print response


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

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.

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 type="text/javascript">
    WePay.iframe_checkout("preapproval_div_id", "preapproval_uri");

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.

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

Charge the customer

Now that the customer has authorized you to charge them in the future, you can charge them at any time until the authorization expires.

To charge the customer, just make the /checkout/create call with the preapproval_id you received from the /preapproval/create call.

The customer will automatically be charged using the payment method they specified when they confirmed the original pre-approval.

Since the customer has already authorized this charge, they will be charged automatically, as soon as you initiate the /checkout/create call.