System Interactions

Withdrawal

There are two scenarios for withdrawals; you either already know who the beneficiary is (pre-whitelisting/data collection) or you don't (collect the data in your frontend during the withdrawal request:

Front-end data collection

In the diagram below, you will see how your system interacts with Notabene and the beneficiary VASP when it comes to sending travel rule messages.

To be able to send these messages, there are 4 parts that need to be integrated into your system:

1. Widget or Validation API for wallet identification and data collection in your front-end;
2. Create transaction for sending travel rule messages;
3. Create a notification webhook for getting updates on your travel rule messages;
4. Update transaction for updating the travel rule message with transaction hashes.

We have described the flow in detail further down on this page, and each number in the diagram corresponds to the number of the text:

📘

Travel rule vs. blockchain

As you can see above, travel rule data transfers happen outside of the blockchain on separate protocols and networks. There is currently a handful of these on the market today, but very few of them are actually live and actively used by VASPs to exchange travel rule messages. While we wait for one or two protocols to become dominant in the market, our TR:Now multi-protocol switch enables us to reach any VASP on any network.

Travel rule step-by-step

The whole travel rule process starts with your customer requesting a withdrawal by specifying the amount, the type of virtual asset, and which wallet address it should go to, then:

1. Our widget or validation API will try to perform wallet identification and help you collect the necessary information required by travel rule requirements in different jurisdictions.
2. Once all the required information has been collected in the validation stage, it is passed from the frontend to the backend of your system.
3. Information about your customer (the originator) is added.
4. The transaction API takes the details of your customer and the recipient, and prepares to share it with the counterparty VASP.
5. Before the PII information is shared, our system will first ask the VASP if they control the wallet address and if they do, the originator and beneficiary details is shared with them.
6. After reviewing the information you have sent, the counterparty VASP will then accept or reject the transfer request.
7. The status of your travel rule transfer (Accepted or rejected) will be automatically updated in your system by the webhook.
8. When you have received the "Accepted" status, you should release the funds on the blockchain.
9. Once the funds have been released, you need to update the travel rule with its transaction hash using txUpdate.

Using pre-collected/whitelisted data

If you require your customer to pre-register all destination addresses they want to send funds to, how they are hosted and the beneficiary details, you can optionally skip implementing the widget/validation API.

You will then need to make sure that the following checks are substituted:

1. Threshold check - is the FIAT value of the virtual asset above or below the amount where you are required to send travel rule information? *Optional; you can create a travel rule for each withdrawal and Notabene will check if it needs to be SENT or SAVED.
2. Valid beneficiary data - have you already collected all the beneficiary details that you need for the travel rule message to be sent?
3. Address identification - do you know if it is hosted or unhosted? If it is hosted, do you know by whom?

The KYC database usually contains everything you need about the originator required by your regulator:

• Name
• Date of Birth
• Address
• National ID
• Etc.

The address book database should contain, among others:

• Wallet addresses
• If they are hosted or unhosted
  • If hosted, name of VASP (which in turn should be mapped to it's DID)
  • If hosted, name of the beneficiary
  • If self-hosted and owned by your customer, the proof of control for that wallet
  • If self-hosted and not owned by your customer, name of the beneficiary
• +any additional details required in your jurisdiction

📘

Do I have everything?

Once all the information about the originator and beneficiary has been pulled from the databases and orchestrated into the IVMS101 format, you can send it to txValidateFull to confirm that everything is present.

You could also leverage txValidateFull when building the address book database so that everything gets collected from the start.

Deposit

There are a few scenarios that can happen when there is a deposit to your VASP:

a) Originator VASP sends funds without travel rule;

b) Originator VASP sends funds with travel rule;

c) Originator VASP sends travel rule and waits for your reply before sending funds.

The diagram below shows how to deal with all of these scenarios and there is a more detailed description of them underneath:

When you receive a travel rule message, you first need to verify that the address is yours. This can be done in two ways:

a) Use the address webhook which will automatically query your backend and ask if the address is yours. If it is, it will automatically confirm it and the message will change to ACK status.

b) Use the details in the notification webhook to check if the address is yours before calling txConfirm.

Originator VASP sends funds without travel rule

When you receive a deposit on the blockchain, you call txNotify to check if there is a travel rule message that matches the transaction details (hash, origin, destination, value).

Since the Originator VASP hasn't sent a travel rule message, one will be automatically created. This message will have an "incomplete" status as it is missing originator and beneficiary information.

The originator information needs to be collected from the beneficiary and then added to the incomplete message using txUpdate.

Originator VASP sends funds with travel rule

When you receive a deposit on the blockchain, you call txNotify to check if there is a travel rule message that matches the transaction details (hash, origin, destination, value).

Since the Originator VASP has sent a travel rule message, txNotify will return the status of that message. If it is accepted, you deposit the funds into the beneficiary wallet. If it is declined, a compliance officer should investigate before anything is done with the funds.

Originator VASP sends travel rule and waits for your reply before sending funds

This is the ideal flow where you get to make a decision before the funds are sent from the Originator VASP. Because no funds are actually yet, there will be no refund or issues if you do not want to receive them.

After this flow is completed, the "Originator VASP sends funds with travel rule"-scenario will still happen since you receive a blockchain deposit and that always triggers txNotify. In this case though, since there is an accepted travel rule message, the funds are deposited.

Deposit from unhosted wallet

If the deposit is coming from an unhosted wallet, you will not receive travel rule information so it will always return an INCOMPLETE message after txNotify.