Embedded Checkout Using Iframe

What is Embedded Checkout?

The Embedded Checkout payment flow uses a co-branded iframe and is a simple, embeddable way to collect payment information and charge payers. You can embed the iframe on your site and then let the payer enter their payment information and complete the payment.

In other words, the iframe payment flow takes care of both collecting the payer's payment information and charging their payment method. Using an iframe, you can minimize your PCI compliance responsibilities.


A marketplace site wants to let users find freelancers and pay them on their site. They don't want users to have to redirect away from their site during the payment process. They can embed the iframe in their payment flow to take care of collecting the payment information (credit card or bank account details) and charge the user.

At WePay, the freelancers are merchants and the users are payers and we'll use those terms below.

Live Example

How does it work?

There are 3 steps to using the iframe:

  1. Make the /checkout/create call to get a checkout_id and checkout_uri
  2. Embed the checkout_uri in an iframe on your site
  3. Handle the confirmation page the payer ends up on after paying

Step 1:

To get started, you will create a checkout with the /checkout/create call. The checkout object represents a single payment. You'll pass in the account_id and access_token you got when you created the merchant's payment account. The redirect_uri that you set is where the payer will end up after they finish the payment flow (typically a confirmation page on your site).

  • PHP
  • cURL
  • Ruby
  • Python
    // WePay PHP SDK - http://git.io/mY7iQQ
    require 'wepay.php';

    // application settings
    $account_id = 123456789; // your app's account_id
    $client_id = 123456789;
    $client_secret = "1a3b5c7d9";
    $access_token = "STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20"; // your app's access_token

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

    $wepay = new WePay($access_token);

    // create the checkout
    $response = $wepay->request('checkout/create', array(
        'account_id'        => $account_id,
        'amount'            => '24.95',
        'short_description' => 'Services rendered by freelancer',
        'type'              => 'service',
        'currency'          => 'USD'

    // display the response
$ curl https://stage.wepayapi.com/v2/checkout/create \
    -H "Authorization: Bearer STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20" \
    -d "account_id=12345" \
    -d "amount=24.95" \
    -d "short_description=Services rendered by freelancer" \
    -d "type=service" \
    -d "currency=USD"
# WePay Ruby SDK - http://git.io/a_c2uQ
require 'wepay'

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

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

# create the checkout
response = wepay.call('/checkout/create', access_token, {
    :account_id         => account_id,
    :amount             => '24.95',
    :short_description  => 'Services rendered by freelancer',
    :type               => 'service'
    :currency           => 'USD'

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

# application settings
account_id = 123456789 # your app's account_id
access_token = 'STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20' # your app's access_token
production = False

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

# create the checkout
response = wepay.call('/checkout/create', {
    'account_id': account_id,
    'amount': '24.95',
    'short_description': 'Services rendered by freelancer',
    'type': 'service',
    'currency': 'USD'

# display the response
print response

In response you will get a checkout_id and checkout_uri which you will use in step 2.

Step 2:

Now that you have a checkout_uri, you should embed it in an iframe on your site. Here is some sample code that will let you do that:

<div id="wepay_checkout"></div>
<script type="text/javascript" src="https://stage.wepay.com/min/js/iframe.wepay.js">

<script type="text/javascript">
    WePay.iframe_checkout("wepay_checkout", "https://stage.wepay.com/api/checkout/12345");

The payer will see the payment flow inside the iframe and will be able to enter their payment info and confirm the payment.

Step 3:

Once the payer has confirmed their payment, their payment method will be charged and they will be sent to whatever redirect_uri you specified in step 1. The checkout_id will be appended as a GET parameter so you can look up the payment details.

Note that if you don't specify a redirect_uri, the payer will not be redirected and will instead see a confirmation page inside the iframe.

Next Steps

Now that you've successfully charged a payer, your merchant will have money in their WePay payment account. The next step is to let the merchant verify their identity and link their bank account.