Skip to main content
PATCH
Update a Deposit Address

Authorizations

Authorization
string
header
required

Token from POST /auth/token

Path Parameters

depositAddressId
string
required

Deposit Address ID (da_ prefix).

Body

application/json

Partial update payload for a Deposit Address. The patchable fields are destination (re-point to a different bank-type External Account), returnDestination, label, and metadata. Any additional key in the JSON body is rejected with 400 by the handler (strict whitelist).

Re-pointing destination to a healthy bank External Account recovers a DA from inactiveActionRequired back to active; a re-point on an already active DA updates the target without a status transition.

destination
US bank account · object

Re-point the DA destination (bank-type External Account by EA id, a registered walletExternal crypto wallet, or a walletFiat fiat wallet). Re-validated exactly like create; walletCrypto is NOT currently supported — 422 destinationWalletCryptoNotSupported. Switching between destination kinds (bank / cryptoWallet / walletFiat) involving walletFiat is rejected with 422 destinationTypeSwitchNotSupported.

returnDestination
object

Re-point the registered crypto return destination (v0.11-8). PATCHable per the v0.11-8 contract; send explicit null to clear.

sponsorGas
boolean
default:true

When true, OMS absorbs the on-chain gas cost for the destination delivery. Only true is currently supported; accepted for forward-compatibility.

label
string

Partner display label.

metadata
object

Free-form key-value pairs stored on the resource and echoed back on reads.

Response

The request has succeeded.

A reusable crypto deposit configuration. Senders deposit the expected asset/network to the assigned on-chain address; OMS converts and delivers the funds to the configured bank destination automatically, creating a transaction per inbound deposit.

id
string

Deposit Address ID (da_ prefix).

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
object
enum<string>

Resource type discriminator. Always "depositAddress".

Available options:
depositAddress
customerId
string

Public customer id (cst_...). Named customerId to match VA's naming convention.

Pattern: ^[a-z]+_([0-9a-hjkmnp-tv-z]{26}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$
customer
object

Display-safe summary of the owning customer (customer.id equals customerId). Returned on list and detail responses.

status
enum<string>

Current lifecycle status of the deposit address.

Available options:
pending,
active,
frozen,
closed,
failed,
inactiveActionRequired
statusReason
string

Human-readable explanation of the current status.

expectedSourceAsset
string

Asset of the inbound crypto the DA expects.

expectedSourceNetwork
enum<string>

Network of the inbound crypto the DA expects.

Available options:
ethereum,
polygon,
base,
solana,
tron
depositInstructions
object

Populated in the create response when the provider assigns the address up front. Otherwise it is null until the provider has assigned the on-chain address: poll GET /deposit-addresses/{depositAddressId} until it is populated before giving a sender deposit instructions.

destination
OMS wallet · object

V0.10: unified destination shape (payoutOrigin now lives inside TransactionDestination).

returnDestination
object

Registered crypto return destination (v0.11-8), echoed when set.

failureReason
enum<string>

Set when status = failed; closed enum identifying the failure category.

Available options:
provisioningTimeout,
systemError,
ereborRejected,
intlBankAccountCreateRejected,
noMatchingNetwork,
blockchainAddressInUse,
bankAccountInUse
sourceToDestination
enum<string>

Derived from the destination type: cryptoToFiatAccount for a bank destination, or cryptoToCrypto for a crypto-wallet destination.

Available options:
cryptoToCrypto,
cryptoToCash,
cryptoToFiatAccount,
cashToCrypto,
fiatAccountToCrypto,
fiatAccountToFiatAccount
sponsorGas
boolean

Whether OMS absorbs the on-chain gas cost for the destination delivery. Persisted from the create/update request (currently only true is accepted).

provider
string

The institution that issues and custodies this Deposit Address — currently "Erebor Bank, N.A." or "Coinme Inc.". Assigned by OMS from your project's configuration. It determines which expectedSourceAsset / expectedSourceNetwork pairs you can use: an unsupported pair is rejected at create time with 422 depositAddressAssetNetworkNotSupported, which names the same provider in details.provider. Read it when you need to tell an end user or a support ticket which institution is holding the funds. It is not the entity an outbound payment is sent under — that is payoutOrigin.accountHolderName, which is set by whoever executes the payout and can name a different company. New providers may be added, so treat the string as free-form rather than a fixed set. Read-only; omitted when the issuing institution is not recognised.

requiresCounterpartyWalletRegistration
boolean

Whether a sender's wallet must be registered as a walletExternal External Account under this Deposit Address's customer before it deposits. Derived from the issuing provider, never supplied by you: Deposit Addresses issued by Erebor Bank, N.A. accept a deposit only from a registered counterparty wallet (true), while those issued by Coinme Inc. accept a deposit from any crypto address (false). When true, a deposit from an unregistered address still arrives, but its transaction parks on a senderAttribution hold until you register a matching External Account (the hold's matchableExternalAccountCriteria says what will match) and fails at the hold's deadline if you never do — so capture the sender's address up front. When false, there is nothing to register against, so skip that step entirely. Read it per Deposit Address rather than caching it per project. Read-only, and omitted when OMS cannot identify the issuing provider — treat the requirement as undetermined rather than assuming either regime.

label
string

Partner display label.

metadata
object

Free-form key-value pairs supplied at creation or update.

createdAt
string<date-time>

When the deposit address was created.

updatedAt
string<date-time>

When the deposit address was last updated.