When it comes to processing payments using Embedded checkouts, you have two options:

  1. Embedded Checkout
  2. Credit Card iFrame

The first option, Embedded Checkout, uses a co-branded iFrame and is a simple, embeddable way to collect payment information and charge payers. WePay collects all information. All information collected will not touch your servers. 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.

The second option, Credit Card iFrame, is simply a pared down version of the Embedded Checkout, only giving you a pre-built user interface for a payer’s credit card information. WePay will only collect credit-card information, and it won’t touch your servers. You’ll have to do more up-front work, but you’ll receive the same benefit of reduced PCI burden. In addition, you’ll gain more flexibility when designing your payments flow, as you can decide where to collect a user’s name, email, postal code, etc.

Example (Embedded Checkout)

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.

Embedded Checkout

Standard Horizontal

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


  • Implement hosted_checkout.fallback_uri in order to successfully present the iframe in browsers which do not accept third-party cookies. Read more about fallback URI.
  • Use unique_id to protect against duplicate transactions. Read more in the Best Pratcies article and /checkout/create API reference.
  • Provide a callbacki_uri to receive updates about the checkout. Read more in the IPN article.
  • Include the relevant rBits to help WePay process the transaction and to protect your users. Read more in the Risk Certification.
  • To limit the available payment methods in an iframe, use the hosted_checkout.funding_sources parameter on the /checkout/create call. Funding sources can be limited to either credit_card or payment_bank.

  • PHP
  • cURL
  • Ruby
  • Python

In the 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:

  • HTML

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.

Credit Card iFrame


The above experience allowed for the whole checkout experience to be completed by the iFrame. If you want to keep the benefits of a reduced PCI scope, but have a little more control over the user experience, you can implement the Credit Card iFrame, which only brings in an iFrame for a subset of the whole checkout experience.

In order to use the CC iFrame, first start by making sure you’ve implemented the WePay Tokenization Javascript library.

From here, at a high level, there are 3 steps:

  • Append credit card iFrame on an HTML element which has an id of “iframe-element”. You’ll run the code in the JS library like so: WePay.createCreditCardIframe('iframe-element', options);, with options being a Javascript variable defining the look and feel of the iFrame.
  • Present iFrame to payer, and collect client_id, user_name, email, address, and postal_code. Collect these fields through your own User Interface and experience. Do not collect credit card information, as the iFrame will collect this.
  • Call tokenize, which combines information from previous step, plus credit card information, and receive Credit Card Token, which can then be used to execute a payment.

You can modify the CSS of the iFrame, by passing an object as the second argument in the createCreditCardIframe call. The structure is presented below:

var options = {
	'custom_style' : {
		'styles': {
			'base': {
				'border-color': '#ccc',
				'transition': ' border-color 0.6s linear, border-width 0.6s linear',
				'border-radius': '5px',
				':hover': {
					'border-color': 'black'
					':focus': {
						'border-color': '#969696'
					'::placeholder': {
						'color': '#ccc'
						'color': 'red'
			'valid': {
				'border-color': '#5ca96d',
			'invalid': {
				'border-color': '#d26172',

Per the example above, you can modify the following three class names:

  • base
  • valid
  • invalid

These represent the default viewing behavior, valid credit card information, and invalid credit card information user experiences.

These are the modifiable CSS properties & pseudo-classes:

  • border-radius,
  • border,
  • font-size,
  • font-weight,
  • font-family,
  • font-smooth,
  • font-style,
  • font-variant,
  • letter-spacing,
  • padding,
  • text-decoration,
  • text-shadow,
  • text-transform,
  • border-color,
  • transition,
  • color,
  • appearance,
  • :hover,
  • :focus,
  • ::placeholder,
  • ::selection

Example (Credit Card iFrame)


  • HTML

Sample credit card iFrame UIs:


Credit Card iFrame Example 1

Credit Card iFrame Example 2

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.