Payment participants

Look up your beneficiaries, senders, and your own onboarded entity, together with the wallets and bank accounts verified for each, used to settle trades with third parties. Submit a new bank account or wallet under any of them for Zodia Markets Operations to review.

A submitted bank account or wallet 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: it does not appear on the Get endpoints below, and it cannot be named in a trade or a withdrawal.

A payment participant is a party that Zodia Markets settles with on your behalf: your own onboarded entity, a beneficiary you deliver to, or a sender who delivers to Zodia Markets for you. Each carries the bank accounts and wallets registered for it.

---

The endpoints

Operation	Method and path
Get Account Details List	POST /api/3/originator
Get Beneficiary List	POST /api/3/beneficiaries
Get Sender List	POST /api/3/senders
Submit a Wallet	POST /api/3/ssi/wallets
Submit a Bank Account	POST /api/3/ssi/bank-accounts
List Wallet Requests	POST /api/3/ssi/wallets/requests
List Bank Account Requests	POST /api/3/ssi/bank-accounts/requests

All are POST and all take a signed JSON body, including the reads, because the anti-replay element travels in the signed body. Signing is described in Signing requests.

---

Adding a bank account or wallet

You can ask Zodia Markets to add a bank account or a wallet under a participant you already have: your own entity, or an existing beneficiary or sender. The same can be done in the client portal, on the Account Details and Third Party Trading screens.

You cannot create a new beneficiary or sender through this API

These endpoints add bank accounts and wallets under a participant that already exists. To set up a new beneficiary or sender, contact your relationship manager.

The lifecycle

1. Submit. Call Submit a Wallet or Submit a Bank Account. A successful call returns an approvalRequestId and status: PENDING. Nothing has been registered yet.
2. Pending Operations review. The request appears on List Wallet Requests or List Bank Account Requests as PENDING_SCREENING, shown in the client portal as Pending screening. The bank account or wallet cannot be used.
3. Approved, or declined.
   • Approved: the request drops off the requests list, and the bank account or wallet appears on the matching Get endpoint.
   • Declined: the request stays on the requests list as REJECTED. No reason is returned through the API; contact your relationship manager. To try again, submit a new request with corrected details.

Check the flags before you use a new entry

Operations may need to complete further checks after approval. Use a new entry only once the Get endpoint reports it as usable: a wallet with enabled: true and whitelisted: true, a bank account with enabled: true and verified: true. These flags are set by Zodia Markets and cannot be set in a submission.

There is no fixed review time. To follow a request, call the requests list, or contact your relationship manager.

---

Before you submit

The Move Funds permission on the key	Required by all four submit and list endpoints, including the two read-only lists. A key without it gets 403 MOVE FUNDS permission required
The ROLE_OPERATIONS role on the account group	Name the account group in accountGroupUuid. Without the role the call returns 403 You do not have permission to perform this action
The participant’s uuid	From Get Account Details List, Get Beneficiary List or Get Sender List

The role must be granted as ROLE_OPERATIONS itself, and owning the account group does not substitute for it.

---

Errors on the submit and list endpoints

Failures return the relevant HTTP status with a two-key body:

{ "success": false, "message": "<reason>" }

Status	Meaning	message examples
400	The participant is not one of yours for that account group, or the details were refused	Originator record not found — please contact support, or the reasons for the refusal
401	Authentication, signature, nonce/tonce, unparseable body, or throttling	Unauthorized
403	A required field missing or invalid, missing Move Funds, or no ROLE_OPERATIONS on the account group	Invalid signed params, MOVE FUNDS permission required, You do not have permission to perform this action
500	Unexpected error. The outcome is undefined	Error while processing request
502	Zodia Markets could not complete the call. The outcome is undefined	Unable to submit the request, please try again later

A missing or invalid field does not name the field

A required field that is absent or empty returns 403 Invalid signed params, the same answer as an unsigned body. Validate client-side against the field tables on each submit page.

The Originator record not found message reads Originator whichever kind of participant you named.

---

Retrying a submit

The submit calls are not idempotent and there is no idempotency key. If a submit times out or returns 500 or 502, call the matching requests list first, and resubmit only if your request is not there.

---

Related documentation

• Withdrawals - withdrawing to a bank account or wallet once it is usable