WePay

Working with Canadian Merchants

Before reading this section...

You should be familiar with how WePay works for US users. Then read this section to understand the additional steps used for Canadian users. In particular, you should be familiar with the following concepts:

WePay supports your Canadian users that:

  • Have a Canadian tax ID
  • Have a Canadian bank account
  • Want to accept payments in Canadian dollars, and
  • Want to have funds settled to them in Canadian dollars

In addition, you as the platform owner can receive any app fees from Canadian merchants in Canadian dollars into a Canadian bank account.

Do you have users in both the US and Canada?

If your platform supports merchants in both countries, then app fees from transactions that are not in the same currency as your platform's account will require special handling and will be paid out monthly.

Summary of changes for Canadian users

  1. Your application must be specially enabled for Canadian users.
  2. Indicate a user is Canadian by appropriate parameters in /user/register, /OAuth2, and /account/create.
  3. If using /user/register, incorporate Canadian debit card opt-in into your UI.
  4. On checkout, specify CAD for currency.
  5. When setting up their payment account, users will see Canadian versions of the setup screens.
  6. At this time, application fees collected for CAD transactions are settled out monthly to your app account with a minimum settlement amount of $1000.00 USD.

Limitations

  • The "pay with bank" option is not available - payers can pay with credit or debit cards (debit cards require opt-in).
  • An account setup for Canadian dollars can only accept payments in Canadian dollars, and an account setup in US dollars can only accept payments in US dollars.

Example Code for CA Users

Just want to see the new code? Here's what you need to do:

Create users and accounts

If your platform uses /oauth2/authorize, include the parameter:

"user_country": "CA"

If your platform uses /user/register, include the parameter with an appropriate timestamp:

"tos_acceptance_time": 1209600

In either case, create a Canadian merchant account with /account/create, include the parameters:

"country": "CA",
"currencies": ["CAD"],
"country_options": {
    "debit_opt_in": true
}

Checkout

In all calls where currency is an optional argument, include currency = CAD. This must be done in every call. For example, if you use /preapproval/create to create a preapproval based in CAD, the subsequent /checkout/create call referencing that preapproval must still explicitly set the currency to CAD.

Delayed payouts are supported in Canada as of API version 2016-05-04. In the /checkout/create call, set the auto_capture parameter to false.

Reference Guide for Canadian Merchants

Boarding Canadian Merchants

As with US users, your platform can create users using your own UI via the /user/register API, or via OAuth2 and redirecting to a WePay-supplied URI. There are additional requirements compared to US user signups. If your platform uses the OAuth2 method, these are handled for you by WePay's UI. If your platform uses /user/register, your sign-up user experience must incorporate these requirements.

The additional requirements for Canadian users are:

Creating a Canadian user using OAuth2

/oauth2/authorize has a new field that is required for Canadian users.

Parameter Required Type Description
user_country No String The value "CA"

You may also use the wepay.v2.js library and call the WePay.OAuth2.button_init() function. The country parameter and the value "CA" will have the same effect as with /oauth2/authorize.

Creating Canadian users with /user/register

If your platform uses /user/register, then you must first ensure that your UI presents the opt-in for debit cards, similar to the way WePay does for /oauth/authorize as shown above.

Parameter Required Type Description
tos_acceptance_time Yes Integer (64 bits) A unix_timestamp referencing the time the user accepted WePay's terms of service.

Creating accounts in Canadian dollars

Once your platform has an access token for a Canadian user, your platform can create accounts for that user in Canadian dollars.

At this time, a Canadian user can only have accounts with currency set to CAD, and a US user can only have accounts with currency set to USD.

Parameter Required Type Description
country Yes String (2 characters) The account's country of orgin 2-letter ISO code (e.g. 'US'). Only 'US' is supported for US users, and 'CA' is supported for CA users.
currencies Yes String (255 characters) Array of supported currency strings for this account (e.g. ["USD"]). Only USD is supported for US users, and CAD is supported for CA users.
country_options Yes JSON Object Object of country specific options. For Canada you must pass {"debit_opt_in":true | false}

Example for CA Users

Taking Payments in Canadian Dollars

Every call that accepts a currency argument has been extended to accept "CAD" as a value. This value must be "CAD" whenever the associated account_id references an account that is setup for CAD.

Every call that includes currency in its response has also been extended to report back CAD or USD as appropriate.

The following calls have all been extended to support CAD:

  • /checkout
  • /checkout/find
  • /checkout/create
  • /preapproval
  • /preapproval/find
  • /preapproval/create

Canadian user payment account setup

We've updated payment account setup flows to account for Canadian tax and address differences.

Canadian user setup flow

Canadian bank accounts

Canadian user bank account setup

Withdrawing funds via the API in Canadian Dollars

Similar to taking payments, the withdrawal API calls that accepts a currency argument have been extended to accept "CAD" as a value. This value must be "CAD" whenever the associated account_id references an account that is setup for CAD.

Every call that includes currency it its response has also been extended to report back CAD or USD as appropriate.

The extended calls are:

  • /withdrawal
  • /withdrawal/find
  • /withdrawal/create