Authentication is a step for many payment methods and adds extra layers of security. Consumers must confirm their identity using various methods before the payment can be authorized.

The vast majority of digital payment methods are authenticated, exceptions include the following:

• Card processing in markets with no SCA/3DS requirement
• SEPA Direct Debit when externally managed mandates are used.

📘

Recommendation

We recommend building support for all authentication types. The authentication types for each payment method are specified in their properties.

Authentication Types

REDIRECT

Browser-based redirection flow where the consumer is taken to a dedicated page (provided by either PPRO or the upstream scheme or network) to authenticate the payment.

SCAN_CODE

A barcode or QR code is presented to consumers as a method of authenticating via their mobile device or code scanning device. Generally used for desktop -> mobile or desktop -> in person payment flows.

APP_INTENT

A Native app-to-app payment experience, supported by triggering an intent handled in iOS or Android for a native transition to the provider application.

EXTERNAL_3DS

Support for externally operated 3DS servers where PPRO receives the cryptogram data points and can pass through the data to a given card issuer.

Multiple Authentication Methods

Some payment methods offer multiple authentication options, allowing you to choose the most optimal one for the consumer and their device.

Example snippet

{...
  "authenticationMethods": [
    {
      "details": {}, // data needed to initalise authentication flow
      "type": "AUTHENTICATION_TYPE_1"
    },
    {
      "details": {}, // data needed to initalise authentication flow
      "type": "AUTHENTICATION_TYPE_2"
    }
  ]
...}

Authentication Settings

Some authentication types require configuration parameters to be provided in the payment charge request as authenticationSettings.

REDIRECT

A REDIRECT authentication requires you to provide a returnUrl which is where the consumer will be returned after completing the payment.

Request

{...
  "authenticationSettings": [
    {
      "type": "REDIRECT",
      "settings": {
        "returnUrl": "https://example.com/order_details?order_id=12345"
      }
    }
  ]
...}

Response

{...
  "authenticationMethods": [
    {
      "details": {
        "requestUrl": "https://mock-processor-public.stg.eu.dp.ppro.com/authenticator.html?payment-charge-id=charge_wKFAib6E4wkAAdVOaVIEF",
        "requestMethod": "GET"
      },
      "type": "REDIRECT"
    }
  ]
...}

• requestUrl is the URL where the consumer should be redirected to authenticate the payment.
• requestMethod is GET or POST.
  • GET, a simple redirection is expected.
  • POST, a client-side form submission with requestUrl as the form target is expected.

SCAN_CODE

There are no required authenticationSettings for SCAN_CODE authentication type.

If the payment method you are using supports customization of the code expiry time by the merchant , you can set this value using the scanBy field:

Request

{...
  "authenticationSettings": [
    {
      "type": "SCAN_CODE",
      "settings": {
        "scanBy": "2023-03-26T20:24:27Z"
      }
    }
  ]
...}

Response

{...
  "authenticationMethods": [
    {
      "type": "SCAN_CODE",
      "details": {
      	"codePayload": "upiGlobal://start_tx?id=abc&amount=100&currency=USD&from=QR",
        "codeImage": "https://qr.ppro.com/image.png?payload=aWQ9YWJjJmFtb3VudD0xMDAmY3VycmVuY3k9VVNEJmZyb209UVI",
        "codeDocument": "cdn.ppro.com//linktocodedocument",
        "scanBy": "2023-03-26T20:24:27Z",
        "codeType": "QR"
      },
    }
  ]
...}

• codePayload is the content the partner can use to render the code image on their side.
• codeImage is the code already rendered as a PNG image for convenience.
• codeDocument is a link to a document in which the code is displayed to the consumer. Only used by some payment methods (e.g. OXXO or Boleto vouchers)
• scanBy contains the ISO 8601 format timestamp at which the code authentication expires. If you set a custom value using the authenticationSettings field above, your custom time will be reflected here. If not, it will generate a default value according to the payment method being used.
• codeType Enum describing the type of code that should be used to render the code image from the payload. Possible values: QR, UPC, ITF, CODE128

APP_INTENT

There are no required authenticationSettings for APP_INTENT authentication.

Response

{...
  "authenticationMethods": [
    {
      "details": {
        "mobileIntentUri": "upiGlobal://start_tx?id=abc&amount=100&currency=USD&from=intent"
      },
      "type": "APP_INTENT"
    }
  ]
...}

• mobileIntentUriis the intent identifier that can be used to trigger the native OS transition.

EXTERNAL_3DS

Partners can use a 3rd-party Merchant Plug-in (MPI) to perform the 3-D Secure authentication. Once authenticated, you provide the payload in your payment charge request.

For a complete mapping of parameters see 3-D Secure.

Request

{...
  "authenticationSettings": [
    {
      "type": "EXTERNAL_3DS",
      "settings": {
        "authenticationStatus": "SUCCESS",
        "authenticationValue": "e3f7a0c2-fff8-4fb8-afab-dbae6e17c9cc",
        "eci": "01",
        "version": "2.0.0",
        "externalId": "a7fe5eae-d5bb-4f57-a946-2125c3c32801",
        "challenge": {
          "preference": "NO_CHALLENGE_REQUESTED",
          "outcome": "FRICTIONLESS",
          "exemptionReason": "LOW_VALUE"
        }
      }
    }
  ]
...}

Response

There are no authenticationMethods returned for the EXTERNAL_3DS authentication type.