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 request body: omit mode or pass "standard" to settle in the next netting window, or pass mode: "instant" with the quoteId from POST /quotes to settle instantly. Instant payments require 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

asset
Type: string
required

See https://docs.bettermoney.com/asset-support for supported values.
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

See https://docs.bettermoney.com/asset-support for supported values.
amountUsd
Type: number
greater than:
0
multiple of:
0.0001
deprecated

Deprecated: the amount as a JSON number, accepted only with feeCollection: "invoiced", where the deposit and the payout are the same. Send fundingAmountUsd or payoutAmountUsd instead.
beneficiary

Required when collection is enabled, the funding amount is $3,000 or more, and the sender and recipient are different users. Omit for exempt payments. See https://docs.bettermoney.com/travel-rule.
Required when collection is enabled, the funding amount is $3,000 or more, and the sender and recipient are different users. Omit for exempt payments. See https://docs.bettermoney.com/travel-rule.
dateOfBirth
Type: stringFormat: date
required

Individual beneficiary’s date of birth, YYYY-MM-DD. Must not be in the future.

familyName
Type: string
min length:
1
max length:
200
required

Individual beneficiary’s family name.

givenName
Type: string
min length:
1
max length:
200
required

Individual beneficiary’s given name.

isSelfHosted
Type: boolean
required

Whether the beneficiary controls the destination wallet without a wallet provider.

location
Type: object
required

Individual beneficiary’s country and subdivision of residence.

Properties: 2
type
enum
const:
individual
required
legalEntityIdentifier
Type: string
max length:
512

Legal entity identifier (LEI) of the wallet provider, not the beneficiary. Required for hosted wallets; omit or pass an empty string for self-hosted wallets. Find it with GET /travel-rule/vasps.
expiresAt
Type: stringFormat: date-time

When the order stops accepting funds. Required for standard, not accepted for instant — an Instant order gets a server-set funding window.
feeCollection
Type: "invoiced" or "deducted"enum

How TBMC’s fee is collected. invoiced (the default) bills it on the monthly invoice and the recipient receives the full amount. deducted takes it out of the payment: the recipient receives the funding amount minus the fee.
fundingAmountUsd
Type: string

What you will deposit, as a USD decimal string with up to 4 places. Under deducted the recipient receives this minus the fee.
idempotencyKey
Type: string
min length:
1
max length:
255
memo
Type: string
mode
Type: "standard" or "instant"enum

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

Responses

application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json

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"
}'

Show Schema

{
  "paymentOrderId": "string",
  "paymentOrder": {
    "returnDetailsReason": "RETURN_DETAILS_MISSING",
    "id": "string",
    "rulesetId": "123e4567-e89b-12d3-a456-426614174000",
    "mode": "standard",
    "senderAccountId": "123e4567-e89b-12d3-a456-426614174000",
    "fromUserId": null,
    "status": "AWAITING_FUNDS",
    "version": -9007199254740991,
    "asset": "string",
    "toChain": "string",
    "toAddress": "string",
    "fundingAmountUsd": "string",
    "payoutAmountUsd": "string",
    "feeUsd": "string",
    "feeBps": 0,
    "feeCollection": "invoiced",
    "memo": null,
    "idempotencyKey": "string",
    "payoutDestinationId": "123e4567-e89b-12d3-a456-426614174000",
    "instantFeeBps": 0,
    "quoteId": "string",
    "quoteFeeBps": 0,
    "estimatedSettlementAt": "2026-10-22T14:42:28.555Z",
    "createdAt": "2026-10-22T14:42:28.555Z",
    "expiresAt": "2026-10-22T14:42:28.555Z",
    "receivedTotal": 0,
    "inboundTransfers": [
      {
        "returnBlockReason": "RETURN_DETAILS_MISSING",
        "sender": "string",
        "amountUsd": 0,
        "chain": "string",
        "asset": "string",
        "transactionHash": "string",
        "observedAt": "2026-10-22T14:42:28.555Z",
        "status": "PENDING_VERIFICATION",
        "version": -9007199254740991,
        "refundReference": "string",
        "refundTransactionHash": "string"
      }
    ],
    "canceledAt": "2026-10-22T14:42:28.555Z",
    "cancelReason": "string",
    "cancelRequestedAt": "2026-10-22T14:42:28.555Z",
    "refundReason": "string",
    "refundedAt": "2026-10-22T14:42:28.555Z",
    "refundTransactionHash": "string",
    "distributionReference": "string",
    "settlementReference": "string",
    "distributionTransactionHash": "string",
    "distributionExecutedAt": "2026-10-22T14:42:28.555Z",
    "settledAt": "2026-10-22T14:42:28.555Z",
    "underfundToleranceUsd": 1
  },
  "depositAddresses": [
    {
      "chain": "string",
      "symbol": "string",
      "address": "string"
    }
  ]
}

Default Response

Notify of inbound transfer

List payment orders