@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
    • Fields Properties
    • 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}',
  locale: 'de' // default locale
});

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

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.

---

Fields Properties

Possible fields customization support:

field name	forceDisplay	optional	description
dateAndPlaceOfBirth	☑️	--	Recipient (or Sender) Date and Place of Birth
geographicAddress	☑️	☑️	Recipient (or Sender) Address
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;
  },
}

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.