Send assets with PII

This workflow covers outgoing transfers where you must submit PII (Personally Identifiable Information). You create the Travel Rule message, collect PII from your end user, submit it through the API, and then create the transfer intent with the suggestedIntentId the message returns.

Creating the message first is the only supported entry path. Ripple Custody doesn't create a Notabene transfer from a transfer intent on its own.

• Travel Rule setup complete.
• Wallet addresses registered with Notabene. Ripple Custody registers them automatically when you connect your Notabene account and when you create new wallets.

Create a Travel Rule message with counterparty information:

POST /v1/domains/{domainId}/compliance/travel-rule/providers/NOTABENE/messages

Notabene is the only supported Travel Rule provider, so the provider path segment is always NOTABENE.

Request body:

Response:

Get the transfer to check whether Notabene requires PII and what the counterparty requests:

GET /v1/domains/{domainId}/compliance/travel-rule/providers/NOTABENE/messages/{travelRuleId}

Use the complianceTravelRuleId from Step 1 as {travelRuleId}.

Key response fields:

Fetch the document at presentationDefinitionUrl. A presentation definition is a JSON document, in the Presentation Exchange format, that lists the IVMS-101 fields the beneficiary VASP's jurisdiction requires. Notabene publishes one per jurisdiction.

Collect required PII from your end user according to the IVMS-101 standard and the requirements in the presentation definition from Step 2.

Notabene offers two ways to attach PII to a transfer, and Ripple Custody exposes both:

• Append (Option A). You submit plaintext IVMS-101 data. Notabene encrypts it with keys that Notabene manages and stores the encrypted PII on both your Notabene entity and the beneficiary's. Notabene can decrypt it, which lets Notabene run checks such as name screening on it.
• Present (Options B and C). You encrypt the IVMS-101 data yourself before you submit it. Notabene can't read the payload and forwards it to the beneficiary VASP. Only the beneficiary side stores the PII. Your Notabene entity and the Notabene platform don't store it.

In all cases, Ripple Custody forwards the PII to Notabene without storing it.

For Options B and C, you produce the encrypted payload. Notabene's end-to-end encryption uses ECDH-ES (RFC 7518) key agreement on the P-256 curve with the beneficiary VASP's public key, which the beneficiary publishes in its DIDdoc, and AES-256-GCM for content encryption. The encrypted payload is a compact JWE string. You publish your own public key in your DIDdoc so that counterparties can encrypt PII for you in the same way. For details and reference implementations, see Notabene's PII encryption guide and Encryption managed by the customer.

Use this option when both sender and receiver need access to the PII. You submit the PII in plaintext IVMS-101 format and Notabene encrypts it.

POST /v1/domains/{domainId}/compliance/travel-rule/providers/NOTABENE/messages/{travelRuleId}/pii

Request body:

Response: 200 OK

Use this option for end-to-end encrypted PII that Notabene can't read.

POST /v1/domains/{domainId}/compliance/travel-rule/providers/NOTABENE/messages/{travelRuleId}/encrypted-pii

Query parameters:

Request body:

Response: 202 Accepted (asynchronous processing)

The policies in this endpoint are Notabene authorization requirements, not Ripple Custody governance policies. The beneficiary VASP defines them in Notabene to state what it needs before it authorizes an incoming transfer, for example a Travel Rule message with originator PII. Each policy references the presentation definition that satisfies it.

Use this option to fulfill one specific policy that the beneficiary VASP attached to the transfer. travelRulePolicyId is the ID of that Notabene policy. Notabene returns it in the transfer details in the response to Step 1, so you don't need to call Notabene directly to get it.

POST /v1/domains/{domainId}/compliance/travel-rule/providers/NOTABENE/messages/{travelRuleId}/policies/{travelRulePolicyId}/encrypted-pii

Query parameters and request body: Same as Option B.

Response: 202 Accepted (asynchronous processing)

Create the Transfer Order intent using the suggestedIntentId returned in Step 1.

Transfer Order intent payload:

If transaction screening is configured (Chainalysis or Elliptic), Ripple Custody screens the transaction first.

• If screening fails (high risk score): The transaction is immediately rejected. No Travel Rule check occurs.
• If screening passes: The workflow proceeds to the Travel Rule check.

Notabene verifies counterparty information and PII.

Ripple Custody evaluates the results:

If the decision is NEED_EXPLICIT_DECISION, manual review is required in Ripple Custody.

• If AUTO_APPROVED: Transaction executes on blockchain, then Notabene is notified of settlement.
• If AUTO_REJECTED: Intent closes, then Notabene is notified of rejection.
• If the intent expires before execution (30 days by default): Ripple Custody automatically rejects the Travel Rule transfer on Notabene.

Poll the Travel Rule transfer status to confirm successful execution:

GET /v1/domains/{domainId}/compliance/travel-rule/providers/NOTABENE/messages/{travelRuleId}

Key response fields:

• Send without PII — When PII is not required
• Receive assets — Handle incoming Travel Rule transfers