External account requirements by rail
These tables list the fields of an external account on the most common rails only: SEPA, SWIFT, Faster Payments, ACH and crypto wallets. The rails available to you depend on your integration agreement with Nodu. The fields can differ by the Nodu entity you integrate with. Get external account requirements returns the exact fields for a customer.
Plan your forms with these tables, but do not copy a fixed list of fields into your code: Find destinations and requirements shows how you build a form from the response.
How to read the tables
- Account fields start with
accountRequisites.. They describe the bank account or the crypto wallet. For each external account, send the account fields that apply to it. - Counterparty fields start with
counterparty.. They describe the counterparty: the person or business that owns the external account. You send these fields for a third-party account, which belongs to someone other than the customer. For a first-party account, you send nocounterparty: Nodu takes the owner's details from the customer's profile. - Counterparty type. A counterparty is an
individualor abusiness. Some fields exist for one type only. - Side. On a bank rail, an external account receives payouts: it is on the beneficiary side. A crypto wallet can also be on the originator side, where it sends crypto to fund a transfer.
- Bank country.
accountRequisites.bankCountryis the country of the bank, as a two-letter code. List external account destinations returns the bank countries that are available to your customer for a currency, with their rails.
Each cell has one of these values:
| Value | Meaning |
|---|---|
| Required | Nodu refuses the request to create the external account without the field. |
| Optional | Not universally required. Nodu accepts the field. The field can be required for your customer: the response of Get external account requirements says so. |
| – | The field does not apply. |
SEPA
Use paymentRail=sepa and currency=eur.
| Field | Individual | Business |
|---|---|---|
accountRequisites.bankCountry | Required | Required |
accountRequisites.iban | Required | Required |
accountRequisites.bic | Optional | Optional |
counterparty.firstName | Required | – |
counterparty.lastName | Required | – |
counterparty.companyName | – | Required |
counterparty.address.country | Required | Required |
counterparty.address.addressLine1 | Optional | Optional |
counterparty.address.addressLine2 | Optional | Optional |
counterparty.address.city | Optional | Optional |
counterparty.address.state | Optional | Optional |
counterparty.address.postalCode | Optional | Optional |
SWIFT
Use paymentRail=swift, with the fiat currency of the bank account as currency.
| Field | Individual | Business |
|---|---|---|
accountRequisites.bankCountry | Required | Required |
accountRequisites.accountNumber | Required | Required |
accountRequisites.bic | Required | Required |
counterparty.firstName | Required | – |
counterparty.lastName | Required | – |
counterparty.companyName | – | Required |
counterparty.address.country | Required | Required |
counterparty.address.addressLine1 | Required | Required |
counterparty.address.addressLine2 | Optional | Optional |
counterparty.address.city | Required | Required |
counterparty.address.state | Optional | Optional |
counterparty.address.postalCode | Required | Required |
accountRequisites.accountNumbertakes the account number. For an account that has an IBAN, send the IBAN in this field.counterparty.address.stateis required whencounterparty.address.countryisUSorCA.
Faster Payments
Use paymentRail=faster_payments and currency=gbp.
The rail has two schemes. A scheme is one set of account details that the rail accepts. The response of Get external account requirements lists the schemes that your customer can use.
| Field | Scheme bban | Scheme iban |
|---|---|---|
accountRequisites.bankCountry | Required | Required |
accountRequisites.sortCode | Required | – |
accountRequisites.accountNumber | Required | – |
accountRequisites.iban | – | Required |
The counterparty fields are the same in both schemes:
| Field | Individual | Business |
|---|---|---|
counterparty.firstName | Required | – |
counterparty.lastName | Required | – |
counterparty.companyName | – | Required |
counterparty.address.country | Required | Required |
counterparty.address.addressLine1 | Required | Required |
counterparty.address.addressLine2 | Optional | Optional |
counterparty.address.city | Required | Required |
counterparty.address.state | Optional | Optional |
counterparty.address.postalCode | Optional | Optional |
accountRequisites.sortCodehas 6 digits.accountRequisites.accountNumberhas 8 digits.
ACH
Use paymentRail=ach and currency=usd.
| Field | Individual | Business |
|---|---|---|
accountRequisites.bankCountry | Required | Required |
accountRequisites.aba | Required | Required |
accountRequisites.accountNumber | Required | Required |
counterparty.firstName | Required | – |
counterparty.lastName | Required | – |
counterparty.companyName | – | Required |
counterparty.address.country | Required | Required |
counterparty.address.addressLine1 | Required | Required |
counterparty.address.addressLine2 | Optional | Optional |
counterparty.address.city | Required | Required |
counterparty.address.state | Optional | Optional |
counterparty.address.postalCode | Optional | Optional |
accountRequisites.abais the ABA routing number. It has 9 digits.accountRequisites.accountNumberhas 4 to 17 digits.
Crypto wallets
The paymentRail is a blockchain network, for example ethereum. The currency is a stablecoin, for example usdc. A crypto wallet has no bankCountry.
The fields depend on the side. Send side to Get external account requirements to get the fields of one side.
The account fields
| Field | Beneficiary side | Originator side |
|---|---|---|
accountRequisites.wallet | Required | Optional |
accountRequisites.walletType | Optional | Optional |
accountRequisites.vaspId | Optional | Optional |
accountRequisites.walletis the address of the crypto wallet. It has 20 to 128 characters.accountRequisites.walletTypeandaccountRequisites.vaspIddescribe crypto wallet custody.
An individual
| Field | Beneficiary side | Originator side |
|---|---|---|
counterparty.firstName | Required | Required |
counterparty.lastName | Required | Required |
counterparty.address.country | Required | Required |
counterparty.address.addressLine1 | Required | Required |
counterparty.address.city | Required | Required |
counterparty.address.postalCode | Required | Required |
counterparty.address.state | Optional | Optional |
| Identity details | – | Required: see the next table |
counterparty.address.state is required when counterparty.address.country is US or CA.
On the originator side, Nodu needs identity details of an individual. The response returns one of two sets of fields. Which set it returns depends on the Nodu entity you integrate with.
| Fields in the response | What you send |
|---|---|
counterparty.dateOfBirth and counterparty.occupation, both with required=true | Both fields. |
counterparty.idDocNumber, counterparty.dateOfBirth and counterparty.placeOfBirth, all with required=false | counterparty.idDocNumber. Or counterparty.dateOfBirth together with counterparty.placeOfBirth. |
A date of birth must show that the person is at least 18 years old.
A business
| Field | Beneficiary side | Originator side |
|---|---|---|
counterparty.companyName | Required | Required |
counterparty.address.country | Required | Required |
counterparty.address.addressLine1 | Required | Required |
counterparty.address.city | Required | Required |
counterparty.address.postalCode | Required | Required |
counterparty.address.state | Optional | Optional |
counterparty.registrationNumber | – | Required |
counterparty.address.state is required when counterparty.address.country is US or CA.
Crypto wallet custody
These fields in accountRequisites apply to first-party and third-party external accounts on blockchain rails:
| Field | What you send |
|---|---|
walletType | hosted for a wallet held at an exchange or custodian; unhosted for a self-custody wallet. Omit it when custody is unknown. |
vaspId | The exchange or custodian's id from Nodu's directory. Optional, and accepted only with walletType=hosted. Send it whenever you know it; otherwise Nodu has to identify the business from the crypto wallet's address. |
Wallets at an exchange or custodian (hosted) explains why declaring custody before the transfer matters. To change custody on an existing account, see Declare an existing crypto wallet.
Find an exchange or custodian
See Find an exchange or custodian for selecting a VASP and looking up a stored identifier.
Limits on the values
The response of Get external account requirements also returns the limits of each field: maxLength, pattern and combinedMaxLength. Check a value against them before you send it. For example, on the bank rails above:
- Names and addresses accept the letters A to Z in upper and lower case, digits, spaces and the characters
-?:().,+. - The first name and the last name, joined by a space, have at most 35 characters. A company name has at most 35 characters.
Next steps
- Find destinations and requirements: get the fields for your customer and build the form.
- Declare who sends incoming crypto: register a crypto wallet on the originator side.
- External accounts and counterparties: the terms used in these tables.
- Simulate funding in the sandbox: test a transfer to an external account.