Create a transfer

post

https://sandbox.notabene.id/api/v1/transfers

Creates a transfer and notifies the beneficiary's institution. Notabene never creates two transfers with the same ref: sent again unchanged, the request answers 201 with the same transfer, or 409. Either way, the first request created it. An inline ownership proof of an address another of your customers already holds a submitted, verified or accepted proof of also returns 409 Conflict, and one that cannot be verified because its verification service is unavailable returns 502 Bad Gateway.

Besides ref, asset and amount, a create needs settlement_address or beneficiary_entity_did. A withdrawal also needs its originator, as originator_id. A deposit you create yourself names the sending institution or your own DID instead, as Deposits, funds first explains.

Required permission: create:transfer.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Used in these guides:

Body Params

amount

string

required

The amount transferred, in the asset's whole units rather than its smallest unit. For example 1.5 ETH, not 1500000000000000000.

asset

string

required

The asset being transferred, as a CAIP-19 identifier or a plain symbol such as BTC. Symbols resolve to their canonical CAIP-19 identifier.

ref

uuid

required

Your own reference for the transfer, a UUID: anything else answers 400 ref must be a UUID. Notabene never creates two transfers with the same ref.

beneficiary

object

The party receiving the funds, supplied inline. Requires beneficiary_id alongside it, naming the customer this profile describes.

beneficiary_entity_did

string

DID of the beneficiary's institution. When omitted, it is discovered from settlement_address.

beneficiary_id

string

The IRI of the beneficiary: an existing customer’s id, or an id of your own for the beneficiary you send in beneficiary. Required with beneficiary: without it, the create answers 400 party profile provided without party ID.

beneficiary_proof_of_ownership

object

Proof that the beneficiary controls a self-hosted settlement_address.

fiat_amount_usd

string

Your own fiat valuation of the transfer, as a decimal string in USD. When present it takes precedence over our own asset pricing, and is what the travel-rule threshold is compared against.

memo

string

Free-text memo carried with the transfer.

memo_tag

string

XRPL destination tag or Stellar memo for the settlement address. Equivalent to appending :tag to settlement_address.

originator

object

The party sending the funds, supplied inline. Requires originator_id alongside it, naming the customer this profile describes.

originator_entity_did

string

DID of the originator's institution. When omitted, it is discovered from source_address. May be combined with beneficiary_entity_did; your own role on the transfer follows the DID you authenticated as.

originator_id

string

IRI naming the originator. Required whenever the transfer names an originator: on its own to reuse a customer the node already holds, or alongside originator to name the customer that profile describes. An IRI the node does not know yet is accepted, and the customer is created with the transfer.

originator_proof_of_ownership

object

Proof that the originator controls a self-hosted source_address.

provided

array of strings | null

The PII fields you are supplying, validated against the requirements of the applicable jurisdiction.

provided

settlement_address

string

The address the funds are sent to. Accepts a bare address, a CAIP-10 identifier or a did:pkh; a bare address is interpreted on the asset's chain.

settlement_id

string

Settlement identifier of a transfer already received on-chain, as a transaction hash or a CAIP-220 identifier. A raw hash is interpreted on the asset's chain. Required when originator_entity_did names a counterparty institution.

source_address

string

The address the funds are sent from. Accepts a bare address, a CAIP-10 identifier or a did:pkh; a bare address is interpreted on the asset's chain.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

429

Too Many Requests: more than 6,000 calls in 300 seconds. Every endpoint refuses your calls for the next 10 seconds. Send the request again with a backoff, as Rate limiting explains.

201Created: the new transfer, or the one an earlier request with the same ref created.

400Bad Request: a field is missing or invalid. Each problem is listed under errors, with the field when it can be named, for example beneficiary_entity_did or settlement_address is required, or originator or originator_id is required for a withdrawal without its originator.

401Unauthorized: the access token is missing, malformed or expired. Request a new one, as Authentication explains.

403Forbidden: the token cannot make this call. It lacks the permission named above.

409Conflict: a transfer with this ref already exists. If you sent the request again, it is the one your first request created: find it by ref in its transfer.created.v3 event. If not, use a new ref.

500Notabene could not complete the call. Send it again after a pause: the same ref never makes a second transfer.

502Bad Gateway