@fat-zebra/sdk 1.0.2 → 1.0.3

package/src/sca/index.ts

@@ -1,329 +0,0 @@
-import * as t from './types'
-import {
-  EnrollmentScenario,
-  enrollmentScenarios,
-  ValidationScenario,
-  validationScenarios,
-} from './scenarios'
-import {
-  Customer,
-  CustomerSnakeCase,
-  PaymentIntent,
-  PublicEvent,
-} from '../shared/types'
-import {
-  CardinalManager,
-  PaymentValidatedDTO,
-} from './cardinal'
-import {
-  emit,
-} from '../shared/event-manager'
-import { toFzSli } from './eci-mappings'
-import { ThreedsData } from './types'
-import GatewayClient from '../shared/api-gateway-client'
-
-export interface ScaRunProps {
-  cardToken: string
-  customer?: Customer
-  paymentIntent: PaymentIntent
-  bin: string
-  challengeWindowSize?: t.ChallengeWindowSize
-}
-
-export interface ScaConfig {
-  gatewayClient: GatewayClient,
-}
-
-class Sca {
-  private _cardinal: CardinalManager
-  private _eventEmitTarget: HTMLDivElement | Window
-  private enrollmentResult: t.EnrollSCAResponse
-  private paymentIntent: PaymentIntent
-  private bin: string
-  private cardToken: string
-  private customer: Customer
-  private challengeWindowSize: t.ChallengeWindowSize
-  private sessionId: string
-  private gatewayClient: GatewayClient
-
-  constructor({ gatewayClient }: ScaConfig) {
-    this._eventEmitTarget = window;
-    this.sessionId = null;
-    this.gatewayClient = gatewayClient;
-
-    this.loadScript()
-  }
-
-  loadScript(): void {
-    if (!document.getElementById("songbird-script")) {
-      const script: HTMLScriptElement = document.createElement('script')
-      script.type = 'text/javascript';
-      script.id = "songbird-script"
-      script.src = process.env.SONGBIRD_URL
-      script.async = true;
-      script.onload = () => {
-        this._cardinal = new CardinalManager()
-      };
-      document.body.appendChild(script);
-    } else {
-      this._cardinal = new CardinalManager()
-    }
-  }
-
-  get cardinal(): CardinalManager {
-    return this._cardinal
-  }
-
-  set cardinal(cardinal: CardinalManager) {
-    this._cardinal = cardinal
-  }
-
-  get eventEmitTarget(): HTMLDivElement | Window {
-    return this._eventEmitTarget
-  }
-
-  // Specify the DOM element to which the SCA results are outputted.
-  set eventEmitTarget(target: HTMLDivElement | Window) {
-    this._eventEmitTarget = target
-  }
-
-  async run(config: ScaRunProps): Promise<void> {
-    // Persist states until next 3DS run.
-    this.paymentIntent = config.paymentIntent
-    this.bin = config.bin
-    this.cardToken = config.cardToken
-    this.customer = config.customer
-    this.challengeWindowSize = config.challengeWindowSize || t.ChallengeWindowSize.SIZE_FULL_PAGE
-
-    let cardinalJwt: string
-
-    // Generate Cardinal JWT
-    try {
-      cardinalJwt = await this.createCardinalJWT()
-    } catch (error) {
-      const message = 'FatZebra.3DS: JWT creation failed.'
-      emit(PublicEvent.SCA_ERROR, {
-        errors: [message],
-        data: null
-      })
-      console.log(message)
-      return
-    }
-
-    // Init cardinal
-    this._cardinal.setup(cardinalJwt)
-
-    if (!this.sessionId) {
-      const paymentsSetupCompleteResponse = await this._cardinal.onPaymentSetupComplete()
-      this.sessionId = paymentsSetupCompleteResponse.sessionId
-
-      // Register handler. Called after OTP is entered on challenge prompt.
-      this._cardinal.onPaymentValidated(async (data: PaymentValidatedDTO, error: string): Promise<void> => {
-        if (typeof error == 'string') {
-          const message = `FatZebra.3DS: Validation failed. ${error}.`
-          emit(PublicEvent.SCA_ERROR, {
-            errors: [message],
-            data: null,
-          })
-          console.log(message)
-          return
-        }
-
-        const decodeSCASessionResponse = (await this.gatewayClient.decodeSCASession({
-          token: data.jwt
-        })).data as t.DecodeSCASessionResponse
-
-        if (data.processorTransactionId !== decodeSCASessionResponse.processor_transaction_id) {
-          const message = 'FatZebra.3DS: Validation failed. Invalid process transaction id.'
-          emit(PublicEvent.SCA_ERROR, {
-            errors: [message],
-            data: null
-          })
-          console.log(message)
-        }
-
-        let validateSCAResponse
-
-        try {
-          const requestParams: t.ValidateSCARequest = {
-            amount: this.paymentIntent.payment.amount,
-            authentication_transaction_id: this.enrollmentResult.authentication_transaction_id,
-            card_token: this.cardToken,
-            currency: this.paymentIntent.payment.currency,
-            pareq: this.enrollmentResult.pareq,
-            reference: this.paymentIntent.payment.reference,
-          }
-
-          validateSCAResponse = (await this.gatewayClient.validateSCA(requestParams)).data as t.ValidateSCAResponse
-
-        } catch (errorResponse) {
-          const message = 'FatZebra.3DS: Validation failed. Server error.'
-          emit(PublicEvent.SCA_ERROR, {
-            errors: [message],
-            data: null,
-          })
-          console.log(message)
-          return
-        }
-
-        const threedsData = threedsResponseData(validateSCAResponse)
-        const scenario: ValidationScenario = getValidationResult(validateSCAResponse)
-
-        if (scenario.outcome.success) {
-          const message = `FatZebra.3DS: 3DS success - ${scenario.description}.`
-          emit(PublicEvent.SCA_SUCCESS, {
-            message,
-            data: threedsData,
-          })
-          console.log(message)
-        } else {
-          const message = `FatZebra.3DS: 3DS error - ${scenario.description}`
-          emit(PublicEvent.SCA_ERROR, {
-            errors: [message],
-            data: {
-              errorCode: scenario.outcome.errorCode
-            },
-          })
-          console.log(message)
-        }
-      })
-    }
-
-    // Cardinal processs BIN using directory server. This determines the 3DS version used.
-    try {
-      await this._cardinal.processBin(this.bin)
-    } catch (err) {
-      const message = 'FatZebra.3DS: BIN verification failed.'
-      emit(PublicEvent.SCA_ERROR, {
-        errors: [message],
-        data: null
-      })
-      console.log(message)
-      return
-    }
-
-    try {
-      await this.check3DSEnrollment()
-    } catch (err) {
-      const message = 'FatZebra.3DS: Enrollment failed. Server error.'
-      emit(PublicEvent.SCA_ERROR, {
-        errors: [message],
-        data: null
-      })
-      console.log(message)
-      return
-    }
-
-    this.handleEnrollmentResult(this.enrollmentResult)
-  }
-
-  async createCardinalJWT(): Promise<string> {
-    const { payment } = this.paymentIntent
-    const response = (await this.gatewayClient.createSCASession({
-      amount: payment.amount,
-      currency: payment.currency,
-      hide_card_holder: payment.hide_card_holder,
-    })).data as t.CreateSCASessionResponse
-
-    return response.jwt
-  }
-
-  async check3DSEnrollment(): Promise<void> {
-    // Persist enrollResult state in memory for handlePaymentValidation handler
-    this.enrollmentResult = (await this.gatewayClient.enrolSCA({
-      amount: this.paymentIntent.payment.amount,
-      card_token: this.cardToken,
-      currency: this.paymentIntent.payment.currency,
-      reference: this.paymentIntent.payment.reference,
-      verification: this.paymentIntent.verification,
-      session_id: this.sessionId,
-      challenge_window_size: this.challengeWindowSize,
-      hide_card_holder: this.paymentIntent.payment.hide_card_holder,
-      customer: this.customerProperties(this.customer),
-    })).data as t.EnrollSCAResponse
-  }
-
-  customerProperties(customer: Customer): CustomerSnakeCase {
-    let properties: CustomerSnakeCase = {};
-    if (!customer) return properties;
-    if (customer.firstName) properties.first_name = customer.firstName
-    if (customer.lastName) properties.last_name = customer.lastName
-    if (customer.email) properties.email = customer.email
-    if (customer.address) properties.address = customer.address
-    if (customer.city) properties.city = customer.city
-    if (customer.state) properties.state = customer.state
-    if (customer.postcode) properties.postcode = customer.postcode
-    if (customer.country) properties.country = customer.country
-    return properties
-  }
-
-  handleEnrollmentResult(enrollSCAResponse: t.EnrollSCAResponse): void {
-    const threedsData = threedsResponseData(enrollSCAResponse)
-    const scenario: EnrollmentScenario = getEnrollmentResult(enrollSCAResponse)
-
-    if (scenario.outcome.authenticationType === 'challenge') {
-      this._cardinal.continue(
-        enrollSCAResponse.acs_url,
-        enrollSCAResponse.pareq,
-        enrollSCAResponse.authentication_transaction_id
-      )
-      return
-    }
-
-    if (scenario.outcome.success) {
-      const message = `FatZebra.3DS: 3DS success - ${scenario.description}.`
-      emit(PublicEvent.SCA_SUCCESS, {
-        message,
-        data: threedsData,
-      })
-      console.log(message)
-    } else {
-      const message = `FatZebra.3DS: 3DS error - ${scenario.description}`
-      emit(PublicEvent.SCA_ERROR, {
-        errors: [message],
-        data: {
-          errorCode: scenario.outcome.errorCode
-        },
-      })
-      console.log(message)
-    }
-  }
-}
-
-const threedsResponseData = (response: t.EnrollSCAResponse | t.ValidateSCAResponse): ThreedsData => {
-  return {
-    // CAVV: Visa & Amex only
-    // AAV: Mastercard only, known as UCAF
-    cavv: response.cavv || response.aav,
-    par: response.pares,
-    sli: toFzSli(response.eci),
-    xid: response.xid,
-    ver: response.enrolled,
-    directoryServerTxnId: response.directory_server_txn_id,
-    threedsVersion: response.version,
-  }
-}
-
-const getEnrollmentResult = (enrollment: t.EnrollSCAResponse): EnrollmentScenario => {
-  return enrollmentScenarios.find((item: EnrollmentScenario) => {
-    return item.reasonCode === enrollment.reason_code &&
-      item.veresEnrolled === enrollment.enrolled &&
-      item.pares === enrollment.pares &&
-      item.threedsVersion === getMajor3dsVersion(enrollment.version)
-  })
-}
-
-const getValidationResult = (validation: t.ValidateSCAResponse): ValidationScenario => {
-  return validationScenarios.find((item: ValidationScenario) => {
-    return item.reasonCode === validation.reason_code &&
-      item.pares === validation.pares &&
-      item.threedsVersion === getMajor3dsVersion(validation.version)
-  })
-}
-
-// 3DS versioning follows SEMVER format. The first charactor is the major version number.
-const getMajor3dsVersion = (original: string): string => {
-  return original[0]
-}
-
-export default Sca;

package/src/sca/scenarios/enrollment.ts

@@ -1,164 +0,0 @@
-import {  ScaErrorCode, VEResEnrolled, PARes } from '../types'
-
-interface EnrollmentScenario {
-  description: string
-  threedsVersion: '1' | '2'
-  reasonCode: string
-  veresEnrolled: VEResEnrolled
-  pares: PARes | null // null is for challenge
-  outcome: {
-    authenticationType?: 'bypass' | 'frictionless' | 'challenge'
-    success: boolean
-    errorCode?: string
-  }
-}
-
-const enrollmentScenarios: EnrollmentScenario[] = [
-/***************************************************************/
-/********************** 3DS2 scenarios *************************/
-/***************************************************************/
-  {
-    // Bypassed Authentication
-    description: 'Bypassed Authentication',
-    threedsVersion: '2',
-    reasonCode: '100',
-    veresEnrolled: VEResEnrolled.BYPASSED,
-    pares: null,
-    outcome: {
-      success: false, // no liability shift
-      authenticationType: 'bypass',
-      errorCode: ScaErrorCode.BYPASSED_AUTHENTICATION
-    },
-  },
-  {
-    // Authentication not Available on Lookup
-    description: 'Authentication not Available on Lookup ',
-    threedsVersion: '2',
-    reasonCode: '100',
-    veresEnrolled: VEResEnrolled.UNABLE,
-    pares: null,
-    outcome: {
-      success: false, // no liability shift
-      errorCode: ScaErrorCode.AUTHENTICATION_NOT_AVAILABLE_ON_LOOKUP
-    }
-  },
-  {
-    // Attempts Processing Frictionless Authentication
-    description: 'Attempts Processing Frictionless Authentication',
-    threedsVersion: '2',
-    reasonCode: '100',
-    veresEnrolled: VEResEnrolled.ENROLLED,
-    pares: PARes.ATTEMPTED,
-    outcome: {
-      authenticationType: 'frictionless',
-      success: true
-    }
-  },
-  {
-    // Successful Frictionless Authentication
-    description: 'Successful Frictionless Authentication',
-    threedsVersion: '2',
-    reasonCode: '100',
-    veresEnrolled: VEResEnrolled.ENROLLED,
-    pares: PARes.SUCCESS,
-    outcome: {
-      authenticationType: 'frictionless',
-      success: true
-    }
-  },
-  {
-    // Unavailable Frictionless Authentication
-    description: 'Unavailable Frictionless Authentication',
-    threedsVersion: '2',
-    reasonCode: '100',
-    veresEnrolled: VEResEnrolled.ENROLLED,
-    pares: PARes.NOT_COMPLETED,
-    outcome: {
-      authenticationType: 'frictionless',
-      success: false,
-      errorCode: ScaErrorCode.UNAVAILABLE_FRICTIONLESS_AUTHENTICATION
-    }
-  },
-  {
-    // Challenge. Continue with OTP prompt
-    description: 'Challenge. Continue with OTP prompt',
-    threedsVersion: '2',
-    reasonCode: '475',
-    veresEnrolled: VEResEnrolled.ENROLLED,
-    pares: null,
-    outcome: {
-      authenticationType: 'challenge',
-      success: true
-    }
-  },
-  {
-    // Unsuccessful Frictionless Authentication
-    description: 'Unsuccessful Frictionless Authentication',
-    threedsVersion: '2',
-    reasonCode: '476',
-    veresEnrolled: VEResEnrolled.ENROLLED,
-    pares: PARes.CANCELED,
-    outcome: {
-      authenticationType: 'frictionless',
-      success: false,
-      errorCode: ScaErrorCode.UNSUCCESSFUL_FRICTIONLESS_AUTHENTICATION
-    }
-  },
-  {
-    // Rejected Frictionless Authentication
-    description: 'Rejected Frictionless Authentication',
-    threedsVersion: '2',
-    reasonCode: '476',
-    veresEnrolled: VEResEnrolled.ENROLLED,
-    pares: PARes.REJECTED,
-    outcome: {
-      authenticationType: 'frictionless',
-      success: false,
-      errorCode: ScaErrorCode.REJECTED_FRICTIONLESS_AUTHENTICATION
-    }
-  },
-/***************************************************************/
-/********************** 3DS1 scenarios *************************/
-/***************************************************************/
-  {
-    // Proceed to challenge step
-    description: '*****',
-    threedsVersion: '1',
-    reasonCode: '475',
-    veresEnrolled: VEResEnrolled.ENROLLED,
-    pares: null,
-    outcome: {
-      authenticationType: 'challenge',
-      success: true
-    }
-  },
-  {
-    // Error, Unavailable Authentication
-    description: 'Error; Unavailable Authentication',
-    threedsVersion: '1',
-    reasonCode: '100',
-    veresEnrolled: VEResEnrolled.UNABLE,
-    pares: null,
-    outcome: {
-      authenticationType: 'frictionless',
-      success: false
-    }
-  },
-  {
-    // Not Enrolled
-    description: 'Not Enrolled',
-    threedsVersion: '1',
-    reasonCode: '100',
-    veresEnrolled: VEResEnrolled.NOT_ENROLLED,
-    pares: null,
-    outcome: {
-      authenticationType: 'frictionless',
-      success: true
-    }
-  },
-]
-
-export {
-  enrollmentScenarios
-}
-export type { EnrollmentScenario }

package/src/sca/scenarios/index.ts

@@ -1,4 +0,0 @@
-export { enrollmentScenarios } from './enrollment'
-export type { EnrollmentScenario } from './enrollment'
-export { validationScenarios } from './validation'
-export type { ValidationScenario } from './validation'

package/src/sca/scenarios/validation.ts

@@ -1,142 +0,0 @@
-import { ScaErrorCode, VEResEnrolled, PARes } from '../types'
-
-interface ValidationScenario {
-  description: string
-  threedsVersion: '1' | '2',
-  reasonCode: string
-  veresEnrolled: VEResEnrolled
-  pares: PARes | null // null is for challenge
-  outcome: {
-    authenticationType?: 'bypass' | 'frictionless' | 'challenge',
-    success: boolean,
-    errorCode?: string
-  }
-}
-
-const validationScenarios: ValidationScenario[] = [
-/***************************************************************/
-/********************** 3DS2 scenarios *************************/
-/***************************************************************/
-  {
-    // Successful Step-Up Authentication
-    description: 'Successful Step-Up Authentication',
-    threedsVersion: '2',
-    reasonCode: '100',
-    veresEnrolled: null,
-    pares: PARes.SUCCESS,
-    outcome: {
-      authenticationType: 'challenge',
-      success: true // liability shift
-    },
-  },
-  {
-    // Unsuccessful Step-Up Authentication
-    description: 'Unsuccessful Step-Up Authentication',
-    threedsVersion: '2',
-    reasonCode: '476',
-    veresEnrolled: null,
-    pares: PARes.CANCELED,
-    outcome: {
-      authenticationType: 'challenge',
-      success: false, // no liability shift
-      errorCode: ScaErrorCode.UNSUCCESSFUL_STEPUP_AUTHENTICATION
-    }
-  },
-  {
-    // Unavailable Step-Up Authentication
-    description: 'Unavailable Step-Up Authentication',
-    threedsVersion: '2',
-    reasonCode: '100',
-    veresEnrolled: null,
-    pares: PARes.NOT_COMPLETED,
-    outcome: {
-      authenticationType: 'challenge',
-      success: false, // no liability shift
-      errorCode: ScaErrorCode.UNAVAILABLE_STEPUP_AUTHENTICATION
-    }
-  },
- /***************************************************************/
- /********************** 3DS1 scenarios *************************/
- /***************************************************************/
-  {
-    // Successful Step-Up Authentication
-    description: 'Successful Authentication',
-    threedsVersion: '1',
-    reasonCode: '100',
-    veresEnrolled: null,
-    pares: PARes.SUCCESS,
-    outcome: {
-      authenticationType: 'challenge',
-      success: true // liability shift
-    },
-  },
-  {
-    // Incomplete Authentication
-    description: 'Incomplete Authentication',
-    threedsVersion: '1',
-    reasonCode: '100',
-    veresEnrolled: null,
-    pares: PARes.NOT_COMPLETED,
-    outcome: {
-      authenticationType: 'challenge',
-      success: false,
-      errorCode: ScaErrorCode.UNAVAILABLE_STEPUP_AUTHENTICATION
-    }
-  },
-  {
-    // Attempts Processing
-    description: 'Attempts Processing',
-    threedsVersion: '1',
-    reasonCode: '100',
-    veresEnrolled: null,
-    pares: PARes.ATTEMPTED,
-    outcome: {
-      authenticationType: 'challenge',
-      success: true
-    }
-  },
-  {
-    // Unsuccessful Authentication
-    description: 'Unsuccessful Authentication',
-    threedsVersion: '1',
-    reasonCode: '476',
-    veresEnrolled: null,
-    pares: PARes.CANCELED,
-    outcome: {
-      authenticationType: 'challenge',
-      success: false,
-      errorCode: ScaErrorCode.UNSUCCESSFUL_STEPUP_AUTHENTICATION
-    }
-  },
-  {
-    // Successful Authentication But Invalid PARes
-    description: 'Successful Authentication But Invalid PARes',
-    threedsVersion: '1',
-    reasonCode: '476',
-    veresEnrolled: null,
-    pares: null,
-    outcome: {
-      authenticationType: 'challenge',
-      success: false,
-      errorCode: ScaErrorCode.UNSUCCESSFUL_STEPUP_AUTHENTICATION
-    }
-  },
-    {
-    // Authentication Error
-    description: 'Authentication Error',
-    threedsVersion: '1',
-    reasonCode: '476',
-    veresEnrolled: null,
-    pares: null,
-    outcome: {
-      authenticationType: 'challenge',
-      success: false, // no liability shift
-      errorCode: ScaErrorCode.UNSUCCESSFUL_STEPUP_AUTHENTICATION
-    }
-  },
-]
-
-export {
-  validationScenarios
-}
-export type { ValidationScenario }