---
title: "Create a cash-in deposit code"
method: POST
path: "/cash-ins"
tags: ["CashIns"]
---

# Create a cash-in deposit code

`POST /cash-ins`

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.

## Headers

- `Idempotency-Key` string, required

## Request body

- CreateCashInRequest — Request body for creating a cash-in. Names the customer, the cash source location, and the crypto destination.
  - `customerId` string, required — The customer depositing cash (`cst_` prefix).
  - `source` CashInSource, required — Cash side of a cash-in: the fiat asset and amounts.
    - `asset` string, required — Canonical asset identifier.
    - `network` string — Network identifier.
    - `email` string — Email address.
    - `indicatedAmount` string — The cash amount the customer indicated they will deposit.
    - `amount` string — Amount as a decimal string.
    - `amountGross` string — Amount on this side before fees are applied.
    - `amountNet` string — Amount after fees - what is actually pulled from a source, or delivered to a destination.
    - `feesDeducted` FeesDeducted — Per-side breakdown of fees deducted in-line from the transaction. End-of-month billable fees will be reported separately in the future (planned `feesInvoice` sibling). Denominated in that side's asset.
      - `total` string, required
      - `developer` string, required — Per-side aggregated developer fee total in this side's asset. Always "0" in alpha - alpha invariant, mirrors the gas line.
      - `oms` string, required
      - `gas` string, required
  - `destination` CashInDestination, required — The crypto destination a cash-in is converted to and delivered to.
    - `wallet` CashInDestinationWallet — The wallet receiving the converted funds.
      - `id` string — Public TypeID, e.g. `txn_01h455vb4pex5vsknk084sn02q`; legacy UUID suffixes are accepted until non-v7 rows are retired.
      - `externalAccount` string — Registered External Account receiving the funds, when applicable.
      - `blockchainAddress` string — On-chain address.
    - `asset` string — Canonical asset identifier.
    - `network` string — Network identifier.
    - `amountGross` string — Amount on this side before fees are applied.
    - `amountNet` string — Amount after fees - what is actually pulled from a source, or delivered to a destination.
    - `feesDeducted` FeesDeducted — Per-side breakdown of fees deducted in-line from the transaction. End-of-month billable fees will be reported separately in the future (planned `feesInvoice` sibling). Denominated in that side's asset.
      - `total` string, required
      - `developer` string, required — Per-side aggregated developer fee total in this side's asset. Always "0" in alpha - alpha invariant, mirrors the gas line.
      - `oms` string, required
      - `gas` string, required
  - `cash` CashInfo, required — The retail location chosen for the deposit, by ID and provider reference.
    - `locationId` string, required — Cash location ID from `GET /cash-locations`.
    - `locationReference` string, required — Provider reference for the location, from `GET /cash-locations`.
  - `sponsorGas` boolean — When `true`, OMS absorbs the on-chain gas cost for the destination delivery. Only `true` is currently supported.
  - `metadata` object — Free-form key-value pairs stored on the resource and echoed back on reads.

## Response `201`

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

- CashIn — A code-based cash deposit. The customer takes the issued code to a retail location and deposits cash, which OMS converts to crypto and delivers to the destination. Amounts start as estimates and are finalized once the cash is deposited.
  - `id` string, 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.
  - `customerId` string, 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.
  - `source` CashInSource, required — Cash side of a cash-in: the fiat asset and amounts.
    - `asset` string, required — Canonical asset identifier.
    - `network` string — Network identifier.
    - `email` string — Email address.
    - `indicatedAmount` string — The cash amount the customer indicated they will deposit.
    - `amount` string — Amount as a decimal string.
    - `amountGross` string — Amount on this side before fees are applied.
    - `amountNet` string — Amount after fees - what is actually pulled from a source, or delivered to a destination.
    - `feesDeducted` FeesDeducted — Per-side breakdown of fees deducted in-line from the transaction. End-of-month billable fees will be reported separately in the future (planned `feesInvoice` sibling). Denominated in that side's asset.
      - `total` string, required
      - `developer` string, required — Per-side aggregated developer fee total in this side's asset. Always "0" in alpha - alpha invariant, mirrors the gas line.
      - `oms` string, required
      - `gas` string, required
  - `destination` CashInDestination, required — The crypto destination a cash-in is converted to and delivered to.
    - `wallet` CashInDestinationWallet — The wallet receiving the converted funds.
      - `id` string — Public TypeID, e.g. `txn_01h455vb4pex5vsknk084sn02q`; legacy UUID suffixes are accepted until non-v7 rows are retired.
      - `externalAccount` string — Registered External Account receiving the funds, when applicable.
      - `blockchainAddress` string — On-chain address.
    - `asset` string — Canonical asset identifier.
    - `network` string — Network identifier.
    - `amountGross` string — Amount on this side before fees are applied.
    - `amountNet` string — Amount after fees - what is actually pulled from a source, or delivered to a destination.
    - `feesDeducted` FeesDeducted — Per-side breakdown of fees deducted in-line from the transaction. End-of-month billable fees will be reported separately in the future (planned `feesInvoice` sibling). Denominated in that side's asset.
      - `total` string, required
      - `developer` string, required — Per-side aggregated developer fee total in this side's asset. Always "0" in alpha - alpha invariant, mirrors the gas line.
      - `oms` string, required
      - `gas` string, required
  - `cash` CashInfo, required — The retail location chosen for the deposit, by ID and provider reference.
    - `locationId` string, required — Cash location ID from `GET /cash-locations`.
    - `locationReference` string, required — Provider reference for the location, from `GET /cash-locations`.
  - `location` CashInLocation, required — Resolved retail location detail.
    - `name` string — Display name.
    - `address` string — Postal address.
  - `depositInstructions` CashInDepositInstructions — The deposit code and retail location a customer uses to complete a cash-in.
    - `code` string, required — Machine-readable code.
    - `expiresAt` string, date-time, required — Expiration time.
    - `locationName` string — Display name of the retail location.
    - `locationAddress` string — Street address of the retail location.
  - `rates` Rates — Exchange and effective rates.
    - `pair` string, required — Asset pair string, e.g. "usdc/usd".
    - `exchangeRate` string, required — Units of destination asset per 1 unit of source asset.
    - `effectiveRate` string, required — All-in rate inclusive of all fees on both sides.
  - `sponsorGasCost` string — USD cost of gas absorbed by the developer when sponsoring gas. Always "0" in alpha; gas is sponsored.
  - `omsFeeSchedule` OmsFeeSchedule — The OMS fee lines applied, denominated in `feeCurrency`.
    - `feeCurrency` string, required — Currency the fee lines are denominated in.
    - `entries` OmsFeeEntry[], required — Individual fee lines.
      - `type` string, required — Type discriminator.
      - `rate` string — Fee rate as a decimal.
      - `amount` string — Amount as a decimal string.
  - `transactionId` string — Public TypeID, e.g. `txn_01h455vb4pex5vsknk084sn02q`; legacy UUID suffixes are accepted until non-v7 rows are retired.
  - `sponsorGas` boolean — When `true`, OMS absorbs the on-chain gas cost for the destination delivery. Only `true` is currently supported.
  - `metadata` object — Free-form key-value pairs supplied at creation or update.
  - `developerFees` FeeEntry[] — Developer fee entries echoed back from the request. Omitted in alpha. The field stays on the schema so it can be reintroduced without a breaking change when developer fees ship.
    - `id` string — Unique identifier assigned by OMS. Present on responses only.
    - `percentage` string — Percentage fee as a decimal rate. "0.02" = 2%.
    - `flatFee` string — Fixed fee in USD. Converted to fee-side asset at the exchange rate.
    - `amount` string — Computed fee amount for this entry. Present on responses only.
    - `payoutAsset` 'usdc' | 'usdt' — Crypto asset for fee payout. Defaults to "usdc".
    - `wallet` string — OMS wallet to receive this fee.
  - `createdAt` string, date-time, required — When the cash-in was created.
  - `updatedAt` string, date-time, required — When the cash-in was last updated.
  - `completedAt` string, date-time — When the cash-in reached a terminal state. Null while in progress.

---

[API](https://skmtc.net/polygon-technology/apis/polygon-oms-public-api.md) · [All operations](https://skmtc.net/polygon-technology/apis/polygon-oms-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/polygon-technology/polygon-oms-public-api/revisions/18fdaebf64e5/schema)