1M1money
crate::connectivity::controller::openapi::withdrawals

POST /v1/customers/{customer_id}/withdrawals

Changed on

Request

Path parameters

customer_idstring required

Customer ID

Headers

Idempotency-Keystring required

UUID v4 for idempotent requests. In sandbox, append simulation suffix (e.g., :FAILED, :PENDING) to simulate different states.

Request body

wallet_addressstring nullable

Wallet address for a crypto transaction.

For withdrawal requests, this is the external destination wallet and cannot be provided together with external_account_id. Transaction responses expose the actual on-chain origin in source.wallet_address and the receiving wallet in destination.wallet_address.

Examples

  • Wallet Address 0x71a6c6be0be5f28ef4ea7541749d90d9c66fec7d
external_account_idstring nullable

External account ID for fiat withdrawals

Required for fiat currency withdrawals (e.g., USD, MXN). Identifies the external bank account used for the transfer. Cannot be provided together with wallet_address.

Examples

  • External Account ID ffb9e832-8e64-11f0-b308-2eaa4f6974f2
amountstring required

Amount to withdraw

assetstring required
  • Stablecoin assets: USDC, USDT, PYUSD, RLUSD, USDG, USDP, EURC, MXNB, 1USD(1USD/USDC conversion only, deposit/withdrawal not supported)
  • Digital assets: BTC, ETH, SOL
  • Fiat currencies: USD, MXN
networkstring required

Public network identifier for bank, blockchain and internal transactions.

Allowed values:

  • Bank: US_ACH, US_FEDWIRE, US_RTP, US_FEDNOW, SWIFT, CUBIX, SPEI, PIX_TRANSFER, LOCAL_BANK_TRANSFER, CHATS, FPS, SEPA, FASTER_PAYMENT, UAEFTS, UPI, EREBOR_RAIL
  • Blockchain: ETHEREUM, POLYGON, ARBITRUM, AVALANCHE, BASE, BNBCHAIN, SOLANA, TRON, ONE_MONEY, BITCOIN
  • Internal: INTERNAL

Availability depends on the asset and customer account configuration.

purpose_codestring nullable

Purpose code for a fiat withdrawal.

Some fiat withdrawals require a purpose code. Select the complete canonical value from the Local Payment Code guide based on the destination country and network. Submit it exactly as documented, including the country and network prefix; do not add, remove, or modify the prefix.

For example, a business-to-business USD SWIFT withdrawal to China requires a code such as cn_swift_cgoddr.

memorandumstring nullable

A string representing the message about the fiat transaction. Values longer than 256 characters are truncated.

mode'prefunding' | 'null' nullable

Withdrawal mode. Set to prefunding to fund the withdrawal from the main account on behalf of the customer specified in on_behalf_of.

on_behalf_ofstring nullable

The customer ID to execute the withdrawal on behalf of. Required when mode is prefunding. The customer must belong to the same entity as the API key owner.

amount_type'SEND_AMOUNT' | 'RECEIVE_AMOUNT' | 'null' nullable

Controls how the fee is applied to the withdrawal amount.

  • SEND_AMOUNT (default): Fee is deducted from the amount. Amount = what leaves the sender.
  • RECEIVE_AMOUNT: Fee is added on top. Amount = what the recipient gets.

Example request

{
  "wallet_address": "0x71a6c6be0be5f28ef4ea7541749d90d9c66fec7d",
  "external_account_id": "2e92e758-893e-11f0-b308-2eaa4f6974f2",
  "amount": "200",
  "asset": "USDC",
  "network": "ETHEREUM",
  "purpose_code": "cn_swift_remtdr",
  "memorandum": "first transaction",
  "mode": "prefunding",
  "amount_type": "SEND_AMOUNT"
}

Response

wallet_addressstring nullable

Wallet address for a crypto transaction.

For withdrawal requests, this is the external destination wallet and cannot be provided together with external_account_id. Transaction responses expose the actual on-chain origin in source.wallet_address and the receiving wallet in destination.wallet_address.

Examples

  • Wallet Address 0x71a6c6be0be5f28ef4ea7541749d90d9c66fec7d
external_account_idstring nullable

External account ID for fiat withdrawals

Required for fiat currency withdrawals (e.g., USD, MXN). Identifies the external bank account used for the transfer. Cannot be provided together with wallet_address.

Examples

  • External Account ID ffb9e832-8e64-11f0-b308-2eaa4f6974f2
amountstring required

Amount to withdraw

assetstring required
  • Stablecoin assets: USDC, USDT, PYUSD, RLUSD, USDG, USDP, EURC, MXNB, 1USD(1USD/USDC conversion only, deposit/withdrawal not supported)
  • Digital assets: BTC, ETH, SOL
  • Fiat currencies: USD, MXN
networkstring required

Public network identifier for bank, blockchain and internal transactions.

Allowed values:

  • Bank: US_ACH, US_FEDWIRE, US_RTP, US_FEDNOW, SWIFT, CUBIX, SPEI, PIX_TRANSFER, LOCAL_BANK_TRANSFER, CHATS, FPS, SEPA, FASTER_PAYMENT, UAEFTS, UPI, EREBOR_RAIL
  • Blockchain: ETHEREUM, POLYGON, ARBITRUM, AVALANCHE, BASE, BNBCHAIN, SOLANA, TRON, ONE_MONEY, BITCOIN
  • Internal: INTERNAL

Availability depends on the asset and customer account configuration.

purpose_codestring nullable

Purpose code for a fiat withdrawal.

Some fiat withdrawals require a purpose code. Select the complete canonical value from the Local Payment Code guide based on the destination country and network. Submit it exactly as documented, including the country and network prefix; do not add, remove, or modify the prefix.

For example, a business-to-business USD SWIFT withdrawal to China requires a code such as cn_swift_cgoddr.

memorandumstring nullable

A string representing the message about the fiat transaction. Values longer than 256 characters are truncated.

mode'prefunding' | 'null' nullable

Withdrawal mode. Set to prefunding to fund the withdrawal from the main account on behalf of the customer specified in on_behalf_of.

on_behalf_ofstring nullable

The customer ID to execute the withdrawal on behalf of. Required when mode is prefunding. The customer must belong to the same entity as the API key owner.

amount_type'SEND_AMOUNT' | 'RECEIVE_AMOUNT' | 'null' nullable

Controls how the fee is applied to the withdrawal amount.

  • SEND_AMOUNT (default): Fee is deducted from the amount. Amount = what leaves the sender.
  • RECEIVE_AMOUNT: Fee is added on top. Amount = what the recipient gets.
transaction_idstring required

Unique transaction identifier

idempotency_keystring required

HTTP Idempotency-Key header value. Stricter than other IDs: ≤64 ASCII chars per the common REST API convention.

status'PENDING' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'MICRO_DEPOSIT_REVERSED' required
transaction_action'WITHDRAWAL' required
created_atstring required
modified_atstring required
referencestring nullable

Transaction reference: on-chain tx hash (crypto) or UETR (fiat)

funder_pidstring

Portfolio ID — also exposed as customer_id in OpenAPI. Identifies one individual application / portfolio row within an entity.

funder_account_idstring nullable
recipient_idstring nullable

Recipient ID for third-party payouts. Present only when this withdrawal targets a recipient (cpid is non-empty); absent for self-withdrawals.

Example response

{
  "wallet_address": "0x71a6c6be0be5f28ef4ea7541749d90d9c66fec7d",
  "external_account_id": "2e92e758-893e-11f0-b308-2eaa4f6974f2",
  "amount": "200",
  "asset": "USDC",
  "network": "ETHEREUM",
  "purpose_code": "cn_swift_remtdr",
  "memorandum": "first transaction",
  "mode": "prefunding",
  "amount_type": "SEND_AMOUNT",
  "transaction_id": "c4e985bc-8b35-11f0-b308-2eaa4f6974f2",
  "action_required": {
    "type": "RFI",
    "case_id": "TC-WXYZ-2345",
    "action": "SUBMIT_INFORMATION"
  },
  "transaction_fee": {
    "value": "10.55",
    "asset": "USDC"
  },
  "platform_fee": {
    "value": "10.55",
    "asset": "USDC"
  },
  "partner_fee": {
    "value": "10.55",
    "asset": "USDC"
  },
  "created_at": "2025-08-21T07:56:57.981Z",
  "modified_at": "2025-08-21T07:56:57.981Z",
  "funder_pid": "14f20ebd-893b-11f0-b308-2eaa4f6974f2",
  "funder_account_id": "BZ-A2C4-9XPN",
  "recipient_id": "f77a8df1-a2b3-4c5d-9e8f-1234567890ab"
}

Changes

  • d213edbaccb6Revision changes
    • warning

      removed the request property /

    • warning

      removed the optional property ///// from the response with the status

    • warning

      added the new MICRO_DEPOSIT_REVERSED enum value to the / response property for the response status

    • warning

      added the new undefined enum value to the ///// response property for the response status

    • warning

      added the new undefined enum value to the ///// response property for the response status

    • info

      api tag crate::connectivity::controller::openapi::withdrawals added

    • info

      api tag Withdrawals removed

    • info

      added the new optional request property /

    • info

      added the new undefined enum value to the request property /

    • info

      added the new undefined enum value to the request property /

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property / to the response with the status