Payment Authentication
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
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
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
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
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¤cy=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¤cy=USD&from=intent"
},
"type": "APP_INTENT"
}
]
...}
mobileIntentUri
is 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.
Updated 7 days ago