WePay

Iframe Tokenization

Before reading this tutorial...

You should be familiar with the following concepts:

Iframe Tokenization allow API applications to experience all the benefits of conditional payments but in a more efficient manner. Iframe Tokenization allows applications to receive authorization to send money to any account that they (the applications) have set up for the users. We can accomplish this by using app-level preapprovals instead of account-level preapprovals.

No PCI Responsibility

When you use iframe tokenization, you do not have to worry about PCI compliance since WePay takes on the PCI compliance responsibility.

You can create an app-level preapproval in three steps:

  1. Create a pre-approval object to define the conditional payment (amount, expiration, etc.) using the /preapproval/create call while specifically using client_id and client_secret rather than account_id and access_token.
  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.

Create a pre-approval object

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

Use client_secret instead of the access_token

For app-level iframe tokenization, use the client_secret of your application rather than the user's access_token.

API Call:

Parameter Description
client_id Your app's unique identifier. Found on your dashboard
client_secret Your app's unique password. Found on your dashboard
period For iframe tokenization, set period to "once"
amount The amount you'll charge the customer
short_description What the payment is for
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 customers will be sent after entering their credit card information
  • 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(
        'client_id'         => $client_id,
        'client_id'         => $client_secret,
        'period'            => 'once',
        'amount'            => '19.99',
        'mode'              => 'iframe',
        'short_description' => 'A brand new soccer ball.',
        'redirect_uri'      => 'http://example.com/success/'
    ));

    // display the response
    print_r($response);
?>
curl https://stage.wepayapi.com/v2/preapproval/capture \
	-H "Authorization: Bearer STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20" \
	-d "client_id=123456789" \
    -d "client_secret=1a3b5c7d9" \
	-d "period=once" \
	-d "amount=19.99" \
	-d "mode=iframe" \
	-d "short_description=A brand new soccer ball." \
	-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, {
    :client_id          => client_id,
    :client_secret      => client_secret,
    :period             => 'once',
    :amount             => '19.99',
    :mode               => 'iframe',
    :short_description  => 'A brand new soccer ball.',
    :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', {
    'client_id': client_id,
    'client_secret': client_secret,
    'period': 'once',
    'amount': '19.99',
    'mode': 'iframe',
    'short_description': 'A brand new soccer ball.',
    'redirect_uri': 'http://example.com/success/'
})

# 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.

Keep your customer on your site

You can have customers enter their payments information 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.

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.

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.