Skip to main content

External accounts and counterparties

An external account is a bank account or crypto wallet outside Nodu that you register for transfers. Its owner is the customer or someone else, and it takes one of two sides in a transfer. Learn both before you find the destinations and requirements of an account or declare the originator of a crypto funding.

External accounts and counterparties​

ObjectWhat it isWhat it holds
External accountThe bank account or crypto wallet itself.A paymentRail, which is the bank payment scheme or blockchain network of the account. A currency. The accountRequisites: for example an IBAN, or the address of a crypto wallet.
CounterpartyThe person or business that owns an external account, when the owner is not the customer.A type (individual or business), a name, an address and identity details.

You register both objects for a particular customer. One counterparty can own several external accounts, for example a supplier with a bank account and a crypto wallet. You use the id of the external account when you create a transfer.

The account details depend on the rail. One rail can accept more than one scheme, which is a set of account details. For example, Faster Payments accepts a sort code with an account number (the scheme bban) or an IBAN (the scheme iban). Get external account requirements returns the schemes and their fields for a customer: see Build the form.

First-party and third-party accounts​

Every external account has an owner. You state the owner with selfOwned when you create the account.

First-party accountThird-party account
The account belongs toThe customer.Someone else, such as a supplier or a family member.
selfOwnedtruefalse
counterpartyLeave it out. Nodu takes the owner's details from the customer's own profile.Required. Send the details of a new counterparty, or the id of an existing one: see below.

You cannot change selfOwned after you create the account.

A transfer that uses a third-party account, on either side, must carry a payment message in destination.message. The message has 6 to 140 characters. On a bank rail, the recipient sees it as the reference text of the payment. Without it, Nodu refuses the transfer with a validation error on destination.message.

For a third-party crypto wallet, Nodu also needs to know who controls it: see Travel Rule: what Nodu needs to know, and why.

Create the counterparty with the account, or reuse one​

For a third-party account, the request to create an external account carries a counterparty object. It works in one of two ways:

  • Create a new counterparty in the same request. Send counterparty.type and the counterparty's details. Nodu creates the counterparty together with the external account. You can add counterparty.clientReferenceId, your own reference for the counterparty. Nodu refuses a second counterparty with the same reference.
  • Reuse an existing counterparty. Send counterparty.id. Next to id, you can send only details that the counterparty still lacks: address, registrationNumber, dateOfBirth, placeOfBirth, idDocNumber and occupation. If you also send type, firstName, lastName, companyName or clientReferenceId, Nodu refuses the request with a validation error.

The response contains the counterparty with its id. Store the id to reuse the counterparty for the owner's next account.

This request creates a counterparty and a US bank account for it:

curl https://api.sandbox.nodu.fi/v1/external-accounts \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <new-uuid>' \
--data '{
"customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
"selfOwned": false,
"counterparty": {
"type": "individual",
"firstName": "John",
"lastName": "Smith",
"address": {
"country": "US",
"addressLine1": "1 Main St",
"city": "New York",
"state": "NY",
"postalCode": "10001"
}
},
"paymentRail": "ach",
"currency": "usd",
"accountRequisites": {
"bankCountry": "US",
"aba": "021000021",
"accountNumber": "12345678"
}
}'

This request registers a UK bank account for an existing counterparty:

curl https://api.sandbox.nodu.fi/v1/external-accounts \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <new-uuid>' \
--data '{
"customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
"selfOwned": false,
"counterparty": {
"id": "019ab6fd-a337-7aaf-9847-138efd21e3a6"
},
"paymentRail": "faster_payments",
"currency": "gbp",
"accountRequisites": {
"bankCountry": "GB",
"sortCode": "040004",
"accountNumber": "12345678"
}
}'

You can also create a counterparty on its own, before any account, with Create a counterparty.

The two sides of a transfer​

An external account takes one of two roles in a transfer:

  • Beneficiary side: the account receives the payout. This is the usual role, and the default.
  • Originator side: the account sends crypto that funds a transfer. You register a third-party account for this side when someone else sends crypto for your customer: see Declare who sends incoming crypto.

A transfer names the crypto wallet that funds it in source.externalAccountId. You send this field in two cases:

  • A third party sends the crypto. Send the third-party account registered for the originator side.
  • The customer sends the crypto from their own wallet at an exchange or custodian. Send the customer's first-party account for that crypto wallet: see Wallets at an exchange or custodian (hosted).

When the customer sends crypto from their own self-custody wallet, leave source.externalAccountId out.

Incoming bank payments need no originator declaration. You do not register the bank account that a customer pays from.

The field supportedSides lists the sides for which Nodu has validated the account. When you send it, Nodu checks the account against the requirements of each side. If the account does not meet them, the request fails with a validation error that names the missing fields. Without the field, Nodu validates the beneficiary side only. The originator side usually needs more details about the counterparty.

Validate an external account for a transfer side checks an existing account against one side. It returns the fields that are missing.

Statuses​

The statuses in this table apply to external accounts. A counterparty uses active and archived in the same way.

statusMeaningWhat you do
activeYou can use the object.Nothing.
update_requiredNodu's requirements changed after Nodu validated the external account.Add the missing details. Then call Update an external account with supportedSides, so that Nodu validates the account again. The account then returns to active.
archivedThe object is archived.Create a new object if you still need one.

Nodu refuses a new transfer that uses an external account whose status is not active.

What you can add or amend later​

After you create an external account, you can add details that it lacks and amend a few others. For example, before a crypto wallet that you registered earlier can send crypto on the originator side, you can add where it is held and the counterparty details that the side needs. The details that route the money are fixed.

ObjectYou can add or amendYou cannot change
External accountalias, a display name of your choice. supportedSides, to have the account validated for another side. For a crypto wallet, accountRequisites.walletType and accountRequisites.vaspId, which say where the crypto wallet is held: see Declare an existing crypto wallet. For a third-party account, the missing details of its counterparty.selfOwned, paymentRail, currency, and the routing details in accountRequisites, such as the IBAN or the address of the crypto wallet.
Counterpartyaddress, registrationNumber, dateOfBirth, placeOfBirth, idDocNumber and occupation.type, firstName, lastName, companyName and clientReferenceId.
  • To change a routing detail, archive the external account. Then create a new external account with the updated details.
  • Update a counterparty replaces each supplied value, including individual fields inside address. Omitted fields retain their values; this endpoint does not clear fields. The update affects every external account owned by that counterparty.
  • To add details about a third-party account's counterparty, send them in the request's counterparty object when you call Update an external account. A first-party account has no counterparty. If you send counterparty for a first-party account, Nodu refuses the request with rule=cannot_enrich_self_owned_external_account.

Complete an account that needs an update​

  1. Retrieve the account and identify every side you still need in supportedSides.
  2. Validate the account for each side to find missing fields.
  3. Update the permitted details, then send the complete supportedSides list with Update an external account to validate it again.
  4. Use the account for new transfers only after the returned status is active.

For example, if the stored address is {"country":"GB","city":"London","postalCode":"SW1A 1AA"}, a counterparty patch of {"address":{"postalCode":"SW1A 2AA"}} changes only the postal code. The country and city remain. Before updating a shared counterparty, account for every external account that uses its details.

Declare an existing crypto wallet​

To add or change the custody declaration on an existing crypto wallet, call Update an external account:

curl --request PATCH 'https://api.sandbox.nodu.fi/v1/external-accounts/<external-account-id>' \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"accountRequisites": {"walletType": "hosted", "vaspId": "<vasp-id>"}
}'

The rules:

  • Nodu replaces walletType and vaspId together. To keep the current vaspId, send it again.
  • To remove the declaration, send walletType=unknown. Nodu then also removes vaspId.
  • You cannot change the address of the crypto wallet. Nodu refuses a request that contains wallet.

Archive an account or a counterparty​

Archive an external account removes the account from use. Archive a counterparty also archives every external account of that counterparty.

  • Nodu refuses an update to an archived object. If you need the account again, create a new one.
  • Existing transfers keep their original account details.
  • List external accounts and List counterparties leave archived objects out, unless you ask for them with statuses[]=archived.

Next steps​