> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crossmint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onramp with Cash App

> Create an onramp order that the buyer pays from Cash App by scanning a Solana Pay QR code

This guide covers how to create an onramp order that the buyer pays from Cash App. The order returns a Solana Pay link that you show as a QR code. The buyer scans it with Cash App and sends USDC on Solana to the order's deposit address. Crossmint then delivers USDC to the buyer's wallet.

<Snippet file="enterprise-feature.mdx" />

## Prerequisites

* **API Key**: A server-side API key with the `orders.create`, `orders.read`, and `orders.update` scopes. In staging, all scopes are included by default.
* **Verified buyer**: The buyer completes KYC before the order can take a Cash App payment. Crossmint links the KYC data to the order through `payment.receiptEmail`. See [User Onboarding](https://docs.crossmint.com/onramp/introduction/user-onboarding.md).
* **Recipient wallet**: The recipient is a wallet on Solana, Base, Polygon, Ethereum, or Arbitrum.
* **Refund address**: Crossmint does not know the buyer's Cash App address, so it cannot refund to Cash App. Ask the buyer for a Solana address that the buyer controls, and send it as `refundAddress`. The buyer always pays on Solana, so `refundAddress` is a Solana address for every delivery chain.

A Cash App order has one line item, delivers only USDC, and delivers at least 1 USDC.

## Create a Cash App Order

**1. Create the order**

Call [Create Order](https://docs.crossmint.com/onramp/api-reference/create-order.md) with these `payment` fields:

| Field | Value |
| - | - |
| `method` | `cashapp` |
| `currency` | `usd` |
| `network` | `solana` |
| `refundAddress` | The buyer's Solana address that receives a refund |

The examples deliver on Solana. To deliver on an EVM chain, set `tokenLocator` to USDC on that chain, for example `base-sepolia:0x036CbD53842c5426634e7929541eC2318f3dCF7e`, and set `walletAddress` to an EVM address.

```bash cURL theme={null}
curl -X POST 'https://staging.crossmint.com/api/2022-06-09/orders' \
  -H 'X-API-KEY: YOUR_SERVER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "recipient": {
      "walletAddress": "USER_SOLANA_WALLET_ADDRESS"
    },
    "lineItems": [
      {
        "tokenLocator": "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
        "executionParameters": {
          "mode": "exact-in",
          "amount": "10"
        }
      }
    ],
    "payment": {
      "method": "cashapp",
      "currency": "usd",
      "network": "solana",
      "refundAddress": "BUYER_REFUND_ADDRESS",
      "receiptEmail": "user@example.com"
    }
  }'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders", {
    method: "POST",
    headers: {
        "X-API-KEY": "YOUR_SERVER_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        recipient: { walletAddress: "USER_SOLANA_WALLET_ADDRESS" },
        lineItems: [
            {
                tokenLocator: "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
                executionParameters: { mode: "exact-in", amount: "10" },
            },
        ],
        payment: {
            method: "cashapp",
            currency: "usd",
            network: "solana",
            refundAddress: "BUYER_REFUND_ADDRESS",
            receiptEmail: "user@example.com",
        },
    }),
});
const { order } = await response.json();
```

```python Python theme={null}
import requests

response = requests.post(
    "https://staging.crossmint.com/api/2022-06-09/orders",
    headers={"X-API-KEY": "YOUR_SERVER_API_KEY", "Content-Type": "application/json"},
    json={
        "recipient": {"walletAddress": "USER_SOLANA_WALLET_ADDRESS"},
        "lineItems": [
            {
                "tokenLocator": "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU",
                "executionParameters": {"mode": "exact-in", "amount": "10"},
            }
        ],
        "payment": {
            "method": "cashapp",
            "currency": "usd",
            "network": "solana",
            "refundAddress": "BUYER_REFUND_ADDRESS",
            "receiptEmail": "user@example.com",
        },
    },
)
print(response.json())
```

This exact-in order specifies the amount to spend. The delivered quantity accounts for fees; read it from the completed order.

> [!WARNING]
>
> A refund goes to `refundAddress`, not to the buyer's Cash App account. Crossmint cannot change it after the order is created, so confirm the address with the buyer before you create the order.

**2. Show the QR code**

The response holds the payment details in `order.payment.preparation`:

```json Response (excerpt) theme={null}
{
  "order": {
    "orderId": "ORDER_ID",
    "phase": "payment",
    "quote": {
      "status": "valid"
    },
    "payment": {
      "status": "awaiting-payment",
      "method": "cashapp",
      "preparation": {
        "chain": "solana",
        "depositAddress": "7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV",
        "transactionParameters": {
          "amount": "10000000"
        },
        "paymentLink": "solana:7EcDhSYGxXyscszYEp35KHN8vvw3svAuLKTzXwCFLtV?amount=10&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
      }
    }
  }
}
```

* `depositAddress`: the address that receives the buyer's USDC.
* `transactionParameters.amount`: the amount to send, in USDC base units. `10000000` is 10 USDC.
* `paymentLink`: a Solana Pay `solana:` URI with the deposit address, the amount, and the USDC token.

Show `paymentLink` as a QR code. The buyer scans it with Cash App to pay. The three fields are present only while `quote.status` is `valid`.

**3. Track the order**

Poll [Get Order](https://docs.crossmint.com/onramp/api-reference/get-order.md) until `phase` is `completed`.

* Read the delivered quantity from `lineItems[].delivery.tokens[].quantity`. It can differ from the requested amount: a payment of a different amount is filled at a new price.
* The order can complete after `quote.status` is `expired`. A late payment still completes the order.
* If the payment is refunded, the refund goes to `refundAddress`.

## Verify Wallet Ownership

When the recipient wallet needs a [proof of ownership](https://docs.crossmint.com/onramp/guides/onramp-to-external-wallets.md#when-is-proof-of-ownership-required), Crossmint creates the order with the verification challenge and no payment details. To get the deposit address:

**1. Verify the wallet**

Have the buyer sign the challenge and submit the signature, as described in [Onramp to Non-Crossmint Wallets](https://docs.crossmint.com/onramp/guides/onramp-to-external-wallets.md).

**2. Update the order**

Call [Edit Order](https://docs.crossmint.com/api-reference/headless/edit-order.md) with the same Cash App `payment` that you used to create the order. The response holds `payment.preparation` with the deposit address.

```bash cURL theme={null}
curl -X PATCH 'https://staging.crossmint.com/api/2022-06-09/orders/ORDER_ID' \
  -H 'X-API-KEY: YOUR_SERVER_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "payment": {
      "method": "cashapp",
      "currency": "usd",
      "network": "solana",
      "refundAddress": "BUYER_REFUND_ADDRESS",
      "receiptEmail": "user@example.com"
    }
  }'
```

```js Node.js theme={null}
const response = await fetch("https://staging.crossmint.com/api/2022-06-09/orders/ORDER_ID", {
    method: "PATCH",
    headers: {
        "X-API-KEY": "YOUR_SERVER_API_KEY",
        "Content-Type": "application/json",
    },
    body: JSON.stringify({
        payment: {
            method: "cashapp",
            currency: "usd",
            network: "solana",
            refundAddress: "BUYER_REFUND_ADDRESS",
            receiptEmail: "user@example.com",
        },
    }),
});
const order = await response.json();
```

```python Python theme={null}
import requests

response = requests.patch(
    "https://staging.crossmint.com/api/2022-06-09/orders/ORDER_ID",
    headers={"X-API-KEY": "YOUR_SERVER_API_KEY", "Content-Type": "application/json"},
    json={
        "payment": {
            "method": "cashapp",
            "currency": "usd",
            "network": "solana",
            "refundAddress": "BUYER_REFUND_ADDRESS",
            "receiptEmail": "user@example.com",
        },
    },
)
print(response.json())
```

A Cash App order cannot change to another payment method, and an order created with another payment method cannot change to Cash App.

## Test on Staging

On staging, no real funds move. Each order completes automatically within about 3 minutes of creation. To test another result, create the order with one of these test `refundAddress` values:

| `refundAddress` | Result |
| - | - |
| `67Ms3NX2cnJdtqRvzJq3yNRyctgS7gAkTGSg9KnEnUjd` | The payment is refunded. |
| `9mCw9kqN89hqpoECbgvK2waKJ1KhvgGxomvg7qXHBg42` | The buyer pays 80% of the amount. The order completes with a smaller delivered quantity. |
| `HGF98rnYGkMq2pE5sPJxxpGUVuT9DdC65tJh54SkDtom` | The payment arrives after the quote expires, about 31 minutes after creation. The order still completes. |

Any other refund address completes the order normally. These addresses select a test result only on staging, so do not use them in production.

## Next Steps

> [card] [Onramp to Non-Crossmint Wallets](https://docs.crossmint.com/onramp/guides/onramp-to-external-wallets.md)
>
> Verify ownership of the recipient wallet

> [card] [Create Order](https://docs.crossmint.com/onramp/api-reference/create-order.md)
>
> Full reference for the onramp order payload
