Iframe Tokenization


Before reading this tutorial, you should be familiar with charge a customer and conditional payments.

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.

Limited PCI Responsibiltiy

When you use iframe tokenization, WePay takes on most of the PCI compliance responsibility. You are still responsible for adhering to certain basic PCI compliance rules.

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: 1) regular - customer is redirected to WePay to complete the pre-approval, and 2) 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


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


  • JSON

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.

  1. Set the mode parameter in /preapproval/create to iframe.
  2. Load WePay’s Javascript library to create the iframe.
  3. Paste the following HTML wherever you want the payment form to appear on your page:
  • HTML
  • 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 or 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.