Find destinations and requirements
Before you create an external account, two operations tell you what to collect: where the customer can be paid out, and which fields the account needs. The fields can differ between two customers on the same rail, so get them for each customer. Do not keep a fixed list of fields in your code. External accounts and counterparties defines the terms used here.
Find the destinations
Call List external account destinations with the customerId and a currency. Each entry of destinations has a bankCountry and the rails available for it. A rail is a bank payment scheme or a blockchain network. A blockchain destination has no bankCountry.
The response lists the rails on which the customer has an active payment channel. Offer the customer these countries and rails.
Get the requirements
Call Get external account requirements with these parameters:
| Parameter | What you send |
|---|---|
customerId | The customer. Required. |
currency, rail | The currency and the rail of the account, from the destinations. Required. |
bankCountry | The country of the bank, for a bank rail. |
counterpartyType | The type of the account's owner: individual or business. For a first-party account, send the customer's own type. Required unless you send counterpartyId. |
side | beneficiary for an account that receives payouts. This is the default. originator for a crypto wallet that funds a transfer: see Declare who sends incoming crypto. |
counterpartyId | An existing counterparty that will own the account: see Reuse a counterparty. |
Reuse a counterparty
One counterparty can own several external accounts. When you register another external account for the same person or business, reuse the existing counterparty:
- Use the counterparty
idyou stored when registering that owner. Do not create a second counterparty for the same stored record. - Send its
idascounterpartyId. You can leave outcounterpartyType. The response leaves out thecounterparty.*fields that the counterparty already has.
Read the response
The response is a list of schemes. A scheme is one set of account details that the rail accepts. For example, Faster Payments can return two schemes: bban, a sort code with an account number, and iban, an IBAN. The scheme with default=true is the recommended one. Offer the customer one scheme, or a choice between the schemes. The request to create an external account has no scheme field. Send the values the customer entered for the selected scheme.
Each scheme has a list of fields. The reference describes every property of a field. These are the ones your form depends on:
| Property | Meaning |
|---|---|
field | The path of the value in the request to create an external account, such as accountRequisites.iban or counterparty.firstName. |
label, inputType, options | A readable name, the kind of input, and the allowed values of a select input. |
required | true when the field is required in every case. A field with false can still be required in some cases. For example, addresses in some countries must include a state. |
maxLength, pattern, combinedMaxLength | Limits on the value. Check them before you send the request. patternMessage is a text that you can show when a value does not match pattern. |
This excerpt of a response for Faster Payments shows one scheme and three of its fields:
[
{
"scheme": "bban",
"default": true,
"fields": [
{
"field": "accountRequisites.sortCode",
"label": "Sort Code",
"inputType": "text",
"required": true,
"pattern": "/^[0-9]{6}$/",
"patternMessage": "Sort code must be exactly 6 digits."
},
{
"field": "accountRequisites.accountNumber",
"label": "Account Number",
"inputType": "text",
"required": true,
"pattern": "/^[0-9]{8}$/",
"patternMessage": "Account number must be exactly 8 digits."
},
{
"field": "counterparty.address.addressLine1",
"label": "Address Line 1",
"inputType": "text",
"required": true,
"maxLength": 100,
"pattern": "/^[a-zA-Z0-9\\-?:().,+ ]*$/",
"patternMessage": "Only letters, numbers, and characters -?:().,+ are allowed."
}
]
}
]
External account requirements by rail shows the fields of the most common rails. Use it to plan your forms. The response returns the exact fields for your customer.
Build the form
- Fields. Show an input for each field of the selected scheme. How you present the form is your choice. The request to create the external account must carry the values.
- First-party account. Use only the fields that start with
accountRequisites.. Do not sendcounterparty: Nodu takes the owner's details from the customer's profile. - Third-party account. Also show the
counterparty.*fields. They describe the counterparty, the owner of the account. - Errors. When a value is missing or not valid, Create an external account fails with a validation error, which has the code
validation_failed. Each entry oferrorshas apropertyPaththat matches afieldof the requirements, so you can show the message next to the input.
Apply constraints and show errors
A missing constraint means that constraint does not apply; it does not mean a limit of zero. A returned pattern is a regular expression with delimiters, such as /^[0-9]{6}$/. If you validate in another language, handle the delimiters and supported syntax explicitly. Do not pass the whole string unchanged to an HTML pattern attribute. Server validation remains authoritative.
For combinedMaxLength, join the values of its fields in the returned order using its separator, then check the joined length against maxLength. For example, John and Smith, joined with a space, have length 10. With a returned limit of 35, they pass; two names that each fit an individual limit can still exceed the combined limit.
required=false means the field is not always required. For example, a bank address can require state when its country is US or CA. Follow the returned requirements and the rail-specific notes; show any additional conditional requirement reported by validation.
If an error names counterparty.address.postalCode, attach its message to the postal-code input. If the path has no matching input or is null, show it as a form-level error. Keep the customer's other values when they correct the form.
Create the external account
Call Create an external account with the customerId, selfOwned, paymentRail, currency and accountRequisites. For a third-party account, add counterparty: the details of a new counterparty, or the id of the counterparty that you reuse. Create the counterparty with the account, or reuse one shows both requests. Send an Idempotency-Key header: see Idempotency.
For a crypto wallet, include the custody fields when you know where it is held.
Store the id of the external account. Send it as destination.externalAccountId when you create a transfer that pays out to this account.
Next steps
- Quotes and exchange rates: show the customer what a transfer to this account costs.
- Declare who sends incoming crypto: register a crypto wallet that funds a transfer.
- Simulate funding in the sandbox: test a payout to the external account.