@fat-zebra/sdk 1.0.1 → 1.0.3

package/src/sca/cardinal.ts

@@ -1,136 +0,0 @@
-// https://cardinaldocs.atlassian.net/wiki/spaces/CC/pages/1409568/Configurations
-interface CardinalConfig {
-  timeout?: number
-  maxRequestRetries?: number
-  logging?: {
-    level: 'on' | 'off' | 'verbose'
-  }
-}
-
-interface CardinalContinueObject {
-  AcsUrl: string
-  Payload: string
-}
-
-interface CardinalOrderObject {
-  OrderDetails: {
-    TransactionId: string
-  }
-}
-
-interface CardinalSetupCompleteResponseData {
-  sessionId: string
-  modules: { module: string, loaded: boolean }[]
-}
-
-// https://cardinaldocs.atlassian.net/wiki/spaces/CC/pages/98315/Response+Objects
-interface PaymentValidatedResponseData {
-  Validated: boolean
-  ErrorNumber: number
-  ErrorDescription: string
-  ActionCode: 'SUCCESS' | 'NOACTION' | 'FAILURE' | 'ERROR'
-  Payment: {
-    OrderId: string
-    OrderNumber: string
-    ProcessorTransactionId: string
-    ReasonDescription: string
-  }
-}
-
-interface PaymentValidatedDTO {
-  processorTransactionId: string
-  jwt: string
-}
-
-enum CardinalWorkflow {
-  CCA = 'cca',
-  INIT = 'init',
-}
-
-enum CardinalPaymentEvent {
-  SETUP_COMPLETE = 'payments.setupComplete',
-  VALIDATED = 'payments.validated',
-}
-
-interface Cardinal {
-  configure(config: CardinalConfig): void
-  continue(
-    workflow: CardinalWorkflow,
-    data: CardinalContinueObject,
-    order: CardinalOrderObject
-  ): void
-  on(event: string, callback: (...data: any[]) => void): void
-  setup(workflow: CardinalWorkflow, data: any): void
-  trigger(event: string, cardBin: string): Promise<any>
-}
-
-interface ScaResult {
-  success: boolean
-  type: 'frictionless' | 'challenge' | 'none'
-  error: string
-}
-
-const defaultConfig = {
-  timeout: 8000,
-  maxRequestRetries: 3,
-  logging: {
-    level: 'on'
-  }      
-}
-
-export default class CardinalManager {
-  private cardinal: Cardinal
-
-  constructor(config?: CardinalConfig) {
-    window.Cardinal.configure((config ? config : defaultConfig as CardinalConfig))
-  }
-
-  setup(jwt: any): void {
-    window.Cardinal.setup(CardinalWorkflow.INIT, { jwt })
-  }
-
-  onPaymentValidated(handler: (data: PaymentValidatedDTO, error: string) => void): void {
-    window.Cardinal.on('payments.validated', (data: PaymentValidatedResponseData, jwt: string) => {      
-      if (data.ErrorDescription.toLowerCase() === 'success') {
-        handler({
-          processorTransactionId: data.Payment.ProcessorTransactionId,
-          jwt
-        }, null)
-      } else {
-        handler(null, data.ErrorDescription)
-      }
-    })
-  }
-
-  onPaymentSetupComplete(): Promise<CardinalSetupCompleteResponseData> {
-    return new Promise((resolve, reject) => {
-      window.Cardinal.on(CardinalPaymentEvent.SETUP_COMPLETE, (data: CardinalSetupCompleteResponseData) => {
-        resolve(data)
-      })
-    })
-  }
-
-  async processBin(bin: string): Promise<any> {
-    await window.Cardinal.trigger('bin.process', bin)
-  }
-
-  continue(acsUrl: string, pareq: string, transactionId: string) {
-    window.Cardinal.continue(
-      CardinalWorkflow.CCA,
-      {
-        AcsUrl: acsUrl,
-        Payload: pareq
-      },
-      {
-        OrderDetails: {
-          TransactionId: transactionId
-        }
-      }
-    )
-  }
-}
-
-export {
-  CardinalManager,
-  PaymentValidatedDTO,
-}

package/src/sca/eci-mappings.ts

@@ -1,63 +0,0 @@
-// FatZebra only supports SLI 05, 06, 07 & 09.
-// https://docs.fatzebra.com/docs/3d-secure
-// Cardinal returns ECI(or SLI for MC) in the range of 01~07
-// https://cardinaldocs.atlassian.net/wiki/spaces/CCen/pages/903577725/EMV+3DS+2.0+Test+Cases
-const eciMappings: { vendorEci: string, fatzebraSli: string }[] = [
-  {
-    // Cards: Mastercard, CB Mastercard
-    // Test Case 2: Failed Frictionless Authentication
-    // Test Case 4: Unavailable Frictionless Authentication from the Issuer
-    // Test Case 5: Rejected Frictionless Authentication by the Issuer
-    // Test Case 6: Authentication Not Available on Lookup
-    // Test Case 7: Error on Lookup
-    // Test Case 9: Bypassed Authentication
-    // Test Case 11: Failed Step Up Authentication
-    // Test Case 12: Step Up Authentication is Unavailable
-    // Test Case 13: Error on Authentication
-    vendorEci: '00',
-    // Non-authenticated transaction - issuer not support. CAVV not present.
-    fatzebraSli: '07',
-  },
-  {
-    // Cards: Mastercard, CB Mastercard
-    // Test Case 3: Attempts Stand-In Frictionless Authentication
-    vendorEci: '01',
-    // Cards: Visa, American Express, Discover (Diners Club), CB Visa, ELO
-    // Secure, Non-authenticated transaction (XID present, CAVV not present)
-    fatzebraSli: '06',
-  },
-  {
-    // Cards: Mastercard, CB Mastercard
-    // Test Case 1: Successful Frictionless Authentication
-    // Test Case 10: Successful Step Up Authentication
-    vendorEci: '02',
-    // Cards: Visa, American Express, Discover (Diners Club), CB Visa, ELO
-    // Secure, Authenticated transaction with XID and CAVV present
-    fatzebraSli: '05',
-  },
-  {
-    vendorEci: '05',
-    // Secure, Authenticated transaction with XID and CAVV present
-    fatzebraSli: '05',
-  },
-  {
-    vendorEci: '06',
-    // Secure, Non-authenticated transaction (XID present, CAVV not present)
-    fatzebraSli: '06',
-  },
-  {
-    vendorEci: '07',
-    // Secure, Non-authenticated transaction (XID and CAVV not present). This is the default value.
-    fatzebraSli: '07',
-  },
-]
-
-const toFzSli = (vendorEci: string): string => {
-  const matched = eciMappings.find((item) => item.vendorEci == vendorEci)
-  return matched ? matched.fatzebraSli : vendorEci
-}
-
-export {
-  eciMappings,
-  toFzSli,
-}

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 {
-  EnrollmentScenario,
-  enrollmentScenarios
-}

package/src/sca/scenarios/index.ts

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