Cash-ins and cash-outs - Polygon Developer Docs

OMS supports two complementary in-person cash flows:

Cash-in: the customer deposits physical cash at a retail location and receives crypto in the destination wallet.
Cash-out (cash pickup): the customer withdraws crypto from a wallet and collects physical cash at a retail counter or ATM.

Both flows hand off a code at a partner retail location. Cash-in skips the upfront quote step; cash-out uses a standard quote with a cash destination. Both require the usd endorsement on the customer.

Cash-in

A cash-in is an in-person cash deposit flow. You create a cash-in that reserves a deposit code. The customer takes that code to a partner retail location, deposits cash, and OMS automatically converts it to crypto and delivers it to the destination wallet (cashToCrypto). Cash-ins skip the quote step: the customer decides how much to deposit at the counter, so no amount is fixed at creation. Pass an indicatedAmount on the source for an upfront pricing estimate.

Cash-in limits

Limit	Value
Transaction minimum	$20
Transaction maximum	$500 (higher at some locations; read `maxTransaction` from cash locations)
Daily maximum	$1,500 and 3 transactions
Weekly maximum	$3,500 and 12 transactions
Monthly maximum	$5,000 and 20 transactions

Create a cash-in

POST /cash-ins. The request names the customer, the cash source location, and the crypto destination.

{
  "customerId": "cst_...",
  "cash": {
    "locationId": "loc_...",
    "locationReference": "loc-ref-4521"
  },
  "source": {
    "asset": "usd",
    "indicatedAmount": "100.00",
    "email": "jane@example.com"
  },
  "destination": {
    "asset": "usdc",
    "network": "polygon",
    "wallet": { "id": "wlt_..." }
  },
  "sponsorGas": true
}

Field	Shape
`cash`	The deposit location: `locationId` and `locationReference`, both required. Read these from cash locations.
`source`	Cash side: `asset` (required, `usd`), optional `indicatedAmount` for the pricing estimate, and optional `email`.
`destination`	Crypto side: `asset`, `network`, and a `wallet` reference (`id`, `blockchainAddress`, or `externalAccount`).
`sponsorGas`	Cover network gas on the customer’s behalf.

Pass an Idempotency-Key header to safely retry without creating duplicates.

Cash-in object

The response, every GET, every list entry, and every cashIn.* webhook payload return the same shape:

{
  "id": "ci_44vxe2xk8gfsjehfcw3npt5bg8",
  "status": "pending",
  "customer": { "id": "cst_..." },
  "source": {
    "type": "cash",
    "asset": "usd",
    "details": {
      "locationId": "loc_01H9Xd",
      "locationName": "Retail Partner #4521",
      "locationAddress": {
        "line1": "123 Main St",
        "city": "New York",
        "state": "NY",
        "zipCode": "10001",
        "country": "US"
      }
    }
  },
  "destination": {
    "type": "walletCrypto",
    "id": "wlt_5h4jzzpr9xre3bamd9ca7qyghn",
    "asset": "usdc",
    "network": "polygon",
    "details": { "address": "0xabc...def" }
  },
  "pricing": {
    "source":      { "amount": "100.00",     "asset": "usd" },
    "destination": { "amount": "99.420000",  "asset": "usdc" },
    "fees": [
      { "type": "oms", "amount": "0.58", "asset": "usd", "side": "source" }
    ],
    "exchangeRate": "1.00",
    "fixedAmountSide": "source",
    "sponsorGas": true
  },
  "depositInstructions": { "cashInCode": "483291" },
  "expiresAt": "2026-10-16T11:30:00.000Z",
  "createdAt": "2026-10-16T10:30:00.000Z",
  "updatedAt": "2026-10-16T10:30:00.000Z"
}

Field	Shape
`source`	A `cash` instrument. `details.locationId`, `details.locationName`, and `details.locationAddress` (a postal address object) identify the retail location the customer deposits at, and `details.locationProvider` names the cash network the location belongs to. No email is carried on the cash-in; identify the customer through `customer.id`.
`destination`	The customer’s wallet as a typed instrument. `walletCrypto` when the destination was created from an OMS wallet by ID (carries the wallet `id` and its on-chain `details.address`); `walletExternal` when the destination was given as an on-chain address or an external account, with the address under `details.address` and the external account (`ext_`) as `id` when there is one.
`depositInstructions`	Always present. Carries only `cashInCode`, the code the customer presents at the retail location.
`expiresAt`	Always present. The deposit code is valid until this time. `POST /cash-ins/{cashInId}/refresh` issues a new `cashInCode` but does not extend `expiresAt`.
`failure`	Present only when `status` is `failed`. Carries a `code`, `message`, and `retryable` flag.
`transactionId`	The auto-created transaction, once the cash is deposited. Omitted before then.
`completedAt`	Present only when `status` is `completed`.
`pricing`	Shared pricing shape, including `fixedAmountSide`; see transactions pricing shape.

Display the depositInstructions.cashInCode in your UI. When you pass an indicatedAmount on create, pricing carries the estimated source and destination amounts and the fee breakdown so you can show the customer what to expect before they visit the location. The estimate is finalized once the cash is deposited; if the amount deposited differs from the amount priced on, pricing carries only the cash actually deposited on the source side, because the estimated destination, fees, and rate no longer describe the cash-in. The created transaction’s ID appears on transactionId once the deposit is made. Amounts in pricing are decimal strings padded to each asset’s precision (two decimals for usd, six for usdc). See the transactions pricing shape for the shared model.

Cash-in flow

POST /cash-ins  →  deposit code (valid 1 hour)
                      │
      customer deposits cash at retail location
                      │
              OMS converts to crypto
                      │
              status → completed

The deposit code is valid for one hour. POST /cash-ins/{cashInId}/refresh issues a new code for a cash-in that has not expired, but it does not extend expiresAt. Once expiresAt passes, the refresh fails with 422 RefreshExpired; create a new cash-in instead.

Cash-in status

Status	Meaning
`pending`	Deposit code issued, awaiting the customer’s deposit.
`processing`	Cash deposited; conversion underway.
`completed`	Cash converted and crypto delivered.
`failed`	The deposit or conversion did not succeed. The `failure` object identifies the cause.
`expired`	Code expired before a deposit was made.
`cancelled`	Cancelled before the code was scanned, superseded by a new cash-in, or voided by the cashier after the scan but before the cash was loaded.

A cash-in has no subStatus; branch on status alone. Detail about a failure lives in the failure object, and the auto-created transaction’s own status and sub-status carry conversion progress after the deposit lands.

Cash-in webhook events

Event	Fires when
`cashIn.created`	A new cash-in was created (`status: pending`).
`cashIn.statusChanged`	The cash-in’s status changed, for example to `processing`, `completed`, `failed`, `expired`, or `cancelled`. `previousStatus` names the status it left. Once the cash is deposited, `transactionId` links the auto-created transaction.
`cashIn.updated`	A field changed without a status change. Refreshing the deposit code fires `cashIn.updated` with `changedFields: ["depositInstructions"]` carrying the new `cashInCode`; `status` and `expiresAt` do not change on a refresh.

Each payload is the full cash-in object described above. Subscribe to the cashIn.* events alongside transaction.statusChanged to receive both the cash-in’s own lifecycle events and the auto-created transaction’s events.

Cash-in operations

Operation	Endpoint
Create a cash-in	`POST /cash-ins`
Refresh deposit code	`POST /cash-ins/{cashInId}/refresh`
Cancel a pending cash-in	`POST /cash-ins/{cashInId}/cancel`
Get a cash-in	`GET /cash-ins/{cashInId}`
List cash-ins	`GET /cash-ins` (filter by customer, status, type, date range, or free-text search)

GET /cash-ins returns results newest first. Page with limit, startingAfter, and endingBefore: pass the previous page’s nextCursor as startingAfter while hasMore is true. POST /cash-ins/{cashInId}/cancel cancels a cash-in that is still pending. The deposit code stops working and the cash-in becomes cancelled once the provider confirms it deleted the code. If the customer scans the code while the cancel is in flight, the request fails with 409 CashInAlreadyScanned; if the code had already expired, it fails with 409 CashInExpired. A cash-in that is processing or final fails with 409 CashInNotCancellable. Pass an Idempotency-Key header to retry safely.

Simulating a cash-in (sandbox)

In sandbox, drive a cash-in through its lifecycle without a real deposit using the simulation endpoints. Each endpoint is scoped to a specific cash-in by ID and returns 404 in production.

Operation	Endpoint
Simulate presenting the deposit code at the register	`POST /cash-ins/{cashInId}/simulate/present-code`
Complete the authorized deposit	`POST /cash-ins/{cashInId}/simulate/deposit-cash`
Cancel an authorized deposit	`POST /cash-ins/{cashInId}/simulate/cancel`

Cash-out

A cash-out (cash pickup) is the inverse of a cash-in: the customer holds crypto in an OMS wallet and withdraws it as physical cash. It uses a standard quote with a cash destination (cryptoToCash). OMS pulls crypto from the wallet, issues a time-limited pickup code, and the customer collects cash at a partner retail location. Set the amount on the destination side; it must be a multiple of $20.00, up to $400.00 per transaction.

Cash pickup is under active development and available through early access. To enable it for your project, contact us.

Request access

Share your use case and we’ll reach out about cash pickup.

Cash-out limits

Limit	Value
Transaction increment	Multiples of $20.00
Transaction minimum	$20
Transaction maximum	$400
Daily maximum	$1,000 in California and New Mexico; $2,000 in all other states
Monthly maximum	$60,000

Cash-out flow

POST /quotes (walletCrypto → cash, amount on destination)
        │
POST /transactions { quoteId }  →  OMS pulls crypto from the wallet
        │
   pickup code (time-limited)
        │
customer collects cash at retail location or ATM
        │
   subStatus processing.cashPickupReady → completed.cashPickupCollected

Supported locations

Cash deposits and withdrawals are processed through OMS’s partner retail and ATM network across the US. List nearby locations with GET /cash-locations, passing the provider, latitude, and longitude query parameters, an optional radius in miles (greater than 0, at most 100), and a flow of cash_in or cash_out to select the configuration. Pass customerId to return only locations the customer is eligible to use, based on their KYC country and, for US customers, their state. The response is a list envelope with locations in data, nearest first. Page with limit, startingAfter, and endingBefore. Each location carries its provider’s maxTransaction and maxDailyPerCustomer limits, an id and a cashLocationReference (pass them as locationId and locationReference when you create a cash-in, or as cashLocationId and cashLocationReference on a cash pickup quote), its distance from the supplied coordinates, and whether it supports deposits (buyAllowed) and withdrawals (sellAllowed).

Cash-in guide: full walkthrough with request and response
Cash pickup guide: the cash-out flow in detail
Transactions: standard two-step flow for card and bank transfers

​Cash-in

​Cash-in limits

​Create a cash-in

​Cash-in object

​Cash-in flow

​Cash-in status

​Cash-in webhook events

​Cash-in operations

​Simulating a cash-in (sandbox)

​Cash-out

Request access

​Cash-out limits

​Cash-out flow

​Supported locations

​Related

Cash-in

Cash-in limits

Create a cash-in

Cash-in object

Cash-in flow

Cash-in status

Cash-in webhook events

Cash-in operations

Simulating a cash-in (sandbox)

Cash-out

Cash-out limits

Cash-out flow

Supported locations

Related