Skip to main content
Before you start: the OMS API is in early access. Every endpoint, including the ones in this guide, requires an early-access API key. Request access before you begin.Authenticate by exchanging your API key and secret for a bearer token at POST /auth/token, then send it as Authorization: Bearer {accessToken} on every request. Every POST that creates or changes a resource also requires an Idempotency-Key header. See Get started for the full flow.
This guide pays someone who is not your customer, such as a vendor or a payee, from a customer’s wallet. The recipient is a counterparty in the customer’s address book (see Entities) and never needs an OMS account. The flow has four steps: create the counterparty, register their bank account, quote, and execute.

​
Prerequisites

  1. A customer with a cst_ ID whose cryptoCustody and usd endorsements are active: the payout is funded from this customer’s wallet.
  2. A funded OMS wallet with a wlt_ ID holding enough USDC to cover the payout.
  3. The recipient’s details: their legal name, and their bank account information.

​
Step 1: Create the counterparty

POST /counterparties requires the owning customerId, an entityType discriminator, and the name fields for that type:
  • entityType: "individual" requires firstName and lastName, with optional dateOfBirth.
  • entityType: "business" requires businessName.
An address is also required unless your project is configured not to require one. Other identity fields are optional but improve compliance screening: email, phone, taxId, and nationality. The request is strictly validated: a missing or unrecognized entityType returns 422 EntityTypeInvalid, and a flat name field is rejected. Each entityType arm rejects keys from the other arm, so firstName on a business request (or businessName on an individual request) returns 422 Validation.

​
Request

When you supply an address, OMS validates it in full: non-blank line1, city, and zipCode, a two-letter ISO country, and state for a US address. line2 is optional. A counterparty created without an address omits address from its responses.

​
Response, 201 Created

Responses echo the split name fields and add a read-only name, server-composed as businessName for a business or firstName + " " + lastName for an individual. The composed value is at most 140 characters.
For an individual counterparty, the response carries firstName, lastName, and optional dateOfBirth in place of businessName, and name renders as "{firstName} {lastName}". Store the ctp_ ID. A counterparty that fails compliance screening comes back rejected with a failure object whose code says why; only active counterparties can own external accounts. Screening also runs on PATCH /counterparties/{counterpartyId}: an update can move a counterparty to rejected, and a counterparty rejected only for countryProhibited returns to active when an update moves its address to an allowed country. Address changes on an existing counterparty are screened the same way. A PATCH /counterparties/{counterpartyId} that resolves to a prohibited country returns 200 with status: rejected and failure.code: countryProhibited, and fires counterparty.statusChanged. Quote and transaction flows in this guide refuse payouts to external accounts owned by a rejected counterparty until the counterparty is updated back to an allowed country. Supplying an allowed country on a counterparty rejected with countryProhibited reactivates it; a counterparty rejected for any other reason stays rejected.

​
Step 2: Register the counterparty’s bank account

Register the recipient’s bank with POST /external-accounts, setting the owner to the counterparty. The per-type detail object must match the type: bankUs for US accounts, bankIban for international IBAN accounts, or bankCanada for Canadian accounts.

​
Request

​
Response, 201 Created

The full account number is write-only; reads return details.accountNumberLast4. owner names the counterparty, and customer is the customer the account is registered for. The account starts pending and moves to active (usable on quotes), or to failed or rejected with a failure. Wait for active, or externalAccount.statusChanged, before quoting against it.

​
Beneficiary identity on a US bank payout

When the destination is a counterparty-owned bankUs account, OMS registers the beneficiary with the paying bank under the counterparty’s own structured identity: the entityType, the matching name fields (firstName and lastName, or businessName), and the counterparty’s address. The customer’s identity is not used for a counterparty-owned account. Register US bank counterparties with the complete entityType, name, and address fields shown in Step 1; a counterparty without entityType cannot be used as a bankUs destination and is rejected with 422 AccountTypeRequirementsNotMet. A payout the receiving bank returns as a payee-name mismatch flips the external account to invalid with failure.code: payeeNameMismatch.

​
Step 3: Create the quote

The quote is identical to any other bank payout: the source is the customer’s OMS wallet, and the destination is the counterparty’s registered bank account referenced by its ext_ ID.
On the response, OMS resolves the recipient’s identity onto the destination’s owner block, so you can render who is being paid without extra reads:
Dereference the counterparty by owner.id for the recipient’s full record (entity type, address, contact fields). All amounts and fees live in the top-level pricing object, and sourceToDestination is cryptoToFiatAccount. The bank destination carries no rail; the rail is on the payout transfer once it exists.

​
Step 4: Execute and track

Accept the quote with POST /transactions and the quoteId:
The transaction starts at processing and moves to completed when the bank payout settles, or failed with a failure object. The payout leg surfaces granular progress in subStatus: processing.awaitingFiatOut while the payout is queued, then processing.fiatOut once it is in flight. If the payout fails and is retried, subStatus reads processing.payoutRetrying; if the provider holds it until your prefunded balance covers it, processing.payoutHeld. Poll GET /transactions/{transactionId} or subscribe to transaction.statusChanged; see the webhook events catalog. To reconcile a payout run, filter GET /transactions?customerId=...: each transaction’s destination owner.id is the counterparty it paid (owner.kind: "counterparty"). To see the name the recipient’s bank shows as the sender, read payoutOrigin.accountHolderName on the quote or transaction. payoutOrigin.accountHolder says whose identity that is: customer, partner, or paymentProvider.

​
Managing counterparties

  • GET /counterparties?customerId=... lists a customer’s counterparties. Paginate with limit, startingAfter, and endingBefore.
  • GET /counterparties/{counterpartyId} fetches one by ID.
  • PATCH /counterparties/{counterpartyId} partially updates identity fields; omitted fields are unchanged. entityType is immutable, and both entityType and the composed name field are rejected with 400. Name updates go through the split fields for the stored entityType (firstName and lastName for individual; businessName for business); the server recomposes and echoes back name. A name field that does not belong to the stored entityType returns 422 Validation, and an empty body returns 422 EmptyUpdate.
  • DELETE /counterparties/{counterpartyId} soft-deletes. It returns 409 CounterpartyHasActiveExternalAccounts while the counterparty still owns active external accounts: delete those accounts first, then delete the counterparty.