@fat-zebra/sdk 1.0.0

package/src/react/useFatZebra.ts

@@ -0,0 +1,154 @@
+import { useEffect, useMemo } from "react";
+import * as FatZebra from "../shared/types"
+import { generatePaymentURL } from "./url";
+import Sca from "../sca"
+import GatewayClient from "../shared/api-gateway-client";
+
+
+interface SuccessEventDetail {
+  message: string;
+  data: any;
+}
+
+interface ErrorEventDetail {
+  errors: string[];
+  data: any;
+}
+
+type UseFatZebraProps = {
+  username: string,
+  handlers: FatZebra.Handlers,
+  config: FatZebra.VerificationConfig,
+  bridge: React.MutableRefObject<HTMLIFrameElement>,
+}
+
+
+const useFatZebra = ({ username, config, handlers, bridge }: UseFatZebraProps) => {
+  const { options, accessToken, paymentIntent, verification } = config;
+
+  const sca = useMemo(() => {
+    const gatewayClient = new GatewayClient({ accessToken, username })
+    return new Sca({ gatewayClient })
+  }, [config, username])
+
+
+  const emit = (
+    event: FatZebra.PublicEvent,
+    data: SuccessEventDetail | ErrorEventDetail
+  ) => {
+    const handler = handlers[event]
+    if (handler) {
+      handler(new CustomEvent(event, { detail: data }))
+    }
+  };
+
+  const handleCreatePaymentResponse = (data: FatZebra.CreatePaymentResponse) => {
+    const transactionPayload: FatZebra.TransactionPayload = {
+      transactionId: data.transaction_id,
+      responseCode: data.response_code,
+      message: data.message,
+      amount: data.amount,
+      currency: data.currency,
+      reference: data.reference,
+      cardNumber: data.card_number,
+      cardHolder: data.card_holder,
+      cardExpiry: data.card_expiry,
+      cardType: data.card_type,
+      verification: data.v,
+    }
+
+    if (data.errors) {
+      emit(FatZebra.PublicEvent.PAYMENT_ERROR, {
+        message: 'Payment failed.',
+        errors: data.errors,
+        data: transactionPayload,
+      })
+    } else {
+      emit(FatZebra.PublicEvent.PAYMENT_SUCCESS, {
+        message: 'Payment successful.',
+        data: transactionPayload,
+      })
+    }
+  }
+
+  const handleTokenizeCardResponse = (data: FatZebra.TokenizeCardResponse) => {
+    if (data.errors) {
+      emit(FatZebra.PublicEvent.TOKENIZATION_ERROR, {
+        message: "Card tokenization failed.",
+        errors: data.errors,
+        data: null,
+      });
+      return;
+    } else {
+      emit(FatZebra.PublicEvent.TOKENIZATION_SUCCESS, {
+        message: "Card tokenization success.",
+        data: {
+          token: data.token,
+        },
+      });
+    }
+
+    if (options.tokenizeOnly) return
+
+    if (options.enableSca) {
+      sca.run({ paymentIntent, bin: data.bin, cardToken: data.token })
+    }
+  }
+
+  const messageHandler = (event: any) => {
+    if (
+      event.data &&
+      event.data.source &&
+      event.data.source.includes("react-devtools")
+    )
+      return;
+    if (event.data.subject === FatZebra.BridgeEvent.BIN_LOOKUP) return;
+
+    if (event.data.subject === FatZebra.BridgeEvent.FORM_VALIDATION_ERROR) {
+      emit(FatZebra.PublicEvent.FORM_VALIDATION_ERROR, {
+        errors: event.data.data,
+        data: null,
+      });
+      return;
+    }
+
+    if (event.data.subject === FatZebra.BridgeEvent.FORM_VALIDATION_SUCCESS) {
+      emit(FatZebra.PublicEvent.FORM_VALIDATION_SUCCESS, {
+        errors: event.data.data,
+        data: null,
+      });
+      return;
+    }
+
+    if (event.data.subject === FatZebra.BridgeEvent.CREATE_PAYMENT_RESPONSE) {
+      handleCreatePaymentResponse(event.data.data)
+    }
+
+    if (event.data.subject === FatZebra.BridgeEvent.TOKENIZE_CARD_RESPONSE) {
+      handleTokenizeCardResponse(event.data.data)
+    }
+  };
+
+  useEffect(() => {
+    window.addEventListener("message", messageHandler);
+
+    return () => {
+      window.removeEventListener("message", messageHandler);
+    };
+  }, []);
+
+  const payment = paymentIntent.payment
+
+  const url = generatePaymentURL({
+    ...options,
+    merchant: username,
+    reference: payment.reference,
+    amount: payment.amount,
+    currency: payment.currency,
+    hash: verification,
+  })
+
+  return { url }
+};
+
+export default useFatZebra;

package/src/sca/__tests__/eci-mappings.test.ts

@@ -0,0 +1,35 @@
+import { eciMappings, toFzSli } from '../eci-mappings'
+
+describe ('toFzSli', () => {
+  describe ('ECI mapping exists', () => {
+    it ('sli mapping => cardinal: 00, fz: 07', () => {
+      expect(toFzSli('00')).toEqual('07')
+    })
+
+    it ('sli mapping => cardinal: 01, fz: 06', () => {
+      expect(toFzSli('01')).toEqual('06')
+    })
+
+    it ('sli mapping => cardinal: 02, fz: 05', () => {
+      expect(toFzSli('02')).toEqual('05')
+    })
+
+    it ('sli mapping => cardinal: 05, fz: 05', () => {
+      expect(toFzSli('05')).toEqual('05')
+    })
+
+    it ('sli mapping => cardinal: 06, fz: 06', () => {
+      expect(toFzSli('06')).toEqual('06')
+    })
+
+    it ('sli mapping => cardinal: 07, fz: 07', () => {
+      expect(toFzSli('07')).toEqual('07')
+    })
+  })
+
+  describe ('ECI mapping does not exist', () => {
+    it ('sli mapping => cardinal: 09, fz: 09', () => {
+      expect(toFzSli('09')).toEqual('09')
+    })
+  })
+})

package/src/sca/__tests__/index.test.ts

@@ -0,0 +1,514 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import Sca, { ScaConfig, ScaRunProps } from '..'
+import {
+  Customer,
+  PaymentIntent,
+  PublicEvent,
+} from '../../shared/types'
+import { LocalStorageAccessTokenKey } from '../../shared/constants'
+import { mockRequest } from '../../../tests/helpers/api-gateway-mock'
+import * as nock from 'nock'
+import { CardinalManager } from '../cardinal'
+import { ChallengeWindowSize, EnrollSCARequest, ThreedsData } from '../types'
+import {
+  enrollmentScenarios,
+  EnrollmentScenario,
+} from '../scenarios'
+import GatewayClient from '../../shared/api-gateway-client'
+
+jest.mock('../cardinal')
+// mock module function
+const eventManager = require('../../shared/event-manager')
+eventManager.emit = jest.fn()
+
+interface ResponseOverride {
+  status: number
+  body: unknown
+}
+
+const mockCardinalManager = () => {
+  // @ts-ignore
+  CardinalManager.mockImplementation(() => {
+    return {
+      processBin: () => ['success'],
+      setup: () => true,
+      onPaymentSetupComplete: () => {
+        return {
+          sessionId: 'session_123'
+        }
+      },
+      onPaymentValidated: () => true,
+      continue: () => jest.fn()
+    }
+  })
+}
+
+const gatewayClient = new GatewayClient({
+  accessToken: "abc1234",
+  username: "TEST"
+})
+
+const scaTests = (config: ScaRunProps) => {
+  const { paymentIntent, cardToken, customer } = config
+
+  const requestCustomer = (customer: ScaRunProps['customer']): EnrollSCARequest['customer'] => {
+    let properties: EnrollSCARequest['customer'] = {};
+    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
+  }
+
+  const enrollmentRequestBody: EnrollSCARequest = {
+    amount: paymentIntent.payment.amount,
+    card_token: cardToken,
+    currency: paymentIntent.payment.currency,
+    reference: paymentIntent.payment.reference,
+    hide_card_holder: paymentIntent.payment.hide_card_holder,
+    verification: paymentIntent.verification,
+    session_id: 'session_123',
+    challenge_window_size: ChallengeWindowSize.SIZE_FULL_PAGE,
+    customer: requestCustomer(customer),
+  }
+
+  const mockCreateSCASessionSuccess = () => {
+    mockRequest({
+      request: {
+        action: 'POST',
+        path: '/sca/session',
+        body: {
+          amount: paymentIntent.payment.amount,
+          currency: paymentIntent.payment.currency,
+          hide_card_holder: paymentIntent.payment.hide_card_holder,
+        }
+      },
+      response: {
+        status: 200,
+        body: {
+          data: {
+            jwt: 'thisisajwt'
+          }
+        }
+      }
+    })
+  }
+
+  const mockSCASession = (override?: ResponseOverride) => {
+    const responseBody = {
+      data: {
+        jwt: 'thisisajwt'
+      }
+    }
+
+    mockRequest({
+      request: {
+        action: 'POST',
+        path: '/sca/session',
+        body: {
+          amount: paymentIntent.payment.amount,
+          currency: paymentIntent.payment.currency,
+          hide_card_holder: paymentIntent.payment.hide_card_holder,
+        }
+      },
+      response: {
+        status: (override ? override.status : 200),
+        body: (override ? override.body : responseBody)
+      }
+    })
+  }
+
+  const mockSCAEnrollment = (override?: ResponseOverride) => {
+    const responseBody = {
+      data: {
+        action: {
+          proceed: true
+        },
+        version: '1.0',
+        enrolled: 'Y',
+        acs_url: '',
+        pareq: 'asdfasdf',
+        pares: '',
+        decision: 'ACCEPT',
+      }
+    }
+
+    mockRequest({
+      request: {
+        action: 'POST',
+        path: '/sca/enrollment',
+        body: enrollmentRequestBody
+      },
+      response: {
+        status: (override ? override.status : 200),
+        body: (override ? override.body : responseBody)
+      }
+    })
+  }
+
+  describe('SCA session failed', () => {
+    it('Emits fz.validation.error event with detail', async () => {
+
+      mockRequest({
+        request: {
+          action: 'POST',
+          path: '/sca/session',
+          body: {
+            amount: paymentIntent.payment.amount,
+            currency: paymentIntent.payment.currency,
+            hide_card_holder: paymentIntent.payment.hide_card_holder,
+          }
+        },
+        response: {
+          status: 422,
+          body: {
+            errors: ['Create SCA session error.']
+          }
+        }
+      })
+
+      mockSCAEnrollment()
+
+      const sca = new Sca({ gatewayClient })
+
+      await sca.run(config)
+
+      const eventDetail: any = {
+        detail: {
+          errors: ['FatZebra.3DS: JWT creation failed.'],
+          data: null
+        }
+      }
+      expect(eventManager.emit).toHaveBeenCalledTimes(1)
+      expect(eventManager.emit.mock.calls[0][0]).toBe(PublicEvent.SCA_ERROR)
+      expect(eventManager.emit.mock.calls[0][1]).toMatchObject(eventDetail.detail)
+    })
+  })
+
+  describe('Bin processing failed', () => {
+    it('Emits fz.validation.error event without detail', async () => {
+      //@ts-ignore
+      CardinalManager.mockImplementation(() => {
+        return {
+          processBin: () => {
+            throw new Error('GG')
+          },
+          setup: () => true,
+          onPaymentSetupComplete: () => {
+            return {
+              sessionId: '123'
+            }
+          },
+          onPaymentValidated: () => true
+        }
+      })
+
+      mockCreateSCASessionSuccess()
+      mockSCAEnrollment()
+
+      const sca = new Sca({ gatewayClient })
+      sca.cardinal = new CardinalManager()
+      await sca.run(config)
+
+      const eventDetail: any = {
+        detail: {
+          errors: ['FatZebra.3DS: BIN verification failed.'],
+          data: null
+        }
+      }
+
+      expect(eventManager.emit).toHaveBeenCalledTimes(1)
+      expect(eventManager.emit.mock.calls[0][0]).toBe(PublicEvent.SCA_ERROR)
+      expect(eventManager.emit.mock.calls[0][1]).toMatchObject(eventDetail.detail)
+    })
+  })
+
+  describe('3DS version 2', () => {
+    const scenarios = enrollmentScenarios.filter((item) => item.threedsVersion[0] == '2')
+
+    scenarios.forEach((scenario: EnrollmentScenario) => {
+      describe(`Enrollment: ${scenario.description}`, () => {
+        beforeEach(() => {
+          mockCardinalManager()
+          mockSCASession()
+          mockSCAEnrollment({
+            status: 200,
+            body: {
+              data: {
+                version: '2.1.0',
+                cavv: 'cavv',
+                eci: '05',
+                xid: 'xid',
+                pareq: 'pareq',
+                pares: scenario.pares,
+                enrolled: scenario.veresEnrolled,
+                reason_code: scenario.reasonCode,
+                directory_server_txn_id: 'txn123',
+                ucaf_collection_indicator: 'ucaf123',
+              }
+            }
+          })
+        })
+
+        it('SCA', async () => {
+          const sca = new Sca({ gatewayClient})
+          sca.cardinal = new CardinalManager()
+          const spy = jest.spyOn(sca.cardinal, 'continue')
+
+          await sca.run(config)
+
+          if (scenario.outcome.authenticationType === 'challenge') {
+            expect(spy).toHaveBeenCalledTimes(1)
+            expect(eventManager.emit).toHaveBeenCalledTimes(0)
+            return
+          }
+
+          if (scenario.outcome.success) {
+            const eventDetail = {
+              detail: {
+                message: `FatZebra.3DS: 3DS success - ${scenario.description}.`,
+                data: {
+                  cavv: 'cavv',
+                  par: scenario.pares,
+                  sli: '05',
+                  xid: 'xid',
+                  ver: 'Y',
+                  threedsVersion: '2.1.0',
+                  directoryServerTxnId: 'txn123',
+                } as ThreedsData,
+              }
+            }
+            expect(eventManager.emit).toHaveBeenCalledTimes(1)
+            expect(eventManager.emit.mock.calls[0][0]).toBe(PublicEvent.SCA_SUCCESS)
+            expect(eventManager.emit.mock.calls[0][1]).toMatchObject(eventDetail.detail)
+          } else {
+            const eventDetail = {
+              detail: {
+                errors: [`FatZebra.3DS: 3DS error - ${scenario.description}`],
+                data: {
+                  errorCode: scenario.outcome.errorCode
+                },
+              }
+            }
+            expect(eventManager.emit).toHaveBeenCalledTimes(1)
+            expect(eventManager.emit.mock.calls[0][0]).toBe(PublicEvent.SCA_ERROR)
+            expect(eventManager.emit.mock.calls[0][1]).toMatchObject(eventDetail.detail)
+          }
+        })
+      })
+    })
+  })
+
+  describe('3DS version 1', () => {
+    const scenarios = enrollmentScenarios.filter((item) => item.threedsVersion[0] == '1')
+
+    scenarios.forEach((scenario: EnrollmentScenario) => {
+      describe(`Enrollment: ${scenario.description}`, () => {
+        beforeEach(() => {
+          mockCardinalManager()
+          mockSCASession()
+          mockSCAEnrollment({
+            status: 200,
+            body: {
+              data: {
+                version: '1.0.2',
+                cavv: 'cavv',
+                eci: '05',
+                xid: 'xid',
+                pareq: 'pareq',
+                pares: scenario.pares,
+                enrolled: scenario.veresEnrolled,
+                reason_code: scenario.reasonCode,
+                directory_server_txn_id: 'txn123',
+                ucaf_collection_indicator: 'ucaf123',
+              }
+            }
+          })
+        })
+
+        it('SCA', async () => {
+          const sca = new Sca({ gatewayClient })
+          sca.cardinal = new CardinalManager()
+          const spy = jest.spyOn(sca.cardinal, 'continue')
+
+          await sca.run(config)
+
+          if (scenario.outcome.authenticationType === 'challenge') {
+            expect(spy).toHaveBeenCalledTimes(1)
+            expect(eventManager.emit).toHaveBeenCalledTimes(0)
+            return
+          }
+
+          if (scenario.outcome.success) {
+            const eventDetail = {
+              detail: {
+                message: `FatZebra.3DS: 3DS success - ${scenario.description}.`,
+                data: {
+                  cavv: 'cavv',
+                  par: scenario.pares,
+                  sli: '05',
+                  xid: 'xid',
+                  ver: scenario.veresEnrolled,
+                  threedsVersion: '1.0.2',
+                  directoryServerTxnId: 'txn123',
+                } as ThreedsData,
+              }
+            }
+            expect(eventManager.emit).toHaveBeenCalledTimes(1)
+            expect(eventManager.emit.mock.calls[0][0]).toBe(PublicEvent.SCA_SUCCESS)
+            expect(eventManager.emit.mock.calls[0][1]).toMatchObject(eventDetail.detail)
+          } else {
+            const eventDetail = {
+              detail: {
+                errors: [`FatZebra.3DS: 3DS error - ${scenario.description}`],
+                data: {
+                  errorCode: scenario.outcome.errorCode
+                },
+              }
+            }
+            expect(eventManager.emit).toHaveBeenCalledTimes(1)
+            expect(eventManager.emit.mock.calls[0][0]).toBe(PublicEvent.SCA_ERROR)
+            expect(eventManager.emit.mock.calls[0][1]).toMatchObject(eventDetail.detail)
+          }
+        })
+      })
+    })
+  })
+}
+
+describe('Sca', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+    nock.disableNetConnect()
+    nock.cleanAll()
+
+    mockCardinalManager()
+
+    localStorage.setItem(LocalStorageAccessTokenKey, 'TOKEN')
+  })
+
+  const bin = '400000'
+  const cardToken = 'token_12345'
+  const paymentIntent: PaymentIntent = {
+    payment: {
+      amount: 1000,
+      currency: 'AUD',
+      reference: 'ref_12345',
+      hide_card_holder: false,
+    },
+    verification: 'ver_12345'
+  }
+
+  describe('#run', () => {
+    describe('customer details: full', () => {
+      const customer: Customer = {
+        firstName: 'Ziggy',
+        lastName: 'Zebra',
+        email: 'ziggy.zebra@fatzebra.com',
+        address: '2/58-62 Kippax Street',
+        city: 'Surry Hills',
+        postcode: '2010',
+        state: 'NSW',
+        country: 'Australia'
+      }
+      const config = {
+        bin,
+        cardToken,
+        customer,
+        paymentIntent,
+      }
+
+      scaTests(config)
+    })
+
+    describe('customer details: partial', () => {
+      const customer: Customer = {
+        firstName: 'Ziggy',
+        lastName: '',
+        email: 'ziggy.zebra@fatzebra.com',
+        address: null,
+        city: undefined,
+        postcode: '',
+      }
+
+      const config = {
+        bin,
+        cardToken,
+        customer,
+        paymentIntent,
+      }
+
+      scaTests(config)
+    })
+
+    describe('customer details: empty', () => {
+      const customer: Customer = {}
+
+      const config = {
+        bin,
+        cardToken,
+        customer,
+        paymentIntent,
+      }
+
+      scaTests(config)
+    })
+
+    describe('no customer', () => {
+      const config = {
+        bin,
+        cardToken,
+        paymentIntent,
+      }
+
+      scaTests(config)
+    })
+  })
+
+  describe('#customerProperties', () => {
+    const sca = new Sca({ gatewayClient })
+
+    it('formats the property keys into snake_case', () => {
+      const customer: Customer = {
+        firstName: 'Ziggy',
+        lastName: 'Zebra',
+      }
+
+      const expectedProperties = {
+        first_name: 'Ziggy',
+        last_name: 'Zebra',
+      }
+
+      expect(sca.customerProperties(customer)).toEqual(expectedProperties)
+    })
+
+    it('only retains non-empty customer properties', () => {
+      const customer: Customer = {
+        firstName: 'Ziggy',
+        lastName: 'Zebra',
+        email: 'ziggy.zebra@fatzebra.com',
+        address: null,
+        city: null,
+        postcode: undefined,
+        state: undefined,
+        country: ''
+      }
+
+      const expectedProperties = {
+        first_name: 'Ziggy',
+        last_name: 'Zebra',
+        email: 'ziggy.zebra@fatzebra.com',
+      }
+
+      expect(sca.customerProperties(customer)).toEqual(expectedProperties)
+    })
+  })
+})