UK Merchants and Strong Customer Authentication

Looking for general guidance on UK Merchants? The article has moved here.

 

What It Is

New requirements introduced in the second Payment Services Directive (PSD2) for cardholders to authenticate transactions. Strong Customer Authentication (SCA) is the permission piece of PSD2, and WePay is working with 3DSecure (3DS) to perform SCA. WePay has created new credit card and checkout API parameters so that platforms and merchants don’t need to integrate with 3DS themselves, but can simply provide the required information in the APIs already in use.

Find out more here.

Who It Impacts

All payment transactions across EU countries are regulated through PSD2. Specific to WePay, this means that all UK merchants processing card-not-present (i.e. web) payments with cards issued in the UK are impacted. Note that WePay will put transactions to UK merchants with cards issued outside the UK through SCA, though it is not required per PSD2.

When It Applies

Beginning in June 2021, issuers will decline some transactions if they have not gone through SCA. This will be done in a percentage ramp so that by 14 September 2021, all applicable transactions must go through SCA.

SCA API Changes

 

Your WePay app must be on version 2019-04-03 to implement SCA APIs. Note that the SCA APIs are not required in the schema, they are necessary to send for GBP transactions.

Once a checkout is created, WePay will determine the transaction’s eligibility for authentication regardless of whether SCA data is present or not. If a transaction is eligible for authentication and SCA data is not present, the transaction will be declined.

Important

Payers are recommended to complete the challenge within 30 seconds. There are issuer timeouts in place ranging from 30 seconds for Online Banking App users to 10 minutes.

Testing numbers can be found here.

/credit_card/create

For any credit cards which will require strong customer authentication (see criteria below), there is a unique requirements for the card holder name. The user_name parameter must contain the card holder’s first and last name such that there is a space between the two strings:

"user_name": "first_name last_name"

It is also important to keep in mind that for eligible cards, a 3-letter ISO code must be provided for address.region, and that uk as a value is not accepted.

/credit_card/authorize

Update your flow to send SCA data on /credit_card/authorize anytime you would send that request to WePay. SCA data is required on /credit_card/authorize if:

  • The cardholder’s address is in the UK and the card brand is either Visa or MasterCard
  • The credit card was created with the virtual_terminal_mode having the web value

If you don’t want to send SCA data on all /credit_card/authorize requests, you’ll need to implement checks on your end for cardholder address, card brand, and virtual terminal mode.

Once you receive a credit card ID from the credit card iFrame, the tokenization JS, or the API, send the /credit_card/authorize request like so:

{  
  "client_id": 12345,
  "client_secret": "asbasf2341",
  "credit_card_id": 235810395803,
  "strong_customer_authentication": {
    "redirect_uri": "https://www.example.com",
    "challenge_mode": "iframe",
    "device_information": {
      "browser": {
        "type": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
        "challenge_iframe_size": "FULL_SCREEN",
        "accept_headers": "application/json",
        "color_depth": 48,
        "java_enabled": true,
        "language": "en-US",
        "screen_height": 400,
        "screen_width": 250,
        "time_zone": 0
      }
    },
    "ip_address": "12.37.161.213"
  }  
}

The response will contain the challenge_uri parameter, which will either contain the challenge URI or will be null.

When the challenge URI is present, you must implement it in your UI for the payer. If you select iFrame mode, then load the iFrame on your page. If you select page mode, then indicate whether the URI should be loaded in a new page or the same page in your HTML. Once the payer completes the challenge, they will be sent to the value you provided in the strong_customer_authentication.redirect_uri parameter in the initial API request.

When the challenge URI is null, it means that the frictionless flow has occurred and you do not need to present any URI to the payer. The frictionless flow is when the card issuer is able to authenticate the payer without presenting a challenge.

Note

When hitting stage endpoints, the challenge_uri value will present an emulator, not the actual challenge interface. Actual challenge interface may not be used for testing purposes.

/checkout/create

Send SCA data on /checkout/create in the following cases:

  • It is a one-off payment
  • It is the first in a series of recurring payments
  • It is a payment using card-on-file (i.e. the payer has login credentials on your site and has saved their card data with you for faster checkout)

Send the /checkout/create request like so:

{
  "account_id": 1548718026,
  "amount": 20,
  "type": "goods",
  "currency": "GBP",
  "short_description": "test payment",
  "long_description": "This is a test payment",
  "email_message": {
      "to_payer": "Please contact us at 555-555-555 if you need assistance.",
      "to_payee": "Please note that we cover all shipping costs."
  },
  "delivery_type": "subscription",
  "fee": {
      "app_fee": 1,
      "fee_payer": "payer"
  },
  "callback_uri": "http://www.example.com",
  "auto_release": true,
  "payment_method": {
      "type": "credit_card",
      "credit_card": {
         "id": 1234
      }
   },
  "transaction_type": "recurring",
  "strong_customer_authentication": {
    "redirect_uri": "https://www.example.com",
    "challenge_mode": "iframe",
    "device_information": {
      "browser": {
        "type": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
        "challenge_iframe_size": "FULL_SCREEN",
        "accept_headers": "application/json",
        "color_depth": 48,
        "java_enabled": true,
        "language": "en-US",
        "screen_height": 400,
        "screen_width": 250,
        "time_zone": 0
      }
    },
    "ip_address": "12.37.161.213"
  }
}

The response will contain the challenge_uri parameter, which will either contain the challenge URI or will be null.

When the challenge URI is present, you must implement it in your UI for the payer. If you select iFrame mode, then load the iFrame on your page. If you select page mode, then indicate whether the URI should be loaded in a new page or the same page in your HTML. Once the payer completes the challenge, they will be sent to the value you provided in the strong_customer_authentication.redirect_uri parameter in the initial API request.

When the challenge URI is null, it means that the frictionless flow has occurred and you do not need to present any URI to the payer. The frictionless flow is when the card issuer is able to authenticate the payer without presenting a challenge.

Note

When hitting stage endpoints, the challenge_uri value will present an emulator, not the actual challenge interface. Actual challenge interface may not be used for testing purposes.

Exemptions

 

Some transactions are exempt from strong customer authentication. Find out how to indicate that a transaction is exempt via the API below.

Recurring Payments

  1. Send the /credit_card/create request with "recurring": true.
  2. Send the first /checkout/create request with "initiated_by": "customer" and "transaction_type": "recurring".
    Note: this initial checkout is subject to SCA, so the payer may be required to complete the challenge before the payment is submitted and before the exemption can be applied to future transactions.
  3. Send all subsequent /checkout/create requests for this recurring payment with "initiated_by": "merchant" and "transaction_type": "recurring".
    Note: if any subsequent checkouts are declined or failed, a challenge will be required before further exempt recurring transactions can be completed on this card.

Merchant Initiated Payments

For all other cases where the merchant initiates payment on behalf of the payer, follow these steps:

  1. Send the /credit_card/create request with "card_on_file": true.
  2. Send the first /checkout/create request with "transaction_type": "card_on_file"and "initiated_by": "merchant".
    Note: this initial checkout is subject to SCA, so the payer may be required to complete the challenge before the payment is submitted and before the exemption can be applied to future transactions.
  3. Send any subsequent /checkout/create requests for this series of merchant-initiated payments with "transaction_type": "card_on_file" and "initiated_by": "merchant".
    Note: if any subsequent checkouts are declined or failed, a challenge will be required before further exempt recurring transactions can be completed on this card.

Low Value Payment

If the transaction is for less than £ 30.00 GBP, then the card issuer will determine whether the transaction needs to be authenticated on a case-by-case basis. WePay still highly recommends sending SCA data for low value transactions so that they don’t get declined.

SCA Checkout State Changes

 

GBP checkouts have an additional state, sca initiated. This state means that the card issuer has requested strong customer authentication for the transaction, and the authentication is in-progress.

GBP Checkout State Diagram

  • SCA Initiated → New: Happy authentication path
  • SCA Initiated → Failed: When authentication fails
  • SCA Initiated → Expired: When the payer does not complete authentication