Custom Checkout Using Tokenization

What is credit card tokenization?

WePay offers a Custom Checkout process whereby you tokenize the payer's credit cards so that you can deliver your own completely branded, custom checkout experience. This takes WePay's brand completely out of the picture. Credit card tokenization enables this because it is a way for you to securely send credit card information to WePay, so that you can charge the card.


A marketplace that rents vacation homes wants to let renters pay for rentals on their site. The marketplace wants 100% control and branding over the payment flow and are willing to do more work during the integration. They collect the credit card info in the browser and then send it to WePay which gives them a credit_card_id they can use to charge the renter's card.

At WePay, the vacation home owner is the merchant and the renter is the payer and we'll use those terms below.

Live Example

Credit Card Number: (Example Card Numbers)
Expiration Month:
Expiration Year:
Postal Code:

How does it work?

There are 3 steps to using credit card tokenization:

  1. Get approval for your app to use credit card tokenization.
  2. Collect the payer's credit card information and make the /credit_card/create call from the client
  3. Send the credit_card_id to your server and make the /checkout/create call to charge the card

Step 1:

The first step is to request approval for your app to use credit card tokenization. Because tokenization requires you to securely handle payer credit card information when transmitting it to WePay, it means you must adhere to certain regulations of PCI compliance. You'll need to request approval and confirm that you have taken appropriate steps to comply with the PCI-DSS standard and secure payer information. You can apply for tokenization from the "API Keys" tab of your app dashboard.

Step 2:

To tokenize the credit card, you will have a form on your site where the user can enter their credit card information. When the user submits their data you will NOT send it to your server, but will instead make the /credit_card/create call from the browser using our special javascript library. We will respond with a credit_card_id that you can send to your server and use to charge the card.

Here is an example of how to collect credit card information, get back a credit_card_id securely, and then submit the credit_card_id to your server.

        <td>Name: </td>
        <td><input id="name" type="text"></td>
        <td>Email: </td>
        <td><input id="email" type="text"></td>
        <td>Credit Card Number: </td>
        <td><input id="cc-number" type="text"></td>
        <td>Expiration Month: </td>
        <td><input id="cc-month" type="text"></td>
        <td>Expiration Year: </td>
        <td><input id="cc-year" type="text"></td>
        <td>CVV: </td>
        <td><input id="cc-cvv" type="text"></td>
        <td>Postal Code: </td>
        <td><input id="postal_code" type="text"></td>
        <td><input type="submit" name="Submit" value="Submit" id="cc-submit"></td>

<script type="text/javascript" src="https://static.wepay.com/min/js/tokenization.3.latest.js"></script>
<script type="text/javascript">
(function() {
    WePay.set_endpoint("stage"); // change to "production" when live

    // Shortcuts
    var d = document;
        d.id = d.getElementById,
        valueById = function(id) {
            return d.id(id).value;

    // For those not using DOM libraries
    var addEvent = function(e,v,f) {
        if (!!window.attachEvent) { e.attachEvent('on' + v, f); }
        else { e.addEventListener(v, f, false); }

    // Attach the event to the DOM
    addEvent(d.id('cc-submit'), 'click', function() {
        var userName = [valueById('name')].join(' ');
            response = WePay.credit_card.create({
            "client_id":        118711,
            "user_name":        valueById('name'),
            "email":            valueById('email'),
            "cc_number":        valueById('cc-number'),
            "cvv":              valueById('cc-cvv'),
            "expiration_month": valueById('cc-month'),
            "expiration_year":  valueById('cc-year'),
            "address": {
                "postal_code": valueById('postal_code')
        }, function(data) {
            if (data.error) {
                // handle error response
            } else {
                // call your own app's API to save the token inside the data;
                // show a success page


Step 3:

Now that you have the credit_card_id, you can use it to charge the card. To do so, make the /checkout/create call with the credit_card_id from step 1, and the merchant's access_token and account_id.

  • 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  = "STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20";

// credit card id to charge
$credit_card_id = 123456789;

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

$wepay = new WePay($access_token);

// charge the credit card
$response = $wepay->request('checkout/create', array(
    'account_id'          => $account_id,
    'amount'              => '25.50',
    'currency'            => 'USD',
    'short_description'   => 'A vacation home rental',
    'type'                => 'goods',
    'payment_method'      => array(
        'type'            => 'credit_card',
        'credit_card'     => array(
            'id'          => $credit_card_id

// display the response
$ curl https://stage.wepayapi.com/v2/checkout/create \
    -H "Authorization: Bearer STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20" \
    -d "account_id=123456789" \
    -d "amount=25.50" \
    -d "currency=USD" \
    -d "short_description=A vacation home rental" \
    -d "type=goods" \
    -d "payment_method[type]=credit_card" \
    -d "payment_method[credit_card][id]=1234"
# WePay Ruby SDK - http://git.io/a_c2uQ
require 'wepay'

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

# credit card to charge
credit_card_id = 123456789

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

# charge the credit card
response = wepay.call('/checkout/create', access_token, {
    :account_id             => account_id,
    :amount                 => '25.50',
    :currency               => 'USD',
    :short_description      => 'A vacation home rental',
    :type                   => 'goods',
    :payment_method         => {
            :type           => 'credit_card',
            :credit_card    =>  {
                :id         =>  credit_card_id

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

# application settings
account_id = 123456789
access_token = 'STAGE_8a19aff55b85a436dad5cd1386db1999437facb5914b494f4da5f206a56a5d20'
production = False

# credit card id to charge
credit_card_id = 123456789

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

# charge the credit card
response = wepay.call('/checkout/create', {
    'account_id': account_id,
    'amount': '25.50',
    'currency': 'USD',
    'short_description': 'A vacation home rental',
    'type': 'goods',
    'payment_method': {
            'type': 'credit_card',
            'credit_card': {
                'id': credit_card_id

# display the response
print response

Bank Account Tokenization

WePay also offers a Custom Checkout process, whereby you tokenize the payer's bank account so that you can offer ACH as a payment method. You can find the complete guide on Bank Account Tokenization here.

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.