Create a payment order

​

Declare a payment order — "send X of asset Y to address Z on chain C." fromUserId must be the system user id returned by the user endpoints, not the user label. TBMC validates the recipient wallet, sender KYB status, and amount, then returns the funding wallet for the inbound asset/chain. Once the inbound transfer lands on-chain, the order moves through its lifecycle (FUNDED → LOCKED → … → DISTRIBUTED) and TBMC delivers the requested outbound asset at par. Pricing is a fixed fee — not slippage.

Both settlement modes take the same body. Omit mode — or pass "standard" — to settle in the next netting window. For an instant payment, pass mode: "instant" with the quoteId from POST /quotes; this requires the instant payment capability on your account. An instant order returns a deposit address for every asset your account supports, or 503 if any of them is momentarily unavailable — the payout destination accepts exactly the assets listed, so a partial set would refuse a later deposit. Retry on 503.

To create the order under one of your subaccounts, pass subaccountId. An instant order takes its account from the quote it cites, so pass subaccountId to POST /quotes instead — sending one here is rejected with a 400 rather than ignored.

Body
required
application/json
  • amountUsd
    Type: number
    greater than:  
    0
    multiple of:  
    0.0001
    required

    Positive USD amount at up to 4 decimal places (one pip = $0.0001).

  • asset
    Type: string
    required
  • fromUserId
    Type: string
    required

    System user id returned by the user endpoints. Do not pass the user label.

  • toAddress
    Type: string
    required
  • toChain
    Type: string
    required
  • expiresAt
    Type: string Format: date-time

    When the order stops accepting funds. Required for standard, not accepted for instant — an instant order gets a server-set funding window.

  • idempotencyKey
    Type: string
    min length:  
    1
    max length:  
    255
  • memo
    Type: string
  • mode
    Type: string enum

    Settlement mode. Omit — or pass standard — to settle in the next netting window.

    values
    • standard
    • instant
  • quoteId
    Type: string

    The quote this order settles against, from POST /quotes. Required for instant, not accepted for standard.

  • subaccountId
    Type: string Format: uuid

    Create this under one of your subaccounts instead of the authenticated account. Must be a direct child of the authenticated account.

Responses
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/api/v1/payment
curl https://api.bettermoney.com/api/v1/payment \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "fromUserId": "9f8c1b7e-5d3a-4c21-9a6f-1e2d3c4b5a60",
  "toAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "toChain": "ethereum",
  "asset": "USDC",
  "amountUsd": 250,
  "memo": "invoice 1042",
  "expiresAt": "2026-08-01T00:00:00Z"
}'

{
  "paymentOrderId": "string",
  "paymentOrder": {
    "id": "string",
    "mode": "standard",
    "senderAccountId": "123e4567-e89b-12d3-a456-426614174000",
    "fromUserId": null,
    "status": "AWAITING_FUNDS",
    "version": -9007199254740991,
    "asset": "string",
    "toChain": "string",
    "toAddress": "string",
    "amountUsd": 1,
    "memo": null,
    "idempotencyKey": "string",
    "payoutDestinationId": "123e4567-e89b-12d3-a456-426614174000",
    "instantFeeBps": 0,
    "createdAt": "2026-08-21T21:35:19.761Z",
    "expiresAt": "2026-08-21T21:35:19.761Z",
    "receivedTotal": 0,
    "inboundTransfers": [
      {
        "sender": "string",
        "amountUsd": 0,
        "chain": "string",
        "asset": "string",
        "transactionHash": "string",
        "observedAt": "2026-08-21T21:35:19.761Z",
        "status": "PENDING_VERIFICATION",
        "version": -9007199254740991,
        "refundReference": "string",
        "refundTransactionHash": "string"
      }
    ],
    "canceledAt": "2026-08-21T21:35:19.761Z",
    "cancelReason": "string",
    "cancelRequestedAt": "2026-08-21T21:35:19.761Z",
    "refundReason": "string",
    "refundedAt": "2026-08-21T21:35:19.761Z",
    "refundTransactionHash": "string",
    "distributionReference": "string",
    "settlementReference": "string",
    "distributionTransactionHash": "string",
    "distributionExecutedAt": "2026-08-21T21:35:19.761Z",
    "settledAt": "2026-08-21T21:35:19.761Z",
    "underfundToleranceUsd": 1
  },
  "depositAddresses": [
    {
      "chain": "string",
      "symbol": "string",
      "address": "string"
    }
  ]
}

Default Response