Submit a Bank Account

POST https://trade-uk.sandbox.zodiamarkets.com/api/3/ssi/bank-accounts

Ask Zodia Markets to add a bank account under your own onboarded entity, or under an existing beneficiary or sender.

A submitted bank account is a request

Zodia Markets Operations must review and approve it before it can be used for settlement or withdrawals. Until then it is pending and unusable.

Permissions

The API key needs the Move Funds permission, and your user needs ROLE_OPERATIONS on the accountGroupUuid you name.

Not idempotent

A retry with a fresh nonce can raise a second request. On a timeout, a 500 or a 502, call List Bank Account Requests before resending.

---

Choosing the participant

participantUuid names who the bank account belongs to:

To add a bank account for	Take uuid from
Your own onboarded entity	Get Account Details List
An existing beneficiary	Get Beneficiary List
An existing sender	Get Sender List

The participant must be one of yours, for the account group you name. Otherwise the call returns 400 Originator record not found — please contact support, whichever kind of participant you named. You cannot create a new beneficiary or sender here; contact your relationship manager for that.

---

Before you call

This endpoint requires more than the bank details alone. Every one of these must be present and non-empty:

accountGroupUuid, participantUuid, bankName, bankBranchName, accountAlias, accountName, currency, iban, swiftCode, clearingType, clearingId, direction, country, street, city and memo.

memo is limited to 1024 characters. accountNumber, postalCode, the intermediary-bank fields and networkIds are optional; send intermediaryClearingType and intermediaryClearingId together. A missing or empty required field returns 403 Invalid signed params without naming the field, so validate client-side against the table below. Details refused on their content return 400 with a message describing the problem.

enabled and verified cannot be set

The body has no field for either. They are set by Zodia Markets, and a property of that name in the body is ignored.

---

After it succeeds

The call returns approvalRequestId and status: PENDING. The request appears on List Bank Account Requests, with kind set to the participant’s kind, as PENDING_SCREENING.

Once Operations approves it, the request drops off that list and the bank account appears under its participant on the matching Get endpoint. Operations may need to complete further checks before the account can be used, so use it only when that endpoint reports enabled: true and verified: true. If Operations declines it, the request is listed as REJECTED; contact your relationship manager for the reason. See Adding a bank account or wallet.

Domain: Payment participants

Note

This call is not idempotent and there is no idempotency key. Resending with a fresh nonce or tonce can raise a second review request. If a submit times out or returns 500 or 502, call List Bank Account Requests first, and resubmit only if the request is not there.

Request

POST https://trade-uk.sandbox.zodiamarkets.com/api/3/ssi/bank-accounts

Headers

Header	Required	Description
Rest-Key	yes	API key for authentication
Rest-Sign	yes	Calculated API Signature

Body

Field	Type	Required	Description
tonce	integer (int64)	yes	The current Unix time in microseconds. Accepted only within two minutes of server time. Send either tonce or nonce.
nonce	integer (int64)		Alternative to tonce, and takes precedence when both are sent. Must be a whole number and strictly increasing for a given API key: a reused or lower value is rejected. A request carrying neither nonce nor tonce is rejected with 401.
accountGroupUuid	string	yes	The account group you are acting for. You must hold ROLE_OPERATIONS on it.
participantUuid	string	yes	The participant the new entry is added under: your own onboarded entity (the uuid from Get Account Details List), or an existing beneficiary or sender (the uuid from Get Beneficiary List or Get Sender List). It must be one of yours. A new beneficiary or sender cannot be created through this API.
bankName	string	yes	Name of the bank.
bankBranchName	string	yes	Branch of the bank.
accountAlias	string	yes	Your own name for the account.
accountName	string	yes	Name of the account holder, as the bank records it.
currency	string	yes	Currency of the account, e.g. GBP.
accountNumber	string		Optional. The account number.
iban	string	yes	The IBAN.
swiftCode	string	yes	SWIFT/BIC of the bank.
clearingType	string	yes	The clearing scheme clearingId belongs to. Ask your relationship manager for the values accepted.
clearingId	string	yes	The bank’s identifier in that clearing scheme.
direction	string	yes	Which way the account is used, for example BOTH.
country	string	yes	Country of the bank.
street	string	yes	Street address of the bank.
city	string	yes	City of the bank.
postalCode	string		Optional. Postal code of the bank.
memo	string	yes	Free text, up to 1024 characters. Required on this endpoint.
intermediaryName	string		Optional. Name of an intermediary bank.
intermediaryBankCountry	string		Optional. Country of the intermediary bank.
intermediaryBankSwiftBic	string		Optional. SWIFT/BIC of the intermediary bank.
intermediaryClearingType	string		Optional. Clearing scheme of the intermediary bank. Send it together with intermediaryClearingId.
intermediaryClearingId	string		Optional. The intermediary bank’s identifier in that scheme.
networkIds	array of string		Optional. Payment network identifiers for the account. Ask your relationship manager which apply.

Responses

200 OK

Request accepted for review by Zodia Markets Operations. The bank account or wallet is not usable yet.

Body

Field	Type	Required	Description
success	boolean
approvalRequestId	integer (int64)		Identifier of the review request. Quote it to your relationship manager, and match it against the id returned by the bank account requests list.
status	string		PENDING: awaiting review by Zodia Markets Operations. The list endpoint reports the same state as PENDING_SCREENING.

400 Bad Request

The request was not created.

message	Cause
Originator record not found — please contact support	participantUuid does not identify one of your participants for this account group. The message reads Originator whichever kind of participant you named
<field>: <reason>, several joined by ;	The details failed validation, for example an address that is not valid for the blockchain
Another reason, or The submitted details were rejected	The details were refused for a reason not covered above

Body

Field	Type	Required	Description
success	boolean
message	string

401 Unauthorized

Authentication failed: unknown key, bad signature, a missing, malformed, reused or decreasing nonce or out-of-window tonce, a body that is not parseable JSON, or a throttled caller. Rate limiting surfaces here as 401, not 429.

Body

Field	Type	Required	Description
success	boolean
message	string

403 Forbidden

Body missing or failed field validation (Invalid signed params), the API key lacks the Move Funds permission (MOVE FUNDS permission required), or you do not hold ROLE_OPERATIONS on accountGroupUuid (You do not have permission to perform this action). The message does not name the field or the permission at fault. Every required field must be present and non-empty, including iban, clearingType, clearingId, direction, street, city and memo; memo at most 1024 characters.

Body

Field	Type	Required	Description
success	boolean
message	string

500 Internal Server Error

Unexpected error. The outcome is undefined.

Body

Field	Type	Required	Description
success	boolean
message	string

502

The service that holds bank accounts and wallets could not be reached or returned an unusable answer. The outcome is undefined: call the matching list endpoint before resending.

Body

Field	Type	Required	Description
success	boolean
message	string