TypeScript icon, indicating that this package has built-in type declarations

3.0.0-alpha.1 • Public • Published

ThreeDSecure Service

A library to simplify the implementation of 3DS flow using Paybyrd API.

How to install

npm i @paybyrd/threedsecure-service

How to configure ThreeDSecureService


  • container: HTML Element where the iframe needed to execute the challenge will be created. The iframe will be resizable as the container. DEFAULT: document.body
  • threeDSecureUrl: Paybyrd ThreeDSecure API base URL.DEFAULT: https://threedsecure.paybyrd.com
  • maxAttempts: The max attempts when the API returns transient errors, like 409, 404 or 504 status codes.DEFAULT: 50
  • attemptDelay: The amount of time in milliseconds to wait for the next attempt when some transient error happens.DEFAULT: 2000
  • culture: The culture that should be used for API responses.DEFAULT: en-US
  • onProgressFn: A notification function to identify what is happening inside the service.DEFAULT: NULL
  • onIFrameCreatedFn: A notification function to allow customizations to the iframe created.
  • onContainerCreatedFn: A notification function to allow customizations to the container created. If the container is passed, the function will be dispatched anyway.
const container = document.getElementById('container-3ds');
const threeDSecureUrl = 'https://threedsecure.paybyrd.com';
const maxAttempts = 50;
const attemptDelay = 2000;
const culture = 'en-US';
const onProgressFn = ({
}) => console.log(`${type}:${error}`);

const threeDSService = new ThreeDSecureService({

How to send the request


  • cardNumber: The card number.

  • cardHolder: The card holder.

  • cardExpiration: The card expiration following the pattern MM/YY.

  • merchantId: The merchant id registered to the API.

  • purchaseAmount: The purchase amount in cents.

  • purchaseCurrency: The purchase currency folowwing the ISO 4217 format.

  • challengeOptions: Indicator passed to ACS to indicate the configuration for challenge.

    • NoPreference: Do not use any challenge options
    • NoChallenge: Try to not require challenge
    • ThreeDSecurePreference: Let 3DS choose the best option
    • Required: Require challenge

    Sometimes, even when we require the challenge, the ACS will not ask for it, and the flow will run successfully until the end

const request = {
    cardNumber: '5500000000000001',
    cardHolder: 'PAYBYRD CARD HOLDER',
    cardExpiration: '07/30',
    merchantId: 10,
    purchaseAmount: 1,
    purchaseCurrency: 'EUR',
    challengeOptions: 'Required'

const threeDSResponse = await threeDSecureService.createAndExecute(request);

How to identify errors

try {
    const threeDSResponse = await threeDSecureService.createAndExecute(request);
} catch (error) {
    // Show the error.message in your website

How to send the paymentRequest

First of all, we truly recommend that you use the 3DS flow using the Order feature, where you can take a look here. When you create the order, we will return a checkoutKey that must be used for authentication.

const createPaymentRequest = {
    type: 'Card',
    card: {
        cardNumber: '5500000000000001',
        cardHolder: 'PAYBYRD CARD HOLDER',
        cardExpiration: '07/30',
        cvv: '123',
        threeDSVersion: threeDSResponse.version,
        aav: threeDSResponse.authenticationValue,
        caav_algorithm: threeDSResponse.authenticationValueAlgorithm,
        dsTransactionId: threeDSResponse.dsTransactionId,
        eci: threeDSResponse.eci,
        xid: threeDSResponse.xid,
        verificationMethod: threeDSResponse.verificationMethod

const createPaymentResponse = await axios.post(


3DS flow


npm i @paybyrd/threedsecure-service

DownloadsWeekly Downloads






Unpacked Size

287 kB

Total Files


Last publish


  • diego.vieira
  • ivelten.paybyrd
  • luizdias.inf
  • bernardoesberard
  • tiagor87