@fat-zebra/sdk 1.0.0

package/src/sca/scenarios/validation.ts

@@ -0,0 +1,142 @@
+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 {
+  ValidationScenario,
+  validationScenarios
+}

package/src/sca/types.ts

@@ -0,0 +1,206 @@
+enum ScaErrorCode {
+  BYPASSED_AUTHENTICATION = '001',
+  AUTHENTICATION_NOT_AVAILABLE_ON_LOOKUP = '002',
+  UNAVAILABLE_FRICTIONLESS_AUTHENTICATION = '003',
+  UNSUCCESSFUL_FRICTIONLESS_AUTHENTICATION = '004',
+  REJECTED_FRICTIONLESS_AUTHENTICATION = '005',
+  UNSUCCESSFUL_STEPUP_AUTHENTICATION = '006',
+  UNAVAILABLE_STEPUP_AUTHENTICATION = '007'
+}
+
+enum ChallengeWindowSize {
+  SIZE_250X400 = '01',
+  SIZE_390X400 = '02',
+  SIZE_500X600 = '03',
+  SIZE_600X400 = '04',
+  SIZE_FULL_PAGE = '05',
+}
+
+interface CreateSCASessionRequest {
+  amount: number
+  currency: string
+  hide_card_holder: boolean;
+}
+
+interface CreateSCASessionResponse {
+  jwt: string
+}
+
+interface ThreedsData {
+  cavv: string
+  par: string
+  sli: string
+  xid: string
+  ver: string
+  directoryServerTxnId: string
+  threedsVersion: string
+}
+
+
+interface EnrollSCARequest {
+  amount: number
+  card_token: string
+  currency: string
+  reference: string
+  verification: string
+  session_id: string
+  challenge_window_size: ChallengeWindowSize
+  hide_card_holder: boolean
+  customer?: {
+    first_name?: string
+    last_name?: string
+    email?: string
+    address?: string
+    city?: string
+    postcode?: string
+    state?: string
+    country?: string
+  }
+}
+
+interface EnrollSCAResponse {
+  aav: string
+  acs_url: string
+  action: {
+    proceed: boolean
+    challenge: boolean
+    frictionless: boolean
+    bypass: boolean
+  }
+  authentication_path: string
+  authentication_result: string
+  authentication_status_message: string
+  authentication_transaction_id: string
+  card_bin: string
+  card_type_name: string
+  cavv: string
+  // payerAuthEnrollReply_commerceIndicator
+  // Commerce indicator for cards not enrolled.
+  commerce_indicator: CommerceIndicator
+  currency: string
+  decision: 'ACCEPT' | 'REJECT' | 'ERROR'
+  directory_server_txn_id: string
+  eci: string
+  // payerAuthEnrollReply_veresEnrolled
+  // Result of the enrollment check for Asia, Middle East and Africa gateway
+  enrolled: VEResEnrolled
+  pareq: string
+  pares: PARes
+  proxy_pan: string
+  reason_code: string
+  request_id: string
+  request_token: string
+  ucaf_collection_indicator: string
+  version: string // 3DS version
+  xid: string
+}
+
+enum CommerceIndicator {
+  // Card not enrolled, or card type not supported by payer authentication. No liability shift.
+  INTERNET = 'internet',
+  // JCB card not enrolled, but attempt to authenticate is recorded. Liability shift.
+  JS_ATTEMPTED = 'js_attempted',
+  // You receive this result if JCB’s directory service is not available. No liability shift.
+  JS_FAILURE = 'js_failure',
+  // Mastercard card not enrolled. No liability shift.
+  SPA = 'spa',
+  // Visa card not enrolled, but attempt to authenticate is recorded. Liability shift.
+  VBV_ATTEMPTED = 'vbv_attempted',
+  // For the payment processors Barclays, Streamline, AIBMS, or FDC Germany, you receive this result if Visa’s directory service is not available. No liability shift.
+  VBV_FAILURE = 'vbv_failure'
+}
+
+enum VEResEnrolled {
+  // Card enrolled. You must authenticate. Liability shift.
+  ENROLLED = 'Y',
+  // Card not enrolled. Proceed with authorization
+  NOT_ENROLLED = 'N',
+  // Enable to authenticate regardless of the reason. No liability shift.
+  UNABLE = 'U',
+  // Authentication was bypassed
+  BYPASSED = 'B'
+}
+
+enum PARes {
+  ATTEMPTED = 'A',
+  BYPASSED = 'B',
+  CANCELED = 'N',
+  REJECTED = 'R',
+  NOT_COMPLETED = 'U',
+  SUCCESS = 'Y'
+}
+
+interface ValidateSCARequest {
+  amount: number
+  authentication_transaction_id: string
+  card_token: string
+  currency: string
+  pareq: string
+  reference: string
+}
+
+interface ValidateSCAResponse {
+  aav: string
+  acs_url: string
+  authentication_result: string
+  card_bin: string
+  cavv: string
+  commerce_indicator: CommerceIndicator
+  decision: 'ACCEPT' | 'REJECT' | 'ERROR'
+  directory_server_txn_id: string
+  eci: string
+  enrolled: VEResEnrolled
+  pareq: string
+  pares: PARes
+  reason_code: string
+  request_id: string
+  request_token: string
+  ucaf_collection_indicator: string
+  xid: string
+  version: string // 3DS version
+}
+
+interface DecodeSCASessionRequest {
+  token: string
+}
+
+interface DecodeSCASessionResponse {
+  amount: number
+  currency_code: string
+  processor_transaction_id: string
+  consumer_session_id: string
+  reference_id: string
+  type: string
+  action_code: string
+  error_number: number
+  error_description: string
+  errors: string[]
+  test: boolean
+}
+
+interface GetCardRequest {
+  card_token: string
+}
+
+interface GetCardResponse {
+  bin: string
+}
+
+export {
+  ScaErrorCode,
+  ChallengeWindowSize,
+  CreateSCASessionRequest,
+  CreateSCASessionResponse,
+  EnrollSCARequest,
+  EnrollSCAResponse,
+  CommerceIndicator,
+  VEResEnrolled,
+  PARes,
+  ValidateSCARequest,
+  ValidateSCAResponse,
+  DecodeSCASessionRequest,
+  DecodeSCASessionResponse,
+  GetCardRequest,
+  GetCardResponse,
+  ThreedsData,
+}

package/src/shared/api-gateway-client.ts

@@ -0,0 +1,71 @@
+import {
+  RequestHeaderSdkVersion,
+  RequestHeaderMerchantUsername,
+  RequestTimeout,
+  LongRequestTimeout,
+} from "./constants";
+import axios, { AxiosResponse, AxiosInstance } from "axios";
+import { getSdkVersionNumber } from "./util";
+
+const baseUrl = process.env.API_GATEWAY_URL;
+
+import * as sca from "../sca/types";
+
+export type GatewayClientProps = {
+  accessToken: string;
+  username: string;
+}
+
+class GatewayClient {
+  client: AxiosInstance | null;
+
+  constructor({ accessToken, username }: GatewayClientProps) {
+    const headers: { [key: string]: string } = {};
+    headers["Authorization"] = `Bearer ${accessToken}`;
+    headers[RequestHeaderSdkVersion] = getSdkVersionNumber();
+    headers[RequestHeaderMerchantUsername] = username;
+
+    this.client = axios.create({
+      baseURL: baseUrl,
+      timeout: RequestTimeout,
+      headers,
+      responseType: "json",
+      transformResponse: [
+        function (response) {
+          const _response =
+            typeof response === "string" ? JSON.parse(response) : response;
+          return _response.data;
+        },
+      ],
+    });
+  }
+
+  /**************** SCA/3DS2 /****************/
+
+  async createSCASession(
+    data: sca.CreateSCASessionRequest
+  ): Promise<AxiosResponse> {
+    return this.client.post("/sca/session", data);
+  }
+
+  async decodeSCASession(
+    data: sca.DecodeSCASessionRequest
+  ): Promise<AxiosResponse> {
+    // return requestBase(`${baseUrl}/sca/decode_session`, 'POST', data)
+    return this.client.post("/sca/decode_session", data);
+  }
+
+  async enrolSCA(data: sca.EnrollSCARequest): Promise<AxiosResponse> {
+    return this.client.post("/sca/enrollment", data);
+  }
+
+  async validateSCA(data: sca.ValidateSCARequest): Promise<AxiosResponse> {
+    return this.client.post("/sca/validation", data);
+  }
+
+  async getCard(data: sca.GetCardRequest): Promise<AxiosResponse> {
+    return this.client.get(`/credit_cards/${data.card_token}`);
+  }
+}
+
+export default GatewayClient;

package/src/shared/bridge-client.ts

@@ -0,0 +1,26 @@
+const headlessIframeId = 'fz-hl'
+
+const load = (url: string): HTMLIFrameElement => {
+  const existing = document.getElementById(headlessIframeId)
+
+  if (existing) {
+    return existing as HTMLIFrameElement
+  }
+
+  const headless = document.createElement('iframe')
+  headless.style.visibility = 'hidden'
+  headless.style.position = 'absolute'
+  headless.style.left = '0px'
+  headless.style.top = '0px'
+  headless.style.height = '0px'
+  headless.style.width = '0px'
+  headless.style.border = 'none'
+  headless.setAttribute('src', url)
+  headless.setAttribute('id', headlessIframeId)
+  document.body.appendChild(headless)
+  return headless
+}
+
+export {
+  load
+}

package/src/shared/constants.ts

@@ -0,0 +1,19 @@
+// Local storage key naming convension:
+// Hypen-separated string with all letters in lower case.
+const LocalStorageAccessTokenKey = 'fz-access-token'
+
+// Request header naming convension:
+// Hyphen-separated string with capitalised 1st letter. Capitalise acronyms
+// See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers
+const RequestHeaderSdkVersion = 'fz-sdk-version'
+const RequestHeaderMerchantUsername = 'fz-merchant-username'
+const RequestTimeout = 8000 // ms
+const LongRequestTimeout = 15000 // ms
+
+export {
+  LocalStorageAccessTokenKey,
+  RequestHeaderSdkVersion,
+  RequestHeaderMerchantUsername,
+  RequestTimeout,
+  LongRequestTimeout
+}

package/src/shared/event-manager.ts

@@ -0,0 +1,44 @@
+import { PublicEvent } from "./types";
+
+interface EventData {
+  detail: { data: any; message?: string } | { errors: string[] };
+}
+
+interface SuccessEventDetail {
+  message: string;
+  data: any;
+}
+
+interface ErrorEventDetail {
+  errors: string[];
+  data: any;
+}
+
+interface SuccessEventDetail {
+  message: string;
+  data: any;
+}
+
+interface ErrorEventDetail {
+  errors: string[];
+  data: any;
+}
+
+// TODO: CustomEvent requires polyfill for IE.
+const emit = (
+  event: PublicEvent,
+  data: SuccessEventDetail | ErrorEventDetail,
+  target: HTMLElement | Window = window,
+): void => {
+  target.dispatchEvent(new CustomEvent(event, { detail: data }));
+};
+
+const on = (
+  event: PublicEvent,
+  callback: (e: any) => void,
+  target: HTMLElement | Window = window,
+): void => {
+  target.addEventListener(event, callback);
+};
+
+export { EventData, emit, on };

package/src/shared/post-message-client.test.ts

@@ -0,0 +1,73 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import {
+  PostMessage,
+  PostMessageLegacy,
+  PostMessageClient
+} from '../../src/shared/post-message-client'
+
+describe('PostMessageClient', () => {
+
+  describe('#setEventListeners', () => {
+    const message: PostMessage = {
+      channel: 'sca',
+      subject: 'test_subject',
+      data: {
+        action: 'transaction.complete'
+      }
+    }
+
+    it('selects the correct handler ', (done) => {
+      const document = window.document;
+      const iframe = document.createElement('iframe');
+      const handler = (data: any) => {
+        expect(data.action).toEqual('transaction.complete')
+        done();
+      };
+
+      document.body.appendChild(iframe);
+
+      const client = new PostMessageClient({
+        channel: 'sca'
+      })
+
+      client.setEventListeners({
+        'test_subject': handler
+      })
+
+      window.postMessage(message, '*')
+    })
+  })
+
+  describe('#setEventListenersLegacy', () => {
+    const message: PostMessageLegacy = {
+      message: 'transaction.complete',
+      data: {
+        action: 'transaction.complete'
+      }
+    }
+
+    it('selects the correct handler ', (done) => {
+      const document = window.document;
+      const iframe = document.createElement('iframe');
+      const handler = (data: any) => {
+        expect(data.action).toEqual('transaction.complete')
+        done();
+      };
+
+      document.body.appendChild(iframe);
+
+      const client = new PostMessageClient({
+        channel: 'sca'
+      })
+
+      client.setEventListenersLegacy({
+        'transaction.complete': handler
+      })
+
+      window.postMessage(message, '*')
+    })
+  })
+})

package/src/shared/post-message-client.ts

@@ -0,0 +1,125 @@
+import { NODE_ENV } from '../shared/types'
+
+interface PostMessage {
+  channel: string // appplepay, sca
+  subject: string // create payment, tokenize card, etc
+  data: unknown
+}
+
+interface PostMessageLegacy {
+  message: string // similar to subject above
+  data: {
+    [key: string]: string | boolean
+  }
+}
+
+interface PostMessageClientConfig {
+  channel: string
+  target?: HTMLIFrameElement
+}
+
+interface EventHandlers {
+  [key: string]: (data: any) => void
+}
+
+interface CreateCardTokenPostMessageData {
+  access_token: string,
+  card_holder: string,
+  card_number: string,
+  card_expiry: string,
+  cvv: string,
+}
+
+interface CreatePurchasePostMessageData {
+  access_token: string,
+  amount: number,
+  card_token: string,
+  currency: string,
+  extra?: { [key: string]: boolean | string },
+  hash: string,
+  invoice: string,
+  test?: boolean,
+}
+
+const domain = process.env.PAYNOW_BASE_URL
+
+// NODE_ENV is introduced to PostMessageClient purely for the purpose of bypassing security
+// check on the postMessage event between parent and child frames. Unforunately there is
+// no workaround to override event origin due to lack of support in existing test framework.
+
+class PostMessageClient {
+  private channel: string
+  private fzEnv: NODE_ENV | undefined
+  private target: HTMLIFrameElement
+
+  constructor(config: PostMessageClientConfig) {
+    this.channel = config.channel
+    this.fzEnv = process.env.NODE_ENV as NODE_ENV
+    this.target = config.target
+  }
+
+  // Handle event messages that conform to PostMessage format.
+  setEventListeners(handlers: EventHandlers): void {
+    window.addEventListener("message", async(event) => {
+
+      const validationEnabled = ![NODE_ENV.TEST, NODE_ENV.LOCALDEV].includes(this.fzEnv)
+      const isChannelValid = event.data.channel === this.channel
+      const isOriginValid = event.origin === domain
+
+      if (validationEnabled && (!isOriginValid || !isChannelValid)) {
+        console.log('[WARNING] unmatched event origin or incorrect message channel')
+        return
+      }
+
+      const message = event.data as PostMessage
+      const subject = message.subject
+      const handler = handlers[subject]
+
+      if (handler) {
+        handler(message.data)
+      } else {
+        // Do not throw error here as it is possible that the parent frame chooses
+        // not to handle certain messages posted from child frame.
+        console.log(`[WARNING] No handler registered for subject ${subject}, message ${JSON.stringify(message)}`)
+      }
+    })
+  }
+
+  // Handle event messages that do not conform to PostMessage format.
+  setEventListenersLegacy(handlers: EventHandlers):void {
+    window.addEventListener("message", (event) => {
+
+      const validationEnabled = ![NODE_ENV.TEST, NODE_ENV.LOCALDEV].includes(this.fzEnv)
+      const isOriginValid = event.origin === domain
+
+      if (validationEnabled && !isOriginValid) {
+        console.log('[WARNING] unmatched event origin or incorrect message channel')
+        return
+      }
+
+      const message = event.data as PostMessageLegacy
+      const handler = handlers[message.message]
+
+      if (handler) {
+        handler(message.data)
+      } else {
+        // Do not throw error here as it is possible that the parent frame chooses
+        // not to handle certain messages posted from child frame.
+        console.log(`[WARNING] no handler registered for message ${message.message}`)
+      }
+    })
+  }
+
+  send(message: PostMessage | PostMessageLegacy): void {
+    this.target.contentWindow.postMessage(message, domain)
+  }
+}
+
+export {
+  CreateCardTokenPostMessageData,
+  CreatePurchasePostMessageData,
+  PostMessage,
+  PostMessageLegacy,
+  PostMessageClient,
+  PostMessageClientConfig,
+}