Sign in

v1

latestOpenAPI 3.0.32026-07-2650226215.9 KB
CashIns

Create a cash-in deposit code

Creates a cash-in: reserves a deposit code the customer presents at a physical cash location to deposit fiat, which is then converted to crypto and credited to the destination wallet. The 201 response includes the cash-in and its deposit instructions (the code and its expiry). Pass an Idempotency-Key header to safely retry without creating duplicates.

post/cash-ins

Headers

Idempotency-Keystring required

Required on POST and PUT requests. Use a unique value per logical mutation attempt, for example a UUID.

Request body

customerIdstring required

The customer depositing cash (cst_ prefix).

sponsorGasboolean

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

metadataobject

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

Example request

{
  "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
  "source": {
    "asset": "usd",
    "indicatedAmount": "200.00"
  },
  "destination": {
    "asset": "usdc",
    "network": "polygon",
    "wallet": {
      "id": "wlt_5h4jzzpr9xre3bamd9ca7qyghn"
    }
  },
  "cash": {
    "locationId": "loc_01H9Xd",
    "locationReference": "R1JFRU5ET1QtMjQzNA=="
  },
  "sponsorGas": true,
  "metadata": {
    "orderId": "order_12345"
  }
}

Response

The request has succeeded and a new resource has been created as a result.

idstring required

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

object'cashIn'

Resource type discriminator. Always "cashIn".

type'cryptoToCrypto' | 'fiatToCrypto' | 'cryptoToFiat' required

Direction of value across rails: cryptoToCrypto, fiatToCrypto, or cryptoToFiat. Retained for resources not yet on the SourceToDestination shape (onramp/cash-in, customer filters).

status'pending' | 'processing' | 'completed' | 'failed' | 'expired' required

Lifecycle of a cash-in. pending: code issued, awaiting deposit. processing: cash deposited, conversion underway. completed: converted and delivered. failed: the deposit or conversion did not succeed. expired: the code expired before any deposit.

subStatus'order_reserved' | 'settled' | 'cash_deposit_expired' | 'cash_deposit_failed' | 'provider_order_failed' | 'provider_order_template_error'

Granular sub-status for a cash-in. Adds detail behind the coarse status field.

customerIdstring required

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

fixedAmountSide'source' | 'destination'

The side the amount was fixed on when creating the cash-in. OMS calculated the other side.

sponsorGasCoststring

USD cost of gas absorbed by the developer when sponsoring gas. Always "0" in alpha; gas is sponsored.

transactionIdstring

Public TypeID, e.g. txn_01h455vb4pex5vsknk084sn02q; legacy UUID suffixes are accepted until non-v7 rows are retired.

sponsorGasboolean

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

metadataobject

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

createdAtstring date-time required

When the cash-in was created.

updatedAtstring date-time required

When the cash-in was last updated.

completedAtstring date-time

When the cash-in reached a terminal state. Null while in progress.

Example response

{
  "id": "ci_44vxe2xk8gfsjehfcw3npt5bg8",
  "object": "cashIn",
  "type": "fiatToCrypto",
  "status": "pending",
  "subStatus": "order_reserved",
  "customerId": "cst_vfa0nxw6zvyws9g237jrxn4y7k",
  "source": {
    "asset": "usd",
    "indicatedAmount": "200.00",
    "amountGross": "200.00",
    "amountNet": "200.00",
    "feesDeducted": {
      "total": "0.00",
      "developer": "0.00",
      "oms": "0.00",
      "gas": "0.00"
    }
  },
  "destination": {
    "asset": "usdc",
    "network": "polygon",
    "amountGross": "200.00",
    "amountNet": "200.00",
    "feesDeducted": {
      "total": "0.00",
      "developer": "0.00",
      "oms": "0.00",
      "gas": "0.00"
    },
    "wallet": {
      "id": "wlt_5h4jzzpr9xre3bamd9ca7qyghn",
      "blockchainAddress": "0x7B3a9F2c4D1eA8bF6390cE5d2B7fA104C8e3D9b1"
    }
  },
  "cash": {
    "locationId": "loc_01H9Xd",
    "locationReference": "R1JFRU5ET1QtMjQzNA=="
  },
  "location": {
    "name": "CVS Pharmacy #4521",
    "address": "123 Main St, San Francisco, CA 94105"
  },
  "rates": {
    "pair": "usd/usdc",
    "exchangeRate": "1.0000",
    "effectiveRate": "1.0000"
  },
  "depositInstructions": {
    "code": "483 291",
    "expiresAt": "2026-05-15T18:32:48Z",
    "locationName": "CVS Pharmacy #4521",
    "locationAddress": "123 Main St, San Francisco, CA 94105"
  },
  "fixedAmountSide": "source",
  "sponsorGas": true,
  "sponsorGasCost": "0",
  "createdAt": "2026-05-15T17:32:48Z",
  "updatedAt": "2026-05-15T17:32:48Z"
}