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 ($ 1,000 at Walmart 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

{
  "id": "ci_...",
  "object": "cashIn",
  "type": "fiatToCrypto",
  "status": "pending",
  "customerId": "cst_...",
  "source": {
    "asset": "usd",
    "indicatedAmount": "100.00",
    "amountGross": "100.00",
    "amountNet": "99.42",
    "feesDeducted": { "total": "0.58" }
  },
  "destination": {
    "asset": "usdc",
    "network": "polygon",
    "amountGross": "99.42",
    "amountNet": "99.42",
    "wallet": { "id": "wlt_..." }
  },
  "cash": { "locationId": "loc_...", "locationReference": "loc-ref-4521" },
  "location": { "name": "Retail Partner #4521", "address": "123 Main St, New York, NY 10001" },
  "rates": { "exchangeRate": "1.00", "effectiveRate": "0.9942", "pair": "usd/usdc" },
  "depositInstructions": {
    "code": "483291",
    "expiresAt": "2026-01-15T11:30:00Z",
    "locationName": "Retail Partner #4521",
    "locationAddress": "123 Main St, New York, NY 10001"
  },
  "sponsorGas": true,
  "sponsorGasCost": "0",
  "transactionId": null,
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}

Display the depositInstructions.code in your UI. When you pass an indicatedAmount, the source and destination amounts carry the estimated figures and fees so you can show the customer what to expect before they visit the location. Amounts start as estimates and are finalized once the cash is deposited. The created transaction’s ID appears on transactionId once the deposit is made.

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. If it expires before the customer deposits, refresh it via POST /cash-ins/{cashInId}/refresh: there is no need to create a new cash-in.

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.
`expired`	Code expired before a deposit was made.

The subStatus field adds granular detail behind these values, for example order_reserved, settled, cash_deposit_expired, cash_deposit_failed, provider_order_failed, and provider_order_template_error.

Cash-in operations

Operation	Endpoint
Create a cash-in	`POST /cash-ins`
Refresh deposit code	`POST /cash-ins/{cashInId}/refresh`
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)

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 (walletOms → 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 and limit, and a flow of cash_in or cash_out to select the provider configuration. Each location returns its distance from the supplied coordinates, and each provider returns its per-transaction and per-customer daily limits.

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 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 operations

Simulating a cash-in (sandbox)

Cash-out

Cash-out limits

Cash-out flow

Supported locations

Related