Build an eCommerce Platform with WePay

Overview

WePay makes it easy to integrate payments into an eCommerce platform. Integrate payments using one of the following approaches.

  • Embedded: Get a simple eCommerce platform integrated with a few calls using an embedded iframe.
  • Custom: Take more control of the user experience using custom integration.

Tip

To check out the various API calls used below, visit the API Reference.

Scenario

You have a platform that allows your users to create websites for their businesses, organizations, etc. You are also adding the ability for these users to list products for sale and easily sell these products. Thus, you want to provide these users with a built-in payment system. You’re also thinking about changing your platform’s business model from charging monthly fees to a percentage of your user’s sales.

At WePay, your users are the merchants, and the buyers of users’ products are the payers, and we’ll use those terms in this guide.

Embedded

Leverage the WePay user experience by using our embedded iframe as much as possible. This approach involves the following steps:

  1. Create accounts for your merchants
  2. Process payments
  3. Post-checkout processing

Create accounts for your merchants

Each of your merchants receives their own WePay payment account. This keeps all the money management with WePay. Your site will facilitate creating this account and will receive an access token that your site saves. This access token allows your site to handle checkout, get status, etc.

Set up a merchant using OAuth2

The easiest approach is to redirect to WePay’s OAuth2 authorization URI. Your merchant will see a popup where they can set up their login.

?client_id=[your client id]
&redirect_uri=[your redirect uri ex. 'http://example.com/wepay']
&scope=[the permissions you want ex. manage_accounts,collect_payments]

When merchants complete this, follow up with the /oauth2/token call to receive an access token for this merchant:

  • PHP
  • cURL
  • Ruby
  • Python

Create a payment account

Now that your platform has an access token, create a merchant account. Although there are many optional arguments, all you need to provide for US merchants are the name of the account and a description. The name is typically based on your platform’s name, e.g. “ABC eCom Service”. The description is variable and up to you.

  • PHP
  • cURL
  • Ruby
  • Python

Process payments

Let’s assume the following:

  • For the first version your platform just needs to handle simple checkout. A single call is all you need, and your platform will never touch sensitive payer information.
  • WePay will send emails to both your merchant and the customer. You can inject a message including embedded HTML. A good use for this is to summarize the purchase. Letting WePay send the email means you’ll only get an email if the payer (buyer) successfully checks out.
  • Your merchant has decided on a flat $1.00 shipping charge per order. Your platform will instruct WePay to ask for shipping info as part of the checkout process.
  • Your platform is charging your merchants 5% of the total amount, and your merchants will pay this as a fee (not the payer/buyer).
  • Finally, set the redirect URI to your platform’s “Congratulations” page. As a side effect, catching this URI will let your platform know that the checkout completed successfully.

Call /checkout/create with these arguments:

  • PHP
  • cURL
  • Ruby
  • Python

The /checkout/create call will return a checkout_id and a URI for the payment page.

Post-checkout processing

The easiest way to know when the merchant completes checkout is by waiting for the callback_uri. Before showing the congrats page, get the shipping address from the checkout object:

  • PHP
  • cURL
  • Ruby
  • Python

This will return a great deal of information, including the shipping_address structure.

That’s it - your platform is doing everything it needs to do for a simple store.

Defer capture until shipping

It’s a best practice to delay actually charging credit cards until a merchant is ready to ship. However, you and your merchants want to know at the time customers checkout that a payment method is valid and to reserve the funds. The way to do this in WePay is to get a preapproval at the time of checkout, and follow it with a checkout call when the merchant ships.

Preapprovals work just like checkout objects, except they don’t charge the card. They just validate that the card is good and hold the funds against the payer’s credit limit. A preapproval is good for up to 14 days. If your merchants will not ship products within 14 days, then your platform needs to tokenize cards and delay authorizing them until shipping. We’ll continue this example using preapprovals.

Change to checkout calls

To use preapprovals, simply change your /checkout/create calls to /preapproval/create. The user will see the same pop-up window to enter payment info, and your app will receive a preapproval_id that it must save.

New calls when your merchant ships

When your merchants indicate they have shipped a product, your platform calls /checkout/create, but this time, they pass in the preapproval_id obtained at checkout.

Just supply the preapproval_id.

Partial shipments

When payers buy multiple items in one checkout, sometimes merchants want to ship items at different times. Your platform can use a /checkout/create call multiple times against a single preapproval_id.

Custom

A Note on Security

WePay minimizes the scope of security requirements for your platform. Using the approach in this section raises your platform’s responsibility compared with the approach in the previous section. Please read our security page for more information.com/general/api-call).

Instead of using WePay’s embedded iframe or pop-up window, as we did in the above example, your platform can completely own the checkout experience with the following steps:

  1. Securely obtain credit card info
  2. Complete checkout using a token
  3. Send your own emails to merchants and payers

Securely obtain credit card info

You can design your credit card acceptance form any way you wish, but you need to use WePay’s JavaScript library to securely send the credit card info directly to WePay’s servers. Do not accept credit card information onto your own server and then call WePay’s APIs.

WePay’s JavaScript library uses the /credit_card/create API call to store the payer’s credit card info securely on WePay’s servers, and returns your platform a token. This token can then be used in a /checkout/create call to complete a transaction without any further user interaction.

A minimal credit card form looks like this:

Name:
Email:
Credit Card Number:
Expiration Month:
Expiration Year:
CVV:
Zipcode:

And the HTML source is here:

  • HTML

The function chargeCard() is invoked when the user submits the checkout form. chargeCard extracts the credit card fields and maps them to WePay’s JavaScript call WePay.credit_card_create. In this way, the sensitive information is passed directly to WePay’s servers, and your platform receives a token for later use.

Your chargeCard function can take the data response and call your own server’s APIs to store the token.

Complete checkout using a token

When it’s time to charge the credit card, follow the /checkout/create example shown before, but this time add the payment_method_id and payment_method_type parameters:

  • PHP
  • cURL
  • Ruby
  • Python

Because your platform already has the card info, this usage of /checkout/create will immediately charge the card with no user interaction.

Send your own emails to merchants and payers

Another way your platform can take more control of the user experience is to generate your own emails to merchants and payers during checkout. Your WePay account manager can assist you in turning off specific emails.