Skip to main content

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 no counterparty: Nodu takes the owner's details from the customer's profile.
  • Counterparty type. A counterparty is an individual or a business. 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.bankCountry is 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:

ValueMeaning
RequiredNodu refuses the request to create the external account without the field.
OptionalNot 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.

FieldIndividualBusiness
accountRequisites.bankCountryRequiredRequired
accountRequisites.ibanRequiredRequired
accountRequisites.bicOptionalOptional
counterparty.firstNameRequired–
counterparty.lastNameRequired–
counterparty.companyName–Required
counterparty.address.countryRequiredRequired
counterparty.address.addressLine1OptionalOptional
counterparty.address.addressLine2OptionalOptional
counterparty.address.cityOptionalOptional
counterparty.address.stateOptionalOptional
counterparty.address.postalCodeOptionalOptional

SWIFT​

Use paymentRail=swift, with the fiat currency of the bank account as currency.

FieldIndividualBusiness
accountRequisites.bankCountryRequiredRequired
accountRequisites.accountNumberRequiredRequired
accountRequisites.bicRequiredRequired
counterparty.firstNameRequired–
counterparty.lastNameRequired–
counterparty.companyName–Required
counterparty.address.countryRequiredRequired
counterparty.address.addressLine1RequiredRequired
counterparty.address.addressLine2OptionalOptional
counterparty.address.cityRequiredRequired
counterparty.address.stateOptionalOptional
counterparty.address.postalCodeRequiredRequired
  • accountRequisites.accountNumber takes the account number. For an account that has an IBAN, send the IBAN in this field.
  • counterparty.address.state is required when counterparty.address.country is US or CA.

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.

FieldScheme bbanScheme iban
accountRequisites.bankCountryRequiredRequired
accountRequisites.sortCodeRequired–
accountRequisites.accountNumberRequired–
accountRequisites.iban–Required

The counterparty fields are the same in both schemes:

FieldIndividualBusiness
counterparty.firstNameRequired–
counterparty.lastNameRequired–
counterparty.companyName–Required
counterparty.address.countryRequiredRequired
counterparty.address.addressLine1RequiredRequired
counterparty.address.addressLine2OptionalOptional
counterparty.address.cityRequiredRequired
counterparty.address.stateOptionalOptional
counterparty.address.postalCodeOptionalOptional
  • accountRequisites.sortCode has 6 digits.
  • accountRequisites.accountNumber has 8 digits.

ACH​

Use paymentRail=ach and currency=usd.

FieldIndividualBusiness
accountRequisites.bankCountryRequiredRequired
accountRequisites.abaRequiredRequired
accountRequisites.accountNumberRequiredRequired
counterparty.firstNameRequired–
counterparty.lastNameRequired–
counterparty.companyName–Required
counterparty.address.countryRequiredRequired
counterparty.address.addressLine1RequiredRequired
counterparty.address.addressLine2OptionalOptional
counterparty.address.cityRequiredRequired
counterparty.address.stateOptionalOptional
counterparty.address.postalCodeOptionalOptional
  • accountRequisites.aba is the ABA routing number. It has 9 digits.
  • accountRequisites.accountNumber has 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​

FieldBeneficiary sideOriginator side
accountRequisites.walletRequiredOptional
accountRequisites.walletTypeOptionalOptional
accountRequisites.vaspIdOptionalOptional
  • accountRequisites.wallet is the address of the crypto wallet. It has 20 to 128 characters.
  • accountRequisites.walletType and accountRequisites.vaspId describe crypto wallet custody.

An individual​

FieldBeneficiary sideOriginator side
counterparty.firstNameRequiredRequired
counterparty.lastNameRequiredRequired
counterparty.address.countryRequiredRequired
counterparty.address.addressLine1RequiredRequired
counterparty.address.cityRequiredRequired
counterparty.address.postalCodeRequiredRequired
counterparty.address.stateOptionalOptional
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 responseWhat you send
counterparty.dateOfBirth and counterparty.occupation, both with required=trueBoth fields.
counterparty.idDocNumber, counterparty.dateOfBirth and counterparty.placeOfBirth, all with required=falsecounterparty.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​

FieldBeneficiary sideOriginator side
counterparty.companyNameRequiredRequired
counterparty.address.countryRequiredRequired
counterparty.address.addressLine1RequiredRequired
counterparty.address.cityRequiredRequired
counterparty.address.postalCodeRequiredRequired
counterparty.address.stateOptionalOptional
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:

FieldWhat you send
walletTypehosted for a wallet held at an exchange or custodian; unhosted for a self-custody wallet. Omit it when custody is unknown.
vaspIdThe 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​