@notabene/javascript-sdk

JavaScript SDK

This library is the JavaScript SDK for loading the Notabene UX components in the front-end.

Documentation • Installation

• JavaScript SDK
  • Installation
  • Usage
    • Authentication
  • Assisted Withdrawal
    • Embedded Component
      • Dynamic updates
    • Linked Component
  • Transaction parameters
    • Asset specification
    • Transaction amount specification
    • Destination address
    • Error handling
  • Customization
    • Functionality
    • Pass the variables in the configuration
    • Theme
    • Dictionary - The property name must be the same as the text in the widget, for it to be replaced
    • Fields Properties
    • Fallbacks
    • Opt-In Features
    • Transaction Custom Asset Price
  • License

Installation

There are two options for loading the Notabene SDK:

<script id="notabene" async src="https://unpkg.com/@notabene/javascript-sdk@1.31.0/dist/es/index.js"></script>

Or installing the library:

yarn add @notabene/javascript-sdk

Usage

Authentication

Use the customer token endpoint with your access token to receive a token with a customer's scope.

⚠️ IMPORTANT ⚠️

When requesting the customer token you must pass a unique customerRef per customer for ownership proof reusability, otherwise you might encounter unwanted behavior.

Create a new Notabene instance:

const notabene = new Notabene({
  nodeUrl: 'https://api.notabene.id',
  authToken: '{CUSTOMER_TOKEN}'
});

Use the same nodeUrl that you use to interact with the Notabene API.

Assisted Withdrawal

The Withdrawal Assist component helps you collect additional required information from your user during a standard crypto withdrawal process.

Embedded Component

This will let you embed the component into your existing withdrawal flow.

Create an html element to contain the component:

<div id="nb-withdrawal/>

Instantiate the withdrawal element and mount it using the id from above

const withdrawal = notabene.createWithdrawalAssist(tx, options);
withdrawal.mount("nb-withdrawal");

The simplest way to get the result is to use:

try {
 const {valid, ivms101} = await withdrawal.completion()
 if (valid) {
  // Submit result to your backend
 }
} catch (e) {
 console.error(e)
}

Dynamic updates

To update the component as users enter transaction details:

withdrawal.update({
  asset: 'ETH',
  destination: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
  amountDecimal: 1.12
});

To be notified once the validation is completed so you can submit the withdrawal to your back end:

withdrawal.on('valid', {ivms101} => ...)

To be notified of any errors use:

withdrawal.on('error',error => ...)

Linked Component

In some cases, in particular institutional or mobile apps you may prefer to link your customers to the component through an email or redirect the user to it in a mobile app.

const withdrawal = notabene.createWithdrawalAssist(tx, options, {
  callback: /// a serverside backend url
  redirectUri: // URI of website or mobile app to redirect user to after completion
});

// NodeJS redirect. Link also works in an email.
res.redirect(withdrawal.url);

Bear in mind that this is a full screen view for your users.

The two parameters that should be configured are:

• callback - a URL for your serverside. On completion this will receive an HTTP POST with the result as a json body and the authToken as an Authorization: Bearer header.
• redirectUri - the user will be redirected here on completion. The result parameters will be json encoded in the URL fragment. You can use a mobile app schema to intercept these in your mobile app.

Note for data privacy reasons the callback will be coming from your users web browser and not from our infrastructure, so no static IP is currently possible. Instead please check the authToken provided with the request.

Transaction parameters

Asset specification

The asset field the following types of assets specified:

• notabene_asset code passed as astring. See Notabene Assets Service.
• CAIP-19 is a chain agnostic format allows you to support the widest amount of assets and blockchains including NFTs.
• DTI is the ISO Digital Token Identifier format. See DTI registry for supported tokens.

Transaction amount specification

Use one of the following

• amountDecimal A number specifying the amount in decimal format. Eg. amountDecimal=1.1 would mean 1.1 of for example BTC or ETH.
• amountSubunits A string specifying the amount in the native blockchain subunits eg Satoshi for Bitcoin or wei for Ethereum

Destination address

Specify the beneficiary address as destination using one of the following formats:

• CAIP-10 is a chain agnostic format allows you to specify the specific blockchain and address
• EIP-3770 EVM URI
• BIP-21 Bitcoin URI
• Native blockchain address

---

Error handling

If any error occurs, the onError function from the Notabene instance will be triggered. The error passed as argument contains a data property that has the following type ErrorData.

⚠️ Note: These errors are mainly used for debugging internal issues while implementing the widget. They are not meant to be shown directly to the end user.

type ErrorData = {
  title: string;
  detail: string;
  code: number;
  type: string;
};

const notabene = new Notabene({
  ...,
  onError: (err) => {
    const errorData = err.data;

    // Do something
  },
});

Notabene Internal Errors

Type	Code	Title	Detail
BAD_REQUEST	400	Bad Request	NotabeneBadRequest: ...
TRANSACTION_INVALID	400	Transaction Invalid	NotabeneTransactionInvalid: ...
TOKEN_INVALID	401	Token Invalid	NotabeneTokenInvalid: ...
ASSET_NOT_SUPPORTED	404	Asset Not Supported	NotabeneAssetNotSupported: ...
SERVICE_UNAVAILABLE	500	Service Unavailable	NotabeneServiceUnavailable: ...
WALLET_CONNECTED_FAILED	500	Wallet Connection Failed	NotabeneWalletConnectionFailed: ...
WALLET_NOT_SUPPORTED	501	Wallet Not Supported	NotabeneWalletNotSupported: ...

Customization

Functionality

transactionTypeAllowed: ALL | VASP_2_VASP_ONLY | FIRST_PARTY_ONLY

For limiting the type of transaction destinations you can pass.

ALL: All transaction destinations are allowed. (DEFAULT) VASP_2_VASP_ONLY: Only transaction destinations that are VASPs are allowed. FIRST_PARTY_ONLY: Only transaction destinations that the originator owns are allowed.

---

nonCustodialDeclarationType: SIGNATURE | DECLARATION

For deciding which ownership proof type you want to use.

SIGNATURE: The ownership proof will be signed by the originator using a wallet. (DEFAULT) DECLARATION: The ownership proof will be declared by the originator using a checkbox.

---

counterpartyManualEntry: TRUE | FALSE

For deciding if you would like to allow your customer to provide a manual counterparty vasp name in the counterparty field.

Pass the variables in the configuration

const notabene = new Notabene({
    vaspDID: 'did:ethr:0x94c38fd29ef36f5cb2f7bc771f9d5bd9f7d05f27',
    widget: 'https://beta-widget.notabene.id',
    container: '#container',
    authToken: '{CUSTOMER_TOKEN}'
    allowedTransactionTypes: 'VASP_2_VASP_ONLY',
    nonCustodialDeclarationType: 'DECLARATION',
});

---

Theme

Pass a theme object when creating an instance

Here you can pass configuration which will customize the styles of the widget to meet your brand needs, all values are optional.

{
  primaryColor: '#fff',
  secondaryColor: '#fff',
  primaryFontColor: '#fff',
  secondaryFontColor: '#fff',
  backgroundColor: '#fff',
  fontFamily: Arial,
  logo: {LOGO_URL},
  mode: 'dark', // default: 'light'

  // If you are using the Signature flow, here is the full list of custom theme that can be applied to the WalletConnect Modal.
  '--w3m-font-family',
  '--w3m-font-feature-settings',
  '--w3m-overlay-background-color',
  '--w3m-overlay-backdrop-filter',
  '--w3m-z-index',
  '--w3m-accent-color',
  '--w3m-accent-fill-color',
  '--w3m-background-color',
  '--w3m-background-image-url',
  '--w3m-logo-image-url',
  '--w3m-background-border-radius',
  '--w3m-container-border-radius',
  '--w3m-wallet-icon-border-radius',
  '--w3m-wallet-icon-large-border-radius',
  '--w3m-wallet-icon-small-border-radius',
  '--w3m-input-border-radius',
  '--w3m-notification-border-radius',
  '--w3m-button-border-radius',
  '--w3m-secondary-button-border-radius',
  '--w3m-icon-button-border-radius',
  '--w3m-button-hover-highlight-border-radius',
}

To get a list of supported fonts, visit https://fonts.google.com/

To get more details about the WalletConnect theme variables, visit General style variables.

---

Dictionary

Pass a dictionary object mapping in text in the widget to your own language, for example:

To replace Loading... with Cargando...

{
  'Loading...': 'Cargando...',
}

The property name must be the same as the text in the widget, for it to be replaced

---

Fields Properties

Possible fields customization support:

field name	forceDisplay	optional	description
counterparty	--	☑️	Counterparty VASP or Wallet (destination or originator)
dateAndPlaceOfBirth	☑️	--	Recipient (or Sender) Date and Place of Birth
geographicAddress	☑️	☑️	Recipient (or Sender) Address
firstName	☑️	--	Recipient (or Sender) First name
name	☑️	--	Recipient (or Sender) Last Name / Company Name
nationalIdentification	☑️	--️	Recipient (or Sender) National Identification
country	☑️	☑️	Recipient (or Sender) Country of Residence (for natural person) / Country of Registration (for legal person)

Field Options

• forceDisplay - Force a field that is not required by your jurisdiction to be displayed - defaults to false
• optional - Bypass the jurisdiction rules validation for that specific field - defaults to false

{
  counterparty: {
    optional: true;
  },
  geographicAddress: {
    forceDisplay: true,
    optional: true;
  },
}

---

Beneficiary Details [DEPRECATED]

You can require specific beneficiary fields that are not required by your jurisdiction.

Possible fields:

• beneficiaryName - Recipient Name
• beneficiaryGeographicAddress - Recipient Address
• beneficiaryNationalIdentification - Recipient National Identification
• beneficiaryDateAndPlaceOfBirth - Recipient Date and Place of Birth

beneficiaryDetails: [
  'benficiaryName',
  'beneficiaryGeographicAddress',
  'beneficiaryNationalIdentification',
  'beneficiaryDateAndPlaceOfBirth',
];

---

Fallbacks

Fallbacks are custom options provided when desired outcome is not achieved

Possible options and actions:

• WALLET_NOT_SUPPORTED - Performs one of the following options when wallet is not supported
  • DECLARATION - Falls back to the self declaration flow
  • REJECT - Rejects the transaction and throws an error

    • The error that will be thrown here will have the following structure

        {
          "type": "WALLET_NOT_SUPPORTED",
          "title": "Wallet Not Supported",
          "status": 501,
          "detail": "We don't support the wallet for the provided asset"
        }
      

fallbacks: [{flow: "WALLET_NOT_SUPPORTED", action: "DECLARATION"}]

---

Finally you pass the configuration to a Notabene instance:

const notabene = new Notabene({
    widget: 'https://beta-widget.notabene.id',
    container: '#container',
    authToken: '{CUSTOMER_TOKEN}'
    theme: {THEME},
    dictionary: {DICTIONARY},
    fallbacks: [{flow: "WALLET_NOT_SUPPORTED", action: "DECLARATION"}]
});

---

Opt-In Features

const notabene = new Notabene({
    widget: 'https://beta-widget.notabene.id',
    container: '#container',
    authToken: '{CUSTOMER_TOKEN}'
    theme: {THEME},
    dictionary: {DICTIONARY},
    optInFeatures: ['REUSE_ADDRESS_OWNERSHIP_PROOF']
});

Available Opt-In Features

• REUSE_ADDRESS_OWNERSHIP_PROOF: For a given unique customer (identified by the customerRef from the customer token used) + unique wallet address, the widget would not ask for data collection if the customer previously verified the address ownership in a previous first party self-hosted transfer.

Transaction Custom Asset Price

To use your own asset price as fallback in case an asset is not supported by Notabene, you can provide a customAssetPrice object that will be used instead to render the widget with the correct jurisdiction requirements.

notabene.setTransaction({
  transactionAsset: 'ASSET_UNSUPPORTED_FROM_NOTABENE',
  beneficiaryAccountNumber: '0x8d12a197cb00d4747a1fe03395095ce2a5cc6819',
  transactionAmount: '2000000000',
  customAssetPrice: {
      priceUSD: 1700.12, // Asset price in USD
      decimals: 10 // Decimals used for the given transactionAmount
    };
});

License

BSD 3-Clause © Notabene Inc.