@xfers/xfers-js-sdk NPM

Web SDK Table of content

Web SDK Table of content
Getting Started
- 1. Through CDN & \ Tag [Deprecated]
- 2. Through npm package
Types of Xfers Web UI SDK
- Xfers.Connect
  - Frontend Integration
- Xfers.Components
  - Verification
    - 1. startVerificationFlow
  - Transaction
Change Logs

Getting Started

Download and install the Xfers Web SDK either through Content Delivery Network (CDN) or via npm install

1. Through CDN & \ Tag Deprecated

Add the following lines into the corresponding HTML file's <head></head> section:

<!-- The following files can also be downloaded from the js folder in this repository -->
<script src="https://cdn.jsdelivr.net/gh/Xfers/xfers-sdk@d064cdadcbfc309a5661d3c74bfe751fc2f07133/JavaScript/dist/vendors~xfers.bundle.js"></script>
<script src="https://cdn.jsdelivr.net/gh/Xfers/xfers-sdk@d064cdadcbfc309a5661d3c74bfe751fc2f07133/JavaScript/dist/xfers.bundle.js"></script>

Note that the Xfers Web SDK requires a mounting point on a HTML DOM. Add the following line into the same HTML file <body></body> section:

<!-- The ID of the DOM element is to be used to instantiate Web SDK later -->
<!-- Make sure the following line is executed before the instantiation in the next segment -->
<div id="xfers_connect"></div>

Next step, initialize the components by adding the following javascript into the same <body></body> section. This is required on all the pages that uses the Xfers SDK

<script type="text/javascript">
  const connectOptions = {
    test: true,
    /* For Singapore Web SDK, use "sg"
     * country: "sg"
     * For Indonesia Web SDK, use "id"
     * country: "id"
     */
    country: 'sg',
    displayName: 'Merchant A',
    logo: 'http://goldengate.vc/wp-content/uploads/2016/02/xfers-logo.png',
    submitPhoneCallback: res => {
      res.goNext()
    },
    submitOtpCallback: res => {
      res.goNext()
    },
    requestOtpCallback: res => {
      console.log('res', res.phoneNo)
    },
    connectFlowCallback: res => {
      res.exit()
    }
  }

  /* Instantiation takes in two parameters:
   * 1st param => mountingElementId: 'xfers_connect'
   * 2nd param => options: { country, test, displayName, logo, submitPhoneCallback, submitOtpCallback, requestOtpCallback, connectFlowCallback }
   */
  const xfersConnect = new Xfers.Connect('xfers_connect', connectOptions)

  // Next, trigger the SDK flows by executing the following command:
  // Start Xfers Connect Flow
  xfersConnect.startAuthenticationFlow()
</script>

2. Through npm package

Begin by installing the SDK package:

yarn add @xfers/xfers-js-sdk

// Or using npm
npm install @xfers/xfers-js-sdk

Next, import the components into your app:

import { Connect } from '@xfers/xfers-js-sdk'

Next, configure the options for connect flow, you can set sandbox environment, locale, merchant display information and callbacks here:

const connectOptions = {
  test: true,
  /* For Singapore Web SDK, use "sg"
   * country: "sg"
   * For Indonesia Web SDK, use "id"
   * country: "id"
   */
  country: 'sg',
  displayName: 'Merchant A',
  logo: 'http://goldengate.vc/wp-content/uploads/2016/02/xfers-logo.png',
  submitPhoneCallback: res => {
    res.goNext()
  },
  submitOtpCallback: res => {
    res.goNext()
  },
  requestOtpCallback: res => {
    console.log('res', res.phoneNo)
  },
  connectFlowCallback: res => {
    res.exit()
  }
}

Note that the Xfers Web SDK requires a mounting point on a HTML DOM. Add the following line into the same HTML file <body></body> section:

<!-- The ID of the DOM element is to be used to instantiate Web SDK later -->
<!-- Make sure the following line is executed before the instantiation in the next segment -->
<div id="xfers_connect"></div>

Next step, instantiate the component onto a mounting DOM, and after that, trigger the pop-up:

/* Instantiation takes in two parameters:
 * 1st param => mountingElementId: 'xfers_elements'
 * 2nd param => options: { country, test, displayName, logo, submitPhoneCallback, submitOtpCallback, requestOtpCallback, connectFlowCallback }
 */
this.xfersConnect = new Connect('xfers_connect', connectOptions)

// Next step, trigger the SDK flows by executing the following command:
// Start Xfers Connect Flow
this.xfersConnect.startAuthenticationFlow()

Once you see this screen, it means you've successfully integrated the SDK!

Please refer to the next section to understand different parts of SDK.

Types of Xfers Web UI SDK

Due to different security requirements, Xfers Web SDK are categorised into three components, namely Connect and Components.

UI Types	Functionalities	Prerequisites	Integration Area
Connect	Link-up customers to their Xfers Wallet through phone number	Xfers App Token & Secret Token	Frontend & Backend
Components	Verification, Manage Bank, Top-up, Withdrawal, Transactions Overview, Credit Card, Bank Transfer, Withdrawal on Behalf	Xfers User Access Token	Frontend only

NOTE:

The Xfers User Acccess token is a token that is required to initialize Component. The SDK relies on this token to communicate with the Xfers backend. In order to initialize the SDK, you will first need to obtain Xfers User Access Token through Connect.

Xfers.Connect

Xfers Connect is a frontend and backend process which you undertake to obtain an Xfers User Access Token. The frontend process is to collect user phone number and OTP (one time password), and the backend process is to ask Xfers server to send an OTP to user, and verify the OTP. Upon successful verification, you will receive a Xfers User Access Token, which can be saved permanently in a database to identify a user. All users should only go through this process once, to link up their Xfers account.

Frontend Integration

The SDK provides an easy way to integrate the interface for collecting phone number and OTP from the users. If you've followed the Getting Started example, you have already integrated the interface successfully. You should see the following screens as you go through the flow.

The section below explains what each of the option parameter does:

Parameters	Type	Value	Description
country	String	'sg' OR 'id'	To specify the country the SDK is used for
test	String	true OR false	To specify sandbox or production environment. If it is true, the API call will be made to `sandbox.xfers.io`. if it's false, the API call will be made to the production environment - `www.xfers.io`
displayName	String	'Merchant A'	To specify the display name for your company / organization which will be shown in the SDK interface.
logo	String	'http://goldengate.vc/wp-content/uploads/2016/02/xfers-logo.png'	To specify an image that represent your company / organization which will be shown in the interface.
submitPhoneCallback	Function		To specify a callback function when user click on submit button on phone field screen
submitOtpCallback	Function		To specify a callback function when user click on submit button on OTP field screen
requestOtpCallback	Function		To specify a callback function when user click on 'Resend Otp' on OTP field screen. Upon clicking, it will start a 60 sec interval before it is allowed to be clicked again.
connectFlowCallback	Function		To specify a callback function when user click on the progress button on the link-up successful screen

submitPhoneCallback & submitOtpCallback will be triggered when user submit their phone number or OTP on the screen. This is where you make an API call to your backend to engage Xfers backend server to send OTP to users and verify the OTP to retrieve Xfers User Access Token.
requestOtpCallback will be triggered when user click on the 'Resend OTP' link on the screen. You can trigger a new OTP by using the same backend method that handle submitPhoneCallback request.

connectFlowCallback will be triggered when user click on the progress button on link-up successful screen above. If you have the verification documents of the user, this is where you send the information to Xfers. Xfers User Access Token is required to utilise this callback.

submitPhoneCallback

The SDK will feed an object to the callback as a parameter, which contains the following:

Key	Value	Description
phoneNo	eg: "98888888"	Phone number of user.
toggleLoading	function	The function to toggle a loading screen on the SDK.
goNext	function	The function to proceed to next screen on the SDK.
goBack	function	The function to return to previous screen on the SDK.
setErrorMessage	function	The function to set error message on phone screen.

You can control the SDK using the functions and inputs from the above.

submitOtpCallback

The SDK will feed an object to the callback as a parameter, which contains the following:

Key	Value	Description
phoneNo	eg: "98888888"	Phone number of the user.
otp	eg: "512512"	OTP (One-time-password) of the user.
toggleLoading	function	The function to toggle a loading screen on the SDK.
goNext	function	The function to proceed to next screen on the SDK. If you intend to submit user verification information to Xfers, you need to pass user's accessToken to this function as a parameter. Refer to example below.
goBack	function	The function to return to previous screen on the SDK.
setErrorMessage	function	The function to set error message on otp screen.

You can control the SDK using the functions and inputs from the above. For example:

requestOtpCallback

The SDK will feed an object to the callback as a parameter, which contains the following:

Key	Value	Description
phoneNo	eg: "98888888"	Phone number of the user.

You can allow your users to request for new OTP using the same method as submitPhoneCallback. In order to prevent spamming, there is a 60 seconds interval in-between initial and subsequent requests.

connectFlowCallback

The SDK will feed an object to the callback as a parameter, which contains the following:

Key	Value	Description
accountFullyVerified	eg: true or false	This flag indicates if the user is verified with Xfers or not. (Required user accessToken)
exit	function	The function to close the pop-up screen and end the process.
toggleLoading	function	The function to toggle a loading screen on the SDK.
submitKycInformation	function	The function to submit user information to Xfers to kick-start the verification process. Refer to below for all available params. (Required user accessToken)
redirectToVerificationFlow	function	The function to proceed to Xfers verification flow for user to submit verification documents. (Required user accessToken)

<script type="text/javascript">
  const submitPhoneCallback = res => {
    res.toggleLoading()

    const fetchOptions = {
      method: 'POST',
      body: { phoneNo: res.phoneNo }
    }

    // In your backend api, call xfers API (refer to following section) to tell Xfers to send OTP to user
    fetch('https://www.example.com/call/your/backend', fetchOptions).then(() => {
      res.toggleLoading()
      res.goNext()
    })
  }

  const submitOtpCallback = res => {
    res.toggleLoading()

    const fetchOptions = {
      method: 'POST',
      body: { phoneNo: res.phoneNo, otp: res.otp }
    }

    // In your backend api, call xfers API (refer to following section) to verify the OTP user has keyed in and to retrieve the user's api token (which you should then save in your own database).
    fetch('https://www.example.com/call/your/backend', fetchOptions).then(accessToken => {
      res.toggleLoading()

      // Note: If you intend to send user verification information to Xfers, you need to call goNext function with the user accessToken.
      res.goNext(accessToken)
    })
  }

  const requestOtpCallback = res => {
    const fetchOptions = {
      method: 'POST',
      body: { phoneNo: res.phoneNo }
    }

    // In your backend api, call xfers API (refer to following section) to tell Xfers to send OTP to user
    fetch('https://www.example.com/call/your/backend', fetchOptions)
  }

  const connectFlowCallback = res => {
    if (res.accountFullyVerified) {
      res.exit()
    } else {
      res.toggleLoading()

      const userInformation = {
        fullName: 'Chong Chee Meng',
        dateOfBirth: '13/01/1987',
        addressLine1: '#07-100',
        addressLine2: '47 Lorong Ah Keng',
        country: 'Singapore',
        state: '',
        city: '',
        postalCode: '740118',
        identityNo: 'G1007777N',
        nationality: 'Singaporean',
        placeOfBirth: 'SG',
        idFrontUrl: 'http://goldengate.vc/wp-content/uploads/2016/02/xfers-logo.png',
        idBackUrl: 'http://goldengate.vc/wp-content/uploads/2016/02/xfers-logo.png',
        selfie2idUrl: 'http://goldengate.vc/wp-content/uploads/2016/02/xfers-logo.png',
        proofOfAddressUrl: 'http://goldengate.vc/wp-content/uploads/2016/02/xfers-logo.png'
      }
      res.submitKycInformation(userInformation)
    }
  }

  const connectOptions = {
    test: true,
    /* For Singapore Web SDK, use "sg"
     * country: "sg"
     * For Indonesia Web SDK, use "id"
     * country: "id"
     */
    country: 'sg',
    displayName: 'Merchant A',
    logo: 'http://goldengate.vc/wp-content/uploads/2016/02/xfers-logo.png',
    submitPhoneCallback,
    submitOtpCallback,
    requestOtpCallback,
    connectFlowCallback
  }

  const xfersConnect = new Xfers.Connect('xfers_connect', connectOptions)

  // Start Xfers Connect Flow
  xfersConnect.startAuthenticationFlow()
</script>

Backend Integration

You need to complete the backend part by referring to the Xfers API Documentation over here

Xfers.Components

Xfers Components is an entirely frontend process which allows you to provide the ability for users to:

Complete their verification process
Manage their bank accounts
Top-up to their Xfers wallet
Withdraw from their Xfers wallet
View their transaction history
Make payment using credit card
Make payment via bank transfer
Withdraw money from your merchant wallet to your bank account

This SDK requires Xfers User Access Token.

<script type="text/javascript">
  // Paste the Xfers User Access Token here
  const accessToken = 'insert the xfers user access token here upon retrieving it from your server backend'

  /* Instantiation takes in two parameters:
   * 1st param => mountingElementId: 'xfers_elements'
   * 2nd param => accessToken: e.g. - 'YTB7iKVauTzJ8zyk6cJ4ooTOUGJMG-SYDPxFNFTDs4Z'
   * 3rd param => options: { country, test, closeVerifiedNoticeCallback, closePendingVerificationNoticeCallback }
   */
  const componentsOptions = {
    test: true,
    /* For Singapore Web SDK, use "sg"
     * country: "sg"
     * For Indonesia Web SDK, use "id"
     * country: "id"
     */
    country: 'sg',
    closeVerifiedNoticeCallback: () => {
      console.log('verified screen is closed')
    },
    closePendingVerificationNoticeCallback: () => {
      console.log('pending verification screen is closed.')
    }
  }
  const xfersComponents = new Xfers.Components('xfers_elements', accessToken, componentOptions)

  // Next step, trigger the SDK flows by executing the following command:
  xfersComponents.startVerificationFlow()
</script>

Verification

1. startVerificationFlow

// Example:
xfersComponents.startVerificationFlow()

Verification Flow allows merchant to collect necessary KYC information from users and show user's verification status.

For Singapore, users are considered to be fully verified only if their 1) NRIC Front and Back, 2) Selfie with ID, 3) Proof of address are verified by Xfers
There are two methods for user to verify their Xfers account: 1) MyInfo Verification, 2) Manual Verification
MyInfo verification will redirect users to login to their SingPass account and authorise to share verification information to Xfers
Some Xfers features requires users to be verified before they are granted full access.
For Indonesia, users are considered to be fully verified only if their 1) NRIC Front 2) Selfie with ID are verified by Xfers

Transaction

1. startManageBankFlow

// Example:
xfersComponents.startManageBankFlow()

Manage Bank Flow allows merchant to provide users a way to add, edit and delete bank accounts.

All users must have a verified bank account in order to use Xfers wallet.

2. startTopUpFlow

// Example:
xfersComponents.startTopUpFlow()

Top-up Flow allows merchant to provide users a way to credit funds into the Xfers wallet for future use.

It will provide users with a detailed instructions to top-up to Xfers wallet.
It will check if transacting users are KYC-verified. If verification is required, it will guide the user to go through Verification process. If there is no bank account, it will guide the user to go through Manage Bank process to add a bank account.

3. startWithdrawalFlow

// Example:
xfersComponents.startWithdrawalFlow()

Withdrawal Flow allows merchant to provide users a way to withdrawal funds from the Xfers wallet to their verified bank accounts.

It will check if transacting users have a verified bank account added. If not, it will guide the user to go through the process of linking a verified bank account.
It will check if transacting users are KYC-verified. If verification is required, it will guide the users to go through Verification process.

4. startTransactionsOverviewFlow

// Example:
xfersComponents.startTransactionsOverviewFlow()

Transactions Overview Flow allows merchant to provide users a way to check the Xfers related transactions records:

Deposit
Withdrawal
Transactions with merchants

5. startCreditCardFlow

<script type="text/javascript">
  // Example:
  const accessToken = 'ACCESS_TOKEN'

  const componentsOptions = {
    test: true,
    country: 'sg'
  }

  const xfersComponents = new Xfers.Components('xfers_elements', accessToken, componentOptions)

  // Trigger the SDK flows by executing the following command:
  xfersComponents.startCreditCardFlow({
    amount: 12000,
    fees: 180,
    currency: 'SGD',
    merchant: 'Binance',
    item: function() {
      return '1.0 BTC'
    },
    itemUpdateInterval: 1000,
    externalId: '1573714463428',
    description: 'extra notes'
  })

  // item: merchant will override this function, to return the right value.
  // itemUpdateInterval: the frequency that item is constantly updated.
</script>

On Sandbox, only credit card info below will produce successful transactions.

Card Number: 5400670032783859
Expiry Date: 12/22
CCV: 307

6. startBankTransferFlow

<script type="text/javascript">
  // Example:
  const accessToken = 'ACCESS_TOKEN'

  const componentsOptions = {
    test: true,
    country: 'sg'
  }

  const xfersComponents = new Xfers.Components('xfers_elements', accessToken, componentOptions)

  // Trigger the SDK flows by executing the following command:
  xfersComponents.startBankTransferFlow({
    bankTransferExternalId: `Ref: ${Date.now()}`,
    // Note: callbackUrl is optional
    bankTransferCallbackUrl: 'www.yourmerchantsite.com/callback'
  })
</script>

7. startWithdrawalOnBehalfFlow

<script type="text/javascript">
  // Example:
  const accessToken = 'ACCESS_TOKEN'

  const componentsOptions = {
    test: true,
    country: 'sg'
  }

  const xfersComponents = new Xfers.Components('xfers_elements', accessToken, componentOptions);

  // Trigger the SDK flows by executing the following command:
  xfersComponents.startWithdrawalOnBehalfFlow({
    withdrawalOnBehalfAmount: 1000,
    submitWithdrawalOnBehalfRequestCallback: params => {
    console.log('withdrawalOnBehalfRequest:', params)
    // params.toggleLoading()
    // params.setErrorMessage("Your withdrawal on behalf request has failed. Please try again.")
    params.goNext()
  })
</script>

The Withdrawal on Behalf flow works similar to the Connect flow, where we only provide the UI and the merchant is required to do the backend API integration.

Change Logs

Version 1.7.6 (02/08/2021)

What's new

Added Datadog JS client for top-up flow logging

Version 1.7.5 (02/08/2021)

What's new

Top-up Flow now takes in merchant_ref as a compulsory field

Version 1.7.0 (16/04/2021)

What's fixed

Update rollup plugins packages
Update axios
Deprecate Sentry package
Deprecate json-api-normalize

What's new

Xfers JS SDK now compiled into CJS instead of ESM (Client's system requirement)

Version 1.6.19 (23/03/2021)

What's fixed

Fix Sentry dependency issue

What's new

Version 1.6.18 (22/03/2021)

What's fixed

Update color code for Modal background

What's new

Version 1.6.17 (12/03/2021)

What's fixed

What's new

Integrate new virtual accounts into deposit
Update top-up instructions with VA integration

Version 1.6.16 (24/11/2020)

What's fixed

What's new

Add Declarations and Employment Forms into Verification SDK
Add Warning note for MyInfo flow for Verification SDK
Show static message for verified users instead of letting users check their submitted information

Version 1.6.15 (01/06/2020)

What's fixed

Fix dist-esm folder

What's new

Version 1.6.12 (22/05/2020)

What's fixed

What's new

Updated consumer advisory

Version 1.6.11 (17/4/2020)

What's fixed

What's new

Make SDK change logs public

Version 1.6.10 (14/4/2020)

What's fixed

Add headers'Accept' = 'application/json'

What's new

Remove entering account holder name for Manage Bank SDK flow

Version 1.6.9 (18/3/2020)

What's fixed

What's new

Remove Payout Flow (Unused)
Remove EditInfo Flow (Unused)
Remove Google Authentication Flow (Unused)
Remove Xfers Hub Flow (Unused)
Remove Payment Flow (Unused)
Remove unused Jest tests and other files

Version 1.6.8 (27/2/2020)

What's fixed

Remove Temporary Holding account check type for PersonalAccount

What's new

Version 1.6.7 (27/2/2020)

What's fixed

Allow withdrawal amount to be specified on Temporary Holding withdrawals
Add withdrawal limits for users (minimum, daily and yearly (yearly only applicable to unverified GW users))

What's new

Version 1.6.6 (25/2/2020)

What's new

All images that came through Verification Flow will only be compressed if size is > 6MB
Compression maximum dimension limits are adjusted from the original 1920 to 4032.

What's new

Version 1.6.5 (23/1/2020)

What's fixed

Remove Pre-PSA old code for top up and withdrawal SDKs
Revise Credit Card SDK APIs
Show 0 instead of - for maxed limits and no balances

What's new

Version 1.6.4 (16/1/2020)

What's fixed

What's new

Adjusted selfie sample and instructions

Version 1.6.3 (16/1/2020)

What's fixed

What's new

Add text for users to hold selfie with Xfers written on it

Version 1.6.2 (14/1/2020)

What's fixed

Fix Pending Withdrawal (Status UI and Verification Checks)

What's new

Version 1.6.1 (10/1/2020)

What's fixed

Fix ImageUploadWidget compression

What's new

Bank Transfer SDK
Withdrawal on Behalf SDK

Version 1.6.0 (31/12/2019)

What's fixed

What's new

Top-up SDK have new PSA limits (topup limits changed to 5k, withdrawal limits removed for SG)

Version 1.5.10 (26/12/2019)

What's fixed

Fix datepicker manual input

What's new

Withdrawal SDK can take in amount config, if amount is specified then user do not need to fill up amount
Expose store for Cypress testing

Version 1.5.9 (20/12/2019)

What's fixed

Datepicker not working

What's new

Add sole beneficial owner declaration for Connect SDK

Version 1.5.8 (18/12/2019)

What's fixed

Fixed datepicker showing invalid date issue

What's new

Version 1.5.6 (18/12/2019)

What's fixed

Updated suspended account screen message. (Compliance request on preventing fraud tip-off)

What's new

Version 1.5.5 (4/12/2019)

What's fixed

Datepicker wonky issue
Fix top up confirmation showing wrong bank account
Fix top up limit reached users unable to view transaction history

What's new

Version 1.5.4 (12/11/19)

What's fixed

What's new

Add tracking for Pending Verification screen
Add tracking for Verification Required screen
Add Credit Card SDK

Version 1.5.3 (8/11/19)

What's fixed

What's new

Add Top Up and Manage Bank Guide Posters
Add SG GW Manage Bank SDK
Add SG DGW Withdrawal SDK
Add SG GW Withdrawal SDK
Add SG Withdrawal SDK Mixpanel Tracking
Support embed Dashboard option for Manage Bank, Withdrawal and Top Up SDK

Version 1.5.2 (18/10/19)

What's fixed

Fix es5 compilation on bundle.js
Refactor code structure on SDK
Dynamically use production Mixpanel token
Add temp polyfill for Object.values and Object.entries

What's new

Add Sentry
Replace dev with customBaseDomain

Version 1.5.1 (Published 10/10/19)

What's fixed

Fix issue where embed VerificationSuccess still shows version footer

What's new

Version 1.5.0 (Published 10/10/19)

What's fixed

What's new

Fixed Can't upload PDF, limit file size to 5mb (with error messages)
Fixed Email validation failed when there's prefilled text
Feature Style updates of upload cover text
Embed option to use on Dashboard
Fully verified users can view their details again

Version 1.4.6

What's fixed

Fixed pdf upload issue for KYC documents

What's new

Added Mixpanel event tracking for all flows
Added pop-up blocker reminder screen for MyInfo flow

Version 1.4.3

What's fixed

Fixed overwriting styling
Updated consumer advisory
Increased the logo size on the successful connection screen

What's new

Remove upload file size limit
Mixpanel event trackers phase one

Version 1.3.16

What's new

Add gender field for verification

Version 1.3.15

What's fixed

Fix bug where users assigned to HSBC2 cannot see the top up instructions

What's new

Indo and SG Binance end-to-end tests

Version 1.3.12

What's improved

Added a datepicker for transactions history screen

What's new

Top-up no longer requires users to submit a bank statement
Better UI for manage bank account flow to inform users on their bank verification status
Indo Binance specific customisation