Authentication

3D Secure Authentication

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

Payblr supports Delegated SMS and Biometric / In-App SCA only. These methods allow your system to participate in the cardholder authentication flow while Payblr coordinates the integration between your system and the processor.

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 15 minutes ago

On this page

Overview At a glance Before you start Supported methods Supported authentication methods How Delegated SMS works Delegated SMS payload How Biometric / In-App SCA works Biometric / In-App SCA payloads SCA response & cancel Required setup Sequence diagram 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 SMS and Biometric / In-App SCA.

At a glance

Supported methods

Payblr supports Delegated SMS 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

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.

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

Supported methods

Payblr supports Delegated SMS and Biometric / In-App SCA. These methods allow your system to participate in the cardholder authentication flow while Payblr coordinates the processor integration.

Delegated SMS

The cardholder receives an OTP through your SMS flow as part of the delegated authentication flow.

Biometric / In-App SCA

The client 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 SMS	The one-time passcode is delivered to the cardholder through your SMS flow.	Receive the delegated SMS request, send the OTP to the cardholder, and support the SMS delivery flow.	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 SMS works

Delegated SMS uses your SMS delivery flow 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

SMS authentication required

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

Step 3

Notification received

The delegated SMS notification is received through the configured integration flow.

Step 4

OTP delivered

Your system sends the OTP to the cardholder using its SMS delivery flow.

Step 5

Cardholder completes challenge

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

Delegated SMS payload example

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

DelegateOTPNotification request

{
  "NotificationId": "f88458df-20ea-49b7-b890-119c2f5e8c6e",
  "PubToken": "123456789",
  "DelegateMethod": "otp-sms",
  "FinancialInstitutionId": "f88458df-20ea-49b7-b890-119c2f5e8c6e",
  "Language": "en-EN",
  "CardScheme": "MasterCard",
  "Device": {
    "Channel": "BROWSER",
    "Ip": "127.0.0.1",
    "Language": "en-EN"
  },
  "MerchantInfo": {
    "Id": "mer-12345",
    "Name": "Amazon",
    "Country": "840",
    "Url": "https://amazon.com",
    "ChallengePreference": "delegate-otp",
    "RedirectAppUrl": "https://amazon.com"
  },
  "TransactionInfo": {
    "Type": "payment",
    "ProtocolVersion": "1.0.2",
    "Channel": "app",
    "Token": "a98846d1-b694-4c85-9840-64ed56bc7c70",
    "DsTransactionId": "98315a91-e0b6-4fe0-8842-9ed82ea8ef0b",
    "Date": 1632990584,
    "ChallengedAt": 1650696156,
    "ChallengeExpiresAfter": 300,
    "ChallengeExpiry": 1650696456,
    "ChallengeMethod": "sms-otc",
    "Amount": "123.45",
    "Currency": {
      "Code": "978",
      "Exponent": "2"
    },
    "Recur": {
      "Frequency": "30",
      "EndRecur": "20221212"
    },
    "Install": "5"
  },
  "Passcode": "xxxxxx",
  "MobileNumber": "+911234",
  "MessageContent": "xxxxxx is the One Time Passcode required for completing a purchase of EUR xxxxx.xxxxx at Amazon with the last four digits of your card ending in xxxxx. Please use the One Time Passcode to complete the transaction."
}

Your response

Upon receipt of a request, your system should return a 200 HTTP response code.

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 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 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": "string",
    "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": "1.0.2",
    "Channel": "app",
    "DsTransactionId": "98315a91-e0b6-4fe0-8842-9ed82ea8ef0b",
    "Date": "2023-08-17T10:35:32.061Z",
    "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"
}

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 notification may not be resent.

Authorization header example

Authorization: Bearer <access_token>

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.

Request

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

Successful response

{
  "PubToken": "206187551",
  "DelegateScaId": "ddab0431-a615-42d7-81ab-5a6683bb5c3e",
  "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": "182293241",
  "DelegateScaId": "82b44d02-71db-4d00-9b3d-9fb7c0aa5eaa",
  "PmReferenceId": "refId",
  "Status": "FAILWITHFEEDBACK",
  "Error": {
    "ReferenceNumber": "504023",
    "Description": "DelegateSca status reporting to 3DSProvider failed",
    "Message": "DelegateSca status reporting to 3DSProvider failed"
  }
}

DelegateSCACancelNotification request

If the cardholder cancels the authentication, your system receives a DelegateSCACancelNotification 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": "string",
    "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": "1.0.2",
    "Channel": "app",
    "DsTransactionId": "98315a91-e0b6-4fe0-8842-9ed82ea8ef0b",
    "Date": "2023-08-17T10:35:32.061Z",
    "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

Payblr supports Delegated SMS and Biometric / In-App SCA only.

Configure credential management

Use 3DS credential endpoints only for the delegated authentication methods supported by Payblr.

Prepare client authentication flow

Your system must be able to participate in the cardholder authentication flow using the supported method.

Review API Explorer

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

3D Secure Authentication Sequence Diagram

Recommended delegated 3DS authentication sequence

User

Cardholder

Platform

Payblr 3DS

System

Client System

1. 3DS authentication required

Delegated auth

A cardholder transaction requires delegated 3D Secure authentication.

CardholderPayblr 3DS

2. Send delegated authentication request

Delegated auth

Endpoint

Client delegated authentication endpoint

Method

POST [CLIENT_3DS_DELEGATED_AUTH_ENDPOINT_URL]

Payblr forwards or coordinates the delegated authentication request with the client system.

Payblr 3DSClient System

3. Present supported challenge

Delegated auth

Endpoint

Delegated SMS or Biometric / In-App SCA

Client system presents Delegated SMS or Biometric / In-App SCA to the cardholder.

Client SystemCardholder

4. Complete authentication

Cardholder completes the supported authentication method in the client experience.

CardholderClient System

5. Return authentication result

Delegated auth

Endpoint

Report a biometric or in-app OOB SCA validation result to processor

Method

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

Client system returns the authentication result so the 3DS flow can continue.

Client SystemPayblr 3DS

6. Continue 3DS flow

Payblr continues coordinating the 3DS flow based on the returned authentication result.

Payblr 3DSCardholder

Sequence diagram showing how Payblr coordinates delegated 3D Secure authentication with the client system and supported cardholder authentication methods.

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 requests

Validate the request before processing authentication details or presenting the challenge to the cardholder.

Complete the supported challenge

Complete the Delegated SMS 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 / program responsibility
3DS setup	Coordinate the PSP integration and supported delegated authentication setup with the processor.	Confirm the delegated methods required for the program and provide setup information when requested.
Delegated SMS	Support the delegated SMS notification path and route the request as agreed.	Send the OTP to the cardholder through the client SMS provider or program SMS 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 SMS 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 SMS 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. Use the related endpoints to list, update, or delete 3DS credentials when cardholder authentication details change or need to be maintained.

Use the 3DS credential endpoints only for the delegated authentication methods supported by Payblr: Delegated SMS and Biometric / In-App SCA.

Operation	Purpose
Create 3DS Credentials	Enroll a card with the supported delegated authentication method.
List 3DS Credentials	Retrieve existing 3DS credential records associated with the card or cardholder.
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.

Credential management pattern

POST [PAYBLR_API_BASE_URL]/[CREATE_3DS_CREDENTIALS_RESOURCE_PATH]
Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json

GET [PAYBLR_API_BASE_URL]/[LIST_3DS_CREDENTIALS_RESOURCE_PATH]
Authorization: Bearer [ACCESS_TOKEN]
Accept: application/json

PATCH [PAYBLR_API_BASE_URL]/[UPDATE_3DS_CREDENTIALS_RESOURCE_PATH]
Authorization: Bearer [ACCESS_TOKEN]
Content-Type: application/json

DELETE [PAYBLR_API_BASE_URL]/[DELETE_3DS_CREDENTIALS_RESOURCE_PATH]
Authorization: Bearer [ACCESS_TOKEN]

API Explorer Reference

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

Use the 3DS credential endpoints only for the delegated authentication methods supported by Payblr: Delegated SMS and Biometric / In-App SCA.

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

Open API Explorer

Testing considerations

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

Test Delegated SMS enrollment and authentication behavior.
Test Biometric / In-App SCA enrollment and authentication behavior.
Validate failure scenarios, expired challenges, and unsupported authentication methods.
Confirm the client endpoint returns the expected response within the required authentication window.
Confirm credential create, list, update, and delete 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.

3D Secure Authentication supports Delegated SMS and Biometric / In-App SCA only.
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 SMS requires the client or program system to send the OTP to the cardholder.
Biometric / In-App SCA requires the client or program system to authenticate the cardholder through the mobile app and return the result.
Store notification references, credential references, challenge timestamps, authentication outcomes, and error details for troubleshooting and audit.
Handle 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.