Authentication

3D Secure Authentication

Payblr supports 3D Secure delegated authentication through its processor integration.

This guide covers the methods that require your system to integrate with Payblr: Delegated OTP and Biometric / In-App SCA.

This page explains the supported authentication methods, required setup, endpoint responsibilities, credential management, and testing considerations for integrating delegated 3D Secure authentication through Payblr.

Updated 1 minute ago

On this page

Overview At a glance Before you start Supported methods Supported authentication methods How Delegated OTP works Delegated OTP payload How Biometric / In-App SCA works Biometric / In-App SCA payloads SCA response & cancel Required setup Endpoint responsibilities Payblr & client responsibilities Credential management API Explorer Reference Testing considerations Implementation notes Next steps

Overview

Payblr supports 3D Secure delegated authentication through its processor integration. In this model, your system participates in the cardholder authentication flow while Payblr coordinates the delegated 3DS integration.

Your implementation should support only the delegated authentication methods enabled by Payblr: Delegated OTP and Biometric / In-App SCA.

At a glance

Supported methods

Client-integrated methods are Delegated OTP and Biometric / In-App SCA.

Integration model

Payblr acts as the integration layer between the processor and your system.

Delegated authentication

Your system participates in OTP delivery or app-based cardholder authentication.

Credential setup

Cards must be enrolled with the correct 3DS credentials before delegated authentication can be used.

Before you start

Delegated OTP Sequence Diagram

Delegated OTP authentication sequence

3DS service

Processor

Aggregator

Payblr 3DS

Client

Client System

User

Cardholder

1. Send OTP authentication request

Delegated auth

Delegated OTP

The processor sends DelegateOTPNotification to Payblr for a delegated OTP authentication session.

ProcessorPayblr 3DS

2. Forward OTP notification

Delegated auth

Delegated OTP

Endpoint

Client OTP notification endpoint

Method

POST [CLIENT_3DS_OTP_ENDPOINT_URL]

Payblr receives DelegateOTPNotification and forwards the payload to your configured endpoint.

Payblr 3DSClient System

3. Deliver OTP

Delegated auth

Delegated OTP

Endpoint

Preferred delivery method

Your system sends the OTP to the cardholder using its preferred delivery method.

Client SystemCardholder

4. Complete OTP challenge

Delegated OTP

The cardholder enters the OTP in the 3DS challenge screen to complete authentication.

CardholderProcessor

Sequence diagram showing the delegated OTP authentication flow between the processor, Payblr, the client system, and the cardholder.

Before using delegated 3D Secure authentication, the 3DS service must be configured for the program, the supported delegated methods must be enabled, and the required UAT and Production integration details must be provided.

For each environment, provide Payblr with the HTTPS endpoint that will receive DelegateOTPNotification for Delegated OTP and the HTTPS endpoint that will receive both DelegateSCANotification and DelegateSCACancelNotification for Biometric / In-App SCA. Only provide endpoints for methods enabled for your program.

Cards must also be enrolled with the correct 3DS credentials before Delegated OTP or Biometric / In-App SCA can be used during authentication.

Supported methods

Delegated OTP

The cardholder receives an OTP through your preferred delivery method as part of the delegated authentication flow.

Biometric / In-App SCA

The client's mobile app collects biometric or in-app approval from the cardholder.

Supported authentication methods

Payblr supports the following delegated authentication methods, with clear client and Payblr responsibilities.

Method	Description	Client responsibility	Payblr responsibility
Delegated OTP	The one-time passcode is delivered to the cardholder through your preferred delivery method.	Receive the delegated OTP request, send the OTP to the cardholder, and support the preferred delivery method.	Coordinate the delegated notification path between the processor and your system.
Biometric / In-App SCA	The cardholder authenticates through your mobile application using biometric or in-app approval.	Notify the cardholder, collect the authentication result, and return the result to Payblr within the challenge window.	Receive the delegated SCA notification, forward the request to your system, and return the authentication result to the processor.

How Delegated OTP works

Delegated OTP uses your preferred delivery method to send an OTP to the cardholder during the 3D Secure authentication process.

Step 1

Transaction starts

The cardholder initiates an online card transaction that requires 3D Secure authentication.

Step 2

OTP authentication required

The 3DS service determines that delegated OTP authentication is required for the cardholder.

Step 3

Notification received

Payblr receives DelegateOTPNotification from the processor and forwards the payload to your configured endpoint.

Step 4

OTP delivered

Your system sends the OTP to the cardholder using its preferred delivery method.

Step 5

Cardholder completes challenge

The cardholder enters the OTP in the 3DS challenge screen to complete authentication.

Delegated OTP Sequence Diagram

Delegated OTP authentication sequence

3DS service

Processor

Aggregator

Payblr 3DS

Client

Client System

User

Cardholder

1. Send OTP authentication request

Delegated auth

Delegated OTP

The processor sends DelegateOTPNotification to Payblr for a delegated OTP authentication session.

ProcessorPayblr 3DS

2. Forward OTP notification

Delegated auth

Delegated OTP

Endpoint

Client OTP notification endpoint

Method

POST [CLIENT_3DS_OTP_ENDPOINT_URL]

Payblr receives DelegateOTPNotification and forwards the payload to your configured endpoint.

Payblr 3DSClient System

3. Deliver OTP

Delegated auth

Delegated OTP

Endpoint

Preferred delivery method

Your system sends the OTP to the cardholder using its preferred delivery method.

Client SystemCardholder

4. Complete OTP challenge

Delegated OTP

The cardholder enters the OTP in the 3DS challenge screen to complete authentication.

CardholderProcessor

Sequence diagram showing the delegated OTP authentication flow between the processor, Payblr, the client system, and the cardholder.

Delegated OTP payload example

The following example shows a DelegateOTPNotification request for a delegated OTP authentication flow.

DelegateOTPNotification request

{
  "NotificationId": "0dfb2d49-2a14-4278-80c5-654d93c404d4",
  "Pubtoken": 132578471,
  "DelegateMethod": "otp-sms",
  "FinancialInstitutionId": "3db8013c-8349-47b0-bff8-7bff7c2d80d3",
  "Language": "en",
  "CardScheme": "visa",
  "Device": {
    "Channel": "BROWSER",
    "IP": "102.106.127.181",
    "Language": "en"
  },
  "MerchantInfo": {
    "Id": "1324123",
    "Name": "Amazon",
    "Url": "http://white-overheard.com",
    "ChallengePreference": "no-preference",
    "Country": "024",
    "RedirectAppUrl": null
  },
  "TransactionInfo": {
    "Type": "payment",
    "ProtocolVersion": "2.1.0",
    "Channel": "browser",
    "Token": "b762a5de-38cf-4e7a-ab6f-73119bee5053",
    "DsTransactionId": "254a5d3a-e251-4fc0-915a-51c01d3420a1",
    "Date": 1789721265,
    "ChallengedAt": 1789721265,
    "ChallengeExpiresAfter": 300,
    "ChallengeExpiry": 1789721565,
    "ChallengeMethod": "sms-otc",
    "Amount": "1234.23",
    "Currency": {
      "Code": "978",
      "Exponent": "2"
    },
    "Recur": null,
    "Install": null
  },
  "passcode": "879384",
  "MobileNumber": "+447755123456",
  "MessageContent": "879384 is the One Time Passcode required for completing a purchase of EUR 1234.23 at Amazon with the last four digits of your card ending in 8591. Please use the One Time Passcode to complete the transaction."
}

In this notification, Pubtokenis the card's 9-digit public identifier, not an authentication token. The transaction Amount is 1234.23 in the specified currency, with exponent 2.

Your response

Your endpoint must return HTTP 200 as soon as it accepts the notification. Deliver the OTP asynchronously after that acknowledgement. Do not wait to send the OTP before responding. Use a non-2xx response only when the notification cannot be accepted.

Successful response

{
  "status": "ok"
}

Error response

{
  "error": "invalid_request"
}

How Biometric / In-App SCA works

Biometric / In-App SCA uses your mobile application to prompt the cardholder for an authentication decision and return the result to Payblr.

Step 1

Transaction starts

The cardholder initiates an online card transaction that requires 3D Secure authentication.

Step 2

In-app authentication required

The 3DS service determines that Biometric / In-App SCA is required for the cardholder.

Step 3

Notification received

Payblr receives the delegated SCA notification and routes it to your system.

Step 4

Cardholder authenticates

The client's mobile app prompts the cardholder to approve or reject the authentication request.

Step 5

Result returned

The authentication result is returned to Payblr so Payblr can complete the delegated validation flow with the processor.

Biometric / In-App SCA Sequence Diagram

Delegated biometric authentication sequence

3DS service

Processor

Aggregator

Payblr 3DS

Client

Client System

User

Cardholder

1. Send biometric authentication request

Delegated auth

The processor sends DelegateSCANotification to Payblr for a biometric or in-app authentication session.

ProcessorPayblr 3DS

2. Send delegated authentication request

Delegated auth

Endpoint

Client biometric notification endpoint

Method

POST [CLIENT_3DS_BIOMETRIC_ENDPOINT_URL]

Payblr validates the processor request, resolves the client, and forwards the notification payload.

Payblr 3DSClient System

3. Present supported challenge

Delegated auth

Endpoint

Biometric / In-App SCA

The client system starts the biometric or in-app challenge in its cardholder application.

Client SystemCardholder

4. Complete authentication

Delegated auth

The cardholder completes the supported authentication method in the client's mobile app.

CardholderClient System

5. Return authentication result

Delegated auth

Endpoint

Submit a biometric or in-app OOB SCA validation result to Payblr

Method

POST /program-manager/thr/3ds/oob/validations

The client system submits the cardholder authentication result to Payblr before ChallengeExpiry.

Client SystemPayblr 3DS

6. Submit validation result

Delegated auth

Payblr authenticates to the processor and submits DelegateSCAValidation for the same authentication session.

Payblr 3DSProcessor

Sequence diagram showing the biometric and in-app authentication flow between the processor, Payblr, the client system, and the cardholder.

Biometric / In-App SCA payload examples

Biometric / In-App SCA uses REST-based JSON messages to initiate an out-of-band authentication session, return the authentication result, and notify your system when the cardholder cancels the authentication.

Message	Purpose	Direction
DelegateSCANotification	Notifies your system to initiate a Biometric / In-App authentication session.	Processor → Payblr → your system
DelegateSCAValidation	Returns the authentication result after the cardholder completes the Biometric / In-App flow.	Your system → Payblr → processor
DelegateSCACancelNotification	Notifies your system that the cardholder cancelled the authentication.	Processor → Payblr → your system

DelegateSCANotification request

{
  "NotificationId": "f88458df-20ea-49b7-b890-119c2f5e8c6e",
  "PubToken": 123456789,
  "DelegateMethod": "push-confirmation",
  "FinancialInstitutionId": "f88458df-20ea-49b7-b890-119c2f5e8c6e",
  "Language": "en-EN",
  "DelegateScaId": "bcd507g1-7ec8-43b4-8a07-6c5e17078967",
  "CardScheme": "MasterCard",
  "CreatedMode": "GA",
  "Device": {
    "Channel": "BROWSER",
    "Ip": "127.0.0.1",
    "Language": "en-EN"
  },
  "MerchantInfo": {
    "Id": "mer-12345",
    "Name": "Amazon",
    "Country": "840",
    "Url": "https://amazon.com",
    "ChallengePreference": "no-preference",
    "RedirectAppUrl": "merchantScheme://appName?transID=b2385523-a66c-4907-ac3c-91848e8c0067"
  },
  "TransactionInfo": {
    "Type": "payment",
    "ProtocolVersion": "2.2.0",
    "Channel": "app",
    "DsTransactionId": "98315a91-e0b6-4fe0-8842-9ed82ea8ef0b",
    "Date": 1650696100,
    "ChallengedAt": 1650696156,
    "ChallengeExpiresAfter": 300,
    "ChallengeExpiry": 1650696456,
    "ChallengeMethod": "push-confirmation",
    "Amount": "12345",
    "Currency": {
      "Code": "978",
      "Exponent": "2"
    },
    "Recur": {
      "Frequency": "30",
      "EndRecur": "20221212"
    },
    "Install": "5"
  },
  "DelegateStatus": "Active"
}

Store NotificationId, DelegateScaId,PubToken, and ChallengeExpiry before starting the cardholder challenge. Treat NotificationId as the notification idempotency key and DelegateScaId as the authentication-session correlation key.

SCA response & cancellation

Your response to DelegateSCANotification

Upon receipt of a DelegateSCANotification request, your system should return a 200 HTTP response code. If the notification is not acknowledged successfully, the processor does not resend it. Return the acknowledgement immediately after accepting the notification, then start the in-app challenge asynchronously. Do not wait for the cardholder to complete the biometric challenge before responding.

Payblr validates the processor's Bearer token before forwarding the notification. Payblr does not forward that token or add an Authorization header to the request sent to your notification endpoint. Network controls, such as allowlisting Payblr's outbound IP addresses, may be agreed during onboarding.

Successful acknowledgement

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "ok"
}

DelegateSCAValidation request

When the Biometric / In-App authentication is complete, your system sends the authentication result back to Payblr. Payblr then returns the validation result to the processor.

Payblr validation endpoint — UAT

POST https://uat-api.payblr.com/program-manager/thr/3ds/oob/validations
Authorization: Bearer <client_access_token>
Content-Type: application/json

PubTokenis the card's public identifier; it is not an authentication token. Copy PubToken and DelegateScaId from the original DelegateSCANotification so Payblr can correlate the result to the same authentication session.

Supported result values are SUCCESS, FAILURE, FAILWITHFEEDBACK, and ERROR.

Request

{
  "NotificationId": "f88458df-20ea-49b7-b890-119c2f5e8c6e",
  "PubToken": "123456789",
  "DelegateScaId": "bcd507g1-7ec8-43b4-8a07-6c5e17078967",
  "PmReferenceId": "refId",
  "Status": "SUCCESS",
  "Error": null
}

Successful response

{
  "PubToken": "123456789",
  "DelegateScaId": "bcd507g1-7ec8-43b4-8a07-6c5e17078967",
  "PmReferenceId": "refId",
  "Status": "SUCCESS",
  "Error": {
    "ReferenceNumber": "",
    "Description": "",
    "Message": ""
  }
}

The authentication session times out if the DelegateSCAValidation result is not received before the ChallengeExpiry time provided in the original DelegateSCANotification.

Error response example

If the validation result cannot be processed or reported successfully, the response may include an error status and error details.

{
  "PubToken": "123456789",
  "DelegateScaId": "bcd507g1-7ec8-43b4-8a07-6c5e17078967",
  "PmReferenceId": "refId",
  "Status": "FAILWITHFEEDBACK",
  "Error": {
    "ReferenceNumber": "504023",
    "Description": "Unable to report the authentication result",
    "Message": "The validation result could not be reported to the processor"
  }
}

DelegateSCACancelNotification request

If the cardholder cancels the authentication, your system receives a DelegateSCACancelNotification request on the same biometric endpoint used for active notifications. Correlate it using DelegateScaId and cancel or expire the matching local challenge.

{
  "NotificationId": "f88458df-20ea-49b7-b890-119c2f5e8c6e",
  "PubToken": 123456789,
  "DelegateMethod": "push-confirmation",
  "FinancialInstitutionId": "f88458df-20ea-49b7-b890-119c2f5e8c6e",
  "Language": "en-EN",
  "DelegateScaId": "bcd507g1-7ec8-43b4-8a07-6c5e17078967",
  "CardScheme": "MasterCard",
  "CreatedMode": "GA",
  "Device": {
    "Channel": "BROWSER",
    "Ip": "127.0.0.1",
    "Language": "en-EN"
  },
  "MerchantInfo": {
    "Id": "mer-12345",
    "Name": "Amazon",
    "Country": "840",
    "Url": "https://amazon.com",
    "ChallengePreference": "no-preference",
    "RedirectAppUrl": "merchantScheme://appName?transID=b2385523-a66c-4907-ac3c-91848e8c0067"
  },
  "TransactionInfo": {
    "Type": "payment",
    "ProtocolVersion": "2.2.0",
    "Channel": "app",
    "DsTransactionId": "98315a91-e0b6-4fe0-8842-9ed82ea8ef0b",
    "Date": 1650696100,
    "Amount": "12345",
    "Currency": {
      "Code": "978",
      "Exponent": "2"
    },
    "Recur": {
      "Frequency": "30",
      "EndRecur": "20221212"
    },
    "Install": "5"
  },
  "DelegateStatus": "Cancelled"
}

Upon receipt of a cancellation request, your system should return a 200 HTTP response code for successful receipt. If the cancellation request cannot be processed, your system should return a 400 HTTP response code.

Required setup

Before using delegated 3D Secure authentication, confirm that the 3DS service is configured for the program, the supported delegated methods are enabled, and the required UAT and Production integration details are provided.

Confirm supported methods

Confirm which client-integrated methods are enabled for the program: Delegated OTP and/or Biometric / In-App SCA.

Configure credential management

Use the Payblr 3DS credential endpoints for the authentication methods enabled for your program.

Configure client endpoints and API access

Provide the notification endpoints Payblr will call and obtain access to the Payblr API for submitting biometric results.

Review API Explorer

Use API Explorer to review endpoint-level request fields, response fields, and examples.

Endpoint responsibilities

Your system must be prepared to support the delegated authentication flow and return the required result based on the supported method.

Receive delegated authentication requests

Maintain the endpoint or integration behavior required to receive delegated 3DS authentication requests from Payblr.

Validate notification payloads

Validate the delegated method, notification identifiers, status, and challenge expiry before processing a notification.

Complete the supported challenge

Complete the Delegated OTP or Biometric / In-App SCA flow within the expected authentication window.

Return the authentication result

Return the required result or response so Payblr can continue coordinating the delegated 3DS flow.

Payblr & client responsibilities

Area	Payblr responsibility	Client responsibility
3DS setup	Coordinate the integration and supported delegated authentication setup with the processor.	Confirm the delegated methods required for the program and provide setup information when requested.
Integration security	Manage processor OAuth credentials, and authenticate client requests received through the Payblr API.	Use the Payblr Bearer token when submitting biometric results.
Delegated OTP	Support the delegated OTP notification path and route the request as agreed.	Send the OTP to the cardholder through the client's approved SMS provider or messaging process.
Biometric / In-App SCA	Receive the delegated SCA notification, route it to the client system, and return the authentication result to the processor.	Trigger the in-app authentication flow, collect the cardholder result, and return the result to Payblr within the required window.
Card enrollment	Support the 3DS credential management flow through the available APIs.	Ensure the correct cardholder data and delegated authentication credentials are available for enrollment.
Testing	Support UAT coordination, test card setup, issue review, and evidence validation.	Execute Delegated OTP and Biometric / In-App SCA test scenarios and provide evidence when required.
Monitoring and support	Store references and monitor delegated authentication processing, failures, and timeouts.	Monitor client-side delivery, mobile app authentication, and callback response behavior.

Credential management

The API Explorer can be used to review the 3DS credential management endpoints available for card enrollment and maintenance.

Start with Create 3DS Credentials to enroll a card with the supported delegated authentication method. Set the request type to OTPSMS for Delegated OTP or BIOMETRIC for Biometric / In-App SCA. Use the related endpoints to list, update, or delete 3DS credentials when cardholder authentication details change or need to be maintained.

Use only the credential types enabled for your program. Consult the API Reference for the exact Payblr resource paths, HTTP methods, request fields, and supported credential types.

Method	Create 3DS Credentials type
Delegated OTP	`OTPSMS`
Biometric / In-App SCA	`BIOMETRIC`

Operation	Purpose
Create 3DS Credentials	Enroll a card with the supported delegated authentication method.
List 3DS Credentials	Retrieve the 3DS credential records associated with a card.
Update 3DS Credentials	Update credential details when cardholder authentication data changes.
Delete 3DS Credentials	Remove delegated authentication credential details when they should no longer be used.
Get 3DS Configuration	Retrieve the card's current 3DS enrollment and provider configuration.

API Explorer Reference

The API Explorer can be used to review the 3DS credential management endpoints available for card enrollment and maintenance.

Start with Create 3DS Credentials to enroll a card with the supported delegated authentication method. Use the related endpoints to list, update, or delete 3DS credentials when cardholder authentication details change or need to be maintained.

The API Reference is the source of truth for resource paths, HTTP methods, schemas, authentication requirements, and supported environments.

Use the API Reference to confirm the endpoint-level request fields, response fields, examples, and supported environments before implementation.

Open API Reference

Testing considerations

Testing should confirm enrollment, credential maintenance, and delegated authentication behavior for each supported method.

Test Delegated OTP enrollment and authentication behavior.
Test Biometric / In-App SCA enrollment and authentication behavior.
Validate failure scenarios and expired challenges.
Confirm the client endpoint returns the expected response within the required authentication window.
Confirm notification endpoints accept Payblr requests under the network controls agreed during onboarding.
Confirm biometric results are submitted to Payblr with the Bearer token.
Confirm NotificationId duplicate handling and DelegateScaId correlation.
Confirm OTP values, access tokens, PANs, CVVs, and secrets are not written to logs.
Confirm credential create, list, update, delete, and configuration retrieval behavior in the selected environment.

Implementation notes

Before enabling delegated 3DS authentication, confirm supported methods, credential management behavior, endpoint behavior, timeout handling, failure handling, and test scenarios.

This page covers the client-integrated methods supported by Payblr: Delegated OTP and Biometric / In-App SCA.
UAT and Production integration details must be provided for each delegated method that is enabled.
Cards must be enrolled with the correct 3DS credentials before the delegated method can be used.
Delegated OTP requires the client system to send the OTP to the cardholder.
Biometric / In-App SCA requires the client system to authenticate the cardholder through its mobile app and return the result.
Store notification references, credential references, challenge timestamps, authentication outcomes, and error details for troubleshooting and audit.
Do not log OTP values, access tokens, PANs, CVVs, or secrets.
Handle duplicate notifications, client retries, cancellations, timeouts, and late authentication results safely.

Keep authentication controlled

Only process delegated authentication requests that pass the required validation checks and belong to supported 3DS authentication methods.

Keep credentials synchronized

Update or remove 3DS credentials when cardholder authentication details change or should no longer be used.

Next steps

After implementing 3D Secure delegated authentication, continue with Click to Pay if your program needs cardholder payment instrument enrollment and lifecycle management.