Working with UK 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 UK users. In particular, you should be familiar with the following concepts: create accounts for your users and charge a customer.

WePay supports your UK users that:

  • Have a UK address
  • Have a UK bank account
  • Want to accept payments in British Pounds
  • Want to have funds settled to them in British Pounds

Do you have users in both the US and UK?

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 UK Users

  1. Your application must be specially enabled for UK users.
  2. Indicate a merchant is from the UK by using appropriate parameters in /account/create.
  3. When setting up their payment account, users will see UK versions of the setup screens.
  4. UK users must complete setup prior to accepting payments (US merchants can defer some elements).
  5. On checkout, specify GBP for currency.
  6. At this time, application fees collected for GBP transactions are settled out monthly to your app account with a minimum settlement amount of £1000.00 GBP.

Limitations

  • The “pay with bank” option is not available - payers can pay with credit or debit cards only.
  • Any account setup for the UK at this time will only accept payments in British Pounds (GBP).
  • For any payments made to UK merchants, delayed payouts are not currently supported.

Tip

The refund time period is up to 90 days for UK merchants.


Example Code for UK Users

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

Create UK accounts

You may create a UK merchant account with /account/create, and include the parameters:

"country": "GB", "currencies": ["GBP"],

You should also be aware of changes to the type and mcc parameters, where supplied. Full details are included in the reference guide below.

Verifying UK accounts

Important Note: UK Know Your Customer (KYC) requirements are different from the US. In the UK it is necessary for all users to complete KYC prior to first payment. Please use /user/send_confirmation to initiate the process.

KYC requirements will depend on the merchant’s entity type, as listed above. The WePay IFrame will present the required fields dynamically, breaking the merchant boarding flow into either 4 or 5 steps, depending on the type of entity. WePay will work with you during integration to confirm the size requirements for this IFrame once we have your style information.

Because of these additional steps, UK accounts created by /account/create will not be ready to transact until KYC has been completed. The only step which may be deferred by the merchant is entering bank account details, until which the account will obviously not be ready for withdrawals.

You can monitor the account readiness via the statuses part of the /account object. It should show incoming_payment_status as OK once the KYC flow is complete and outgoing_payment_status as OK once valid bank account details are provided. In practice the only circumstances where incoming_payment_status will not be OK is if a new merchant has not yet completed KYC or occasionally where those checks have required us to request additional documentation.

Checkout

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

At this time auto release is mandatory in the UK - setting this to false to achieve a delayed payout, is not possible.


Reference Guide for UK Merchants

Boarding UK 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 UK users are:

  • Accepting Terms of Service: The WePay TOS includes a specific version for UK merchants, which must be accepted.

Creating a UK User Using OAuth2

The /oauth2/authorize will have new field that is required for UK users.

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

You may also use the WePay JavaScript library and call the WePay.OAuth2.button_init() function. The country parameter and the value “UK” will have the same effect as with /oauth2/authorize.

Creating a UK User with /user/register

If you platform uses /user/register then no changes are required.

Creating UK accounts in British Pounds

Once your platform has an access token for a UK user, your platform can create accounts for that user in British Pounds (GBP).

Suggestion

At this time, a UK user can only have accounts with currency set to GBP, just as a US user can only have accounts with currency set to USD.

As well as using the correct country and currency, please note the additional type values that must be specified if applicable, and the merchant category code mcc value limitation.

Parameter Required Type Description
country Yes String (2 characters) The account's country of orgin 2-letter ISO code country Yes characters) (e.g. 'US'). Only 'US' is supported for US users, and ‘UK’ is supported for UK users.
currencies Yes String (255 characters) Array of supported currency strings for this currencies Yes characters) account (e.g. ["USD"]). Only USD is supported for US users, and GBP is supported for UK users.
type No String (255 characters) The type of account you are creating. Most commonly: individual, private limited company, or charity. Possible values:
  • individual
  • partnership
  • private_limited_company
  • public_limited_company
  • limited_liability_partnership
  • charity
mcc No Integer (64 bits) The Merchant Category Code (MCC) indicating Integer (64 the merchant's type of business. Please note that bits) at this time not all merchant categories are supported for the UK.

Example for UK Users

Taking Payments in British Pounds

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

Every call that includes currency in its response has also been extended to report back GBP where appropriate.

The following calls have all been extended to support GBP:

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

Please note that at this time delayed payouts are not supported in the UK so when making /checkout/create requests the auto_capture value should be excluded or set to true.

UK User Payment Account Setup

We’ve updated payment account setup flows to account for UK Know Your Customer (KYC) differences.

Verify

UK Bank Accounts

Accounts

Withdrawing Funds with the API in British Pounds

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

Every call that includes currency it its response has also been extended to report back GBP where appropriate.

The extended calls are:

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