# Using the Platform API
Source: https://dev.moonpay.com/api-reference/platform/documentation/using-the-api

Get started with the MoonPay Platform API

<Info>
  Looking for the widget API? Take a look at the [reference
  here](/api-reference/widget).
</Info>

## Base URL

```bash theme={null}
https://api.moonpay.com
```

<Info>
  Test mode vs live mode is determined by the API key you use, not the URL. Use
  test API key (`sk_test_...`) for test mode and live API keys (`sk_live_...`)
  for production.
</Info>

## Authentication

Authentication depends on whether you’re calling an endpoint from your server or from the client.

### Server-side Authentication

For server-side requests, send your [secret key](/platform/guides/api-and-sdk-credentials#secret-key) in the `X-Api-Key` header.

<CodeGroup>
  ```ts fetch theme={null}
  const URL = "https://api.moonpay.com/platform/v1/sessions";

  const res = await fetch(URL, {
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": "sk_test_123",
    },
    method: "POST",
    body: JSON.stringify({
      externalCustomerId: "your_user_id",
      deviceIp: "203.0.113.1",
    }),
  });
  ```

  ```sh curl theme={null}
  curl -X POST "https://api.moonpay.com/platform/v1/sessions" \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: sk_test_123" \
    -d '{
      "externalCustomerId": "customer1",
      "deviceIp": "203.0.113.1"
    }'
  ```
</CodeGroup>

### Client-side Authentication

For client-side API requests, use the [`accessToken`](/platform/guides/api-and-sdk-credentials#access-token) returned from a connection as a [Bearer token](https://swagger.io/docs/specification/v3_0/authentication/bearer-authentication/).

<CodeGroup>
  ```ts fetch theme={null}
  await fetch("https://api.moonpay.com/platform/v1/quotes", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify({
      // ... request body ...
    }),
  });
  ```
</CodeGroup>

## Response Format

Responses are returned as `JSON` with the `content-type: application/json` header.

## Pagination

Some requests, like [listing transactions](/api-reference/platform/endpoints/transactions/list), return paginated results using cursor-based pagination. Each response includes a cursor string that you pass to the next request to fetch the next page.

The response includes a `pageInfo` object. If `pageInfo.nextCursor` is `null`, there are no more pages. For example:

```json theme={null}
{
  "data": [],
  "pageInfo": {
    "nextCursor": "tr_123e4567-e89b-12d3-a456-426614174000"
  }
}
```

## Rate limits

Currently, requests for this integration are limited to 30 per second.

## Debugging

Each API response includes a request ID header. Use this ID when working with support:

```bash Example theme={null}
X-Request-Id: some-value
```

## Error Handling

When a request fails (4xx), the API returns an error object with details:

```json Example error response theme={null}
{
  "code": 400,
  "type": "Invalid request",
  "message": "Invalid request. sourceAmount must be greater than 0."
}
```

## OpenAPI

The API follows the [OpenAPI 3.1](https://swagger.io/specification/) specification. You can use the spec to generate typed clients for any language.

See the [OpenAPI Spec](/platform/guides/openapi-codegen) page for the full specification and code generation instructions.


# Delete a payment method
Source: https://dev.moonpay.com/api-reference/platform/endpoints/payment-methods/delete

DELETE /platform/v1/payment-methods/{paymentMethodId}
Remove a stored payment method for a customer



# List payment methods
Source: https://dev.moonpay.com/api-reference/platform/endpoints/payment-methods/list

GET /platform/v1/payment-methods
Get available payment method configurations for a user



# Get a quote
Source: https://dev.moonpay.com/api-reference/platform/endpoints/quotes/get

POST /platform/v1/quotes/buy
Build quotes for fiat->crypto transactions



# Create a session
Source: https://dev.moonpay.com/api-reference/platform/endpoints/sessions/create

POST /platform/v1/sessions
Create a session token to initialize a connection



# Revoke a session
Source: https://dev.moonpay.com/api-reference/platform/endpoints/sessions/revoke

DELETE /platform/v1/sessions
Revoke an active session token



# Get a transaction
Source: https://dev.moonpay.com/api-reference/platform/endpoints/transactions/get

GET /platform/v1/transactions/{id}
Get details for a single transaction by ID



# List transactions
Source: https://dev.moonpay.com/api-reference/platform/endpoints/transactions/list

GET /platform/v1/transactions
List transactions for the connected user with optional date filtering and pagination



# Asset
Source: https://dev.moonpay.com/api-reference/platform/objects-and-types/asset

A fiat currency or crypto token

## Properties

| Property    | Type    | Required | Description                                                   |
| ----------- | ------- | -------- | ------------------------------------------------------------- |
| `code`      | string  | Yes      | The currency code or token symbol (e.g., `USD`, `ETH`, `BTC`) |
| `name`      | string  | No       | The human-readable name (e.g., `US Dollar`, `Ethereum`)       |
| `precision` | integer | No       | The number of supported decimal places                        |

## Example

```json theme={null}
{
  "code": "ETH",
  "name": "Ethereum",
  "precision": 18
}
```

## Common Assets

### Fiat Currencies

| Code  | Name          | Precision |
| ----- | ------------- | --------- |
| `USD` | US Dollar     | 2         |
| `EUR` | Euro          | 2         |
| `GBP` | British Pound | 2         |

### Cryptocurrencies

| Code   | Name     | Precision |
| ------ | -------- | --------- |
| `BTC`  | Bitcoin  | 8         |
| `ETH`  | Ethereum | 18        |
| `USDC` | USD Coin | 6         |


# Fees
Source: https://dev.moonpay.com/api-reference/platform/objects-and-types/fees

Fee breakdown for an operation

## Properties

| Property    | Type                                                                            | Required | Description                                                                                                               |
| ----------- | ------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `network`   | [MonetaryAmount](/api-reference/platform/objects-and-types/fees#monetaryamount) | No       | The network fee (e.g., gas fee for blockchain transactions)                                                               |
| `moonpay`   | [MonetaryAmount](/api-reference/platform/objects-and-types/fees#monetaryamount) | No       | The MoonPay processing fee                                                                                                |
| `ecosystem` | [MonetaryAmount](/api-reference/platform/objects-and-types/fees#monetaryamount) | No       | The ecosystem fee, if applicable                                                                                          |
| `partner`   | [MonetaryAmount](/api-reference/platform/objects-and-types/fees#monetaryamount) | No       | **Deprecated.** Use `ecosystem` instead. This field will be removed in a future release. The partner's fee, if applicable |

## MonetaryAmount

Each fee is represented as a monetary amount:

| Property       | Type   | Required | Description                                          |
| -------------- | ------ | -------- | ---------------------------------------------------- |
| `amount`       | string | Yes      | The numeric amount as a string to preserve precision |
| `currencyCode` | string | Yes      | The currency code (e.g., `USD`)                      |

## Example

```json theme={null}
{
  "network": {
    "amount": "2.50",
    "currencyCode": "USD"
  },
  "moonpay": {
    "amount": "3.99",
    "currencyCode": "USD"
  },
  "ecosystem": {
    "amount": "1.00",
    "currencyCode": "USD"
  },
  "partner": {
    "amount": "1.00",
    "currencyCode": "USD"
  }
}
```

<Note>
  All fee amounts are strings to preserve decimal precision. Parse them
  appropriately in your application.
</Note>


# Payment Method
Source: https://dev.moonpay.com/api-reference/platform/objects-and-types/payment-method

A payment method configuration with its capabilities and availability

## Properties

| Property       | Type   | Required | Description                                        |
| -------------- | ------ | -------- | -------------------------------------------------- |
| `type`         | string | Yes      | Payment method type (e.g., `apple_pay`)            |
| `capabilities` | object | Yes      | What this payment method supports                  |
| `availability` | object | Yes      | Whether this payment method is currently available |

## Capabilities

| Property                    | Type      | Required | Description                                           |
| --------------------------- | --------- | -------- | ----------------------------------------------------- |
| `supportedCurrencies`       | string\[] | Yes      | Currencies supported (e.g., `["USD", "EUR"]`)         |
| `supportedTransactionTypes` | string\[] | Yes      | Transaction types supported (e.g., `["buy", "sell"]`) |

## Availability

| Property            | Type    | Required | Description                                       |
| ------------------- | ------- | -------- | ------------------------------------------------- |
| `active`            | boolean | Yes      | Whether the payment method is currently available |
| `unavailableReason` | string  | No       | Reason for unavailability, if applicable          |

## Payment Method Types

| Type        | Description |
| ----------- | ----------- |
| `apple_pay` | Apple Pay   |

## Example

```json theme={null}
{
  "type": "apple_pay",
  "capabilities": {
    "supportedCurrencies": ["USD", "EUR", "GBP"],
    "supportedTransactionTypes": ["buy"]
  },
  "availability": {
    "active": true
  }
}
```

## Checking Availability

Always check `availability.active` before offering a payment method to users. If `active` is `false`, check `unavailableReason` for details:

```json theme={null}
{
  "type": "apple_pay",
  "capabilities": {
    "supportedCurrencies": ["USD"],
    "supportedTransactionTypes": ["buy"]
  },
  "availability": {
    "active": false,
    "unavailableReason": "Payment method is in maintenance"
  }
}
```


# Quote
Source: https://dev.moonpay.com/api-reference/platform/objects-and-types/quote

A quote for a buy transaction with locked rate, fees, and expiry

## Properties

| Property        | Type                                                               | Required | Description                                                         |
| --------------- | ------------------------------------------------------------------ | -------- | ------------------------------------------------------------------- |
| `source`        | object                                                             | Yes      | Source amount and asset (fiat currency) you send                    |
| `destination`   | object                                                             | Yes      | Destination amount and asset (cryptocurrency) the customer receives |
| `fees`          | [Fees](/api-reference/platform/objects-and-types/fees)             | Yes      | Breakdown of network, MoonPay, and ecosystem fees                   |
| `wallet`        | [Wallet](/api-reference/platform/objects-and-types/wallet) \| null | Yes      | Wallet address where crypto will be sent. Null if not yet provided  |
| `paymentMethod` | object \| null                                                     | Yes      | Payment method used for this quote. Null if not specified           |
| `expiresAt`     | string (date-time)                                                 | Yes      | ISO 8601 datetime when the quote expires                            |
| `executable`    | boolean                                                            | Yes      | Whether the quote can be executed                                   |
| `signature`     | string                                                             | Yes      | Signature for mounting a payment frame                              |

## Source / Destination

Both `source` and `destination` have the same structure:

| Property | Type                                                     | Required | Description                                  |
| -------- | -------------------------------------------------------- | -------- | -------------------------------------------- |
| `amount` | string                                                   | Yes      | The amount as a string to preserve precision |
| `asset`  | [Asset](/api-reference/platform/objects-and-types/asset) | Yes      | The currency or token                        |

## Using the Quote

Pass the `signature` to the payment frame when you mount it. The frame uses this signature along with the quote data to execute the payment and create the transaction.

<Warning>
  Quotes expire. Check `expiresAt` and create the transaction before this time.
  If `executable` is `false`, the customer must provide additional information
  before you can use this quote.
</Warning>

## Example

```json theme={null}
{
  "source": {
    "amount": "100.00",
    "asset": {
      "code": "USD",
      "name": "US Dollar",
      "precision": 2
    }
  },
  "destination": {
    "amount": "0.0025",
    "asset": {
      "code": "ETH",
      "name": "Ethereum",
      "precision": 18
    }
  },
  "fees": {
    "network": {
      "amount": "2.50",
      "currencyCode": "USD"
    },
    "moonpay": {
      "amount": "3.99",
      "currencyCode": "USD"
    }
  },
  "wallet": {
    "address": "0x1234...abcd"
  },
  "paymentMethod": {
    "type": "apple_pay"
  },
  "expiresAt": "2026-01-29T14:35:50.000Z",
  "executable": true,
  "signature": "eyJhbGciOiJIUzI1NiIs..."
}
```


# Transaction
Source: https://dev.moonpay.com/api-reference/platform/objects-and-types/transaction

A transaction representing a crypto purchase or sale

## Properties

| Property        | Type                                                       | Required | Description                                                                                           |
| --------------- | ---------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `id`            | string                                                     | Yes      | The MoonPay ID of the transaction                                                                     |
| `createdAt`     | string (date-time)                                         | Yes      | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of when the transaction was created      |
| `updatedAt`     | string (date-time)                                         | Yes      | [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp of when the transaction was last updated |
| `status`        | string                                                     | Yes      | The current status: `completed`, `failed`, or `pending`                                               |
| `source`        | object                                                     | Yes      | The source amount and asset (fiat currency)                                                           |
| `destination`   | object                                                     | Yes      | The destination amount and asset (cryptocurrency)                                                     |
| `fees`          | [Fees](/api-reference/platform/objects-and-types/fees)     | Yes      | Fee breakdown for the transaction                                                                     |
| `wallet`        | [Wallet](/api-reference/platform/objects-and-types/wallet) | Yes      | The wallet where crypto was delivered                                                                 |
| `customer`      | object                                                     | Yes      | The customer who made the transaction                                                                 |
| `paymentMethod` | object                                                     | No       | The payment method used                                                                               |
| `stages`        | array                                                      | No       | The stages of the transaction lifecycle                                                               |

## Source / Destination

Both `source` and `destination` have the same structure:

| Property | Type                                                     | Required | Description                                  |
| -------- | -------------------------------------------------------- | -------- | -------------------------------------------- |
| `amount` | string                                                   | Yes      | The amount as a string to preserve precision |
| `asset`  | [Asset](/api-reference/platform/objects-and-types/asset) | Yes      | The currency or token                        |

## Customer

| Property | Type   | Required | Description                    |
| -------- | ------ | -------- | ------------------------------ |
| `id`     | string | Yes      | The MoonPay ID of the customer |

## Transaction Status

| Value       | Description                        |
| ----------- | ---------------------------------- |
| `pending`   | Transaction is in progress         |
| `completed` | Transaction completed successfully |
| `failed`    | Transaction failed                 |

## Example

```json theme={null}
{
  "id": "tr_abc123",
  "createdAt": "2026-01-29T14:30:50.000Z",
  "updatedAt": "2026-01-29T15:30:50.000Z",
  "status": "completed",
  "source": {
    "amount": "100.00",
    "asset": {
      "code": "USD"
    }
  },
  "destination": {
    "amount": "0.0025",
    "asset": {
      "code": "ETH"
    }
  },
  "fees": {
    "network": {
      "amount": "2.50",
      "currencyCode": "USD"
    },
    "moonpay": {
      "amount": "3.99",
      "currencyCode": "USD"
    }
  },
  "wallet": {
    "address": "0x1234...abcd"
  },
  "customer": {
    "id": "cust_xyz789"
  },
  "paymentMethod": {
    "type": "apple_pay"
  }
}
```


# Wallet
Source: https://dev.moonpay.com/api-reference/platform/objects-and-types/wallet

A blockchain wallet address

## Properties

| Property  | Type   | Required | Description                                                                  |
| --------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `address` | string | Yes      | The wallet address                                                           |
| `tag`     | string | No       | An optional memo or destination tag (used by some blockchains like XRP, XLM) |

## Example

### Standard Wallet

```json theme={null}
{
  "address": "0x1234567890abcdef1234567890abcdef12345678"
}
```

### Wallet with Memo/Tag

Some blockchains like XRP and XLM require a destination tag or memo to route funds to the correct account:

```json theme={null}
{
  "address": "rN7n3473SaZBCG4dFL83w7a1RXtXtbk2D9",
  "tag": "12345678"
}
```

<Warning>
  For blockchains that require tags/memos (XRP, XLM, etc.), always include the
  `tag` field when provided. Missing tags can result in lost funds.
</Warning>


# Widget API Reference
Source: https://dev.moonpay.com/api-reference/widget

API reference for the MoonPay widget integration.

The MoonPay widget integration is powered by two APIs:

* **Ramps & Swaps** — buy, sell, and swap quotes; transaction lookups;
  supported countries, currencies, and payment methods.
* **Virtual Accounts** — programmatic on-ramp and off-ramp via virtual
  bank accounts, plus the associated transaction history.

<CardGroup>
  <Card title="On-ramp" icon="arrow-right-arrow-left" href="/api-reference/widget/getbuyquote">
    Buy quotes, currency limits, network fees, and transaction lookups.
  </Card>

  <Card title="Off-ramp" icon="arrow-down-from-arc" href="/api-reference/widget/getsellquote">
    Sell quotes and sell transaction lookups.
  </Card>

  <Card title="Swaps" icon="rotate" href="/api-reference/widget/getswappairs">
    Swap pairs, quotes, execution, and transaction lookups.
  </Card>

  <Card title="Data" icon="database" href="/api-reference/widget/getcountries">
    Supported countries, currencies, payment methods, and IP-address checks.
  </Card>

  <Card title="DeFi tokens" icon="coins" href="/api-reference/widget/getdefitoken">
    Token data and token lists for DeFi assets.
  </Card>

  <Card title="Virtual Accounts" icon="building-columns" href="/api-reference/widget/getvirtualaccounts">
    Programmatic on-ramp and off-ramp via virtual bank accounts.
  </Card>

  <Card title="Webhooks" icon="bell" href="/api-reference/widget/webhooks/overview">
    Receive asynchronous notifications when transaction status changes.
  </Card>
</CardGroup>

## Authentication

Most endpoints require an API key. Pass it as the `apiKey` query parameter,
or use the `Authorization: Api-Key <secret>` header where indicated.

## Base URL

```
https://api.moonpay.com
```


# Cancel Sell transaction
Source: https://dev.moonpay.com/api-reference/widget/cancelselltransaction

DELETE /v3/sell_transactions/{transactionId})



# Execute Swap quote
Source: https://dev.moonpay.com/api-reference/widget/executeswapquote

POST /v4/swap/execute_quote
Executes a given swap quote. Refer to our Recipes section for more detailed examples.



# Get Real-time Buy quote
Source: https://dev.moonpay.com/api-reference/widget/getbuyquote

GET /v3/currencies/{currencyCode}/buy_quote
Get detailed real-time quote based on the provided currency code, base amount, your extra fee percentage, payment method, and the inclusion of the fees.




# Get Buy transaction
Source: https://dev.moonpay.com/api-reference/widget/getbuytransaction

GET /v1/transactions/{transactionId}
Retrieve a transaction by id. This call will return an error if no transaction with the supplied identifier exists.



# Get Buy transaction by External identifier
Source: https://dev.moonpay.com/api-reference/widget/getbuytransactionbyexternalid

GET /v1/transactions/ext/{externalTransactionId}
Retrieve a transaction by its externalTransactionId. This is the identifier you assigned the transaction when creating it. This endpoint returns an array of objects because we cannot ensure the uniqueness of externalTransactionId.



# List Buy transactions
Source: https://dev.moonpay.com/api-reference/widget/getbuytransactions

GET /v1/transactions
Returns an array of successful Buy transactions which fulfill criteria supplied in the query parameters. Each entry in the array is a separate transaction object. Transactions will be listed from newest to oldest.



# List supported countries
Source: https://dev.moonpay.com/api-reference/widget/getcountries

GET /v3/countries
Returns the list of countries currently supported by MoonPay.



# List supported currencies
Source: https://dev.moonpay.com/api-reference/widget/getcurrencies

GET /v3/currencies
Returns the list of currencies supported by MoonPay.



# Get Crypto Currency limits
Source: https://dev.moonpay.com/api-reference/widget/getcurrencylimits

GET /v3/currencies/{currencyCode}/limits
Returns an object containing minimum and maximum buy amounts including or excluding fees for base and quote currencies.

It takes into account the payment method if it's provided, **otherwise it defaults to the payment method with the lowest fees.**




# Get customer
Source: https://dev.moonpay.com/api-reference/widget/getcustomer

GET /v1/customers/{customerId}
Returns very basic information about a customer based on their MoonPay ID. For you to be able to retrieve a customer, they must have at least one session initiated with your `Api-Key`.



# Get customer by externalId
Source: https://dev.moonpay.com/api-reference/widget/getcustomerbyexternalid

GET /v1/customers/ext/{customerId}
Returns very basic information about a customer based on their external customer ID. For you to be able to retrieve a customer, they must have at least one session initiated with your `API-Key`. Please note that this endpoint returns an array of objects because we cannot ensure the uniqueness of the external customer ID.



# Get DeFi token
Source: https://dev.moonpay.com/api-reference/widget/getdefitoken

GET /v1/defi/token
Retrieve defi token for a specific contractAddress and network code



# List DeFi tokens
Source: https://dev.moonpay.com/api-reference/widget/getdefitokens

GET /v1/defi/tokens
Search and retrieve a paginated list of defi tokens



# Check Customer's IP address
Source: https://dev.moonpay.com/api-reference/widget/getipaddress

GET /v3/ip_address
Returns information about an IP address. If the `isAllowed` flag is set to <span class="value">false</span>, it means that MoonPay accepts citizens of this country but not residents.



# Get Crypto network fees
Source: https://dev.moonpay.com/api-reference/widget/getnetworkfees

GET /v3/currencies/network_fees
Returns a set of key-value pairs representing the current network fees of cryptocurrencies against fiat currencies.

Supply the codes of the crypto and fiat currencies you are interested in, and MoonPay will return the relevant network fees.




# Get off ramp transaction
Source: https://dev.moonpay.com/api-reference/widget/getofframptransaction

GET /v1/virtual-accounts/transactions/offramp/{transactionId}



# Get off ramp transactions
Source: https://dev.moonpay.com/api-reference/widget/getofframptransactions

GET /v1/virtual-accounts/transactions/offramp



# Get on ramp transaction
Source: https://dev.moonpay.com/api-reference/widget/getonramptransaction

GET /v1/virtual-accounts/transactions/onramp/{transactionId}



# Get on ramp transactions
Source: https://dev.moonpay.com/api-reference/widget/getonramptransactions

GET /v1/virtual-accounts/transactions/onramp



# Get Sell quote
Source: https://dev.moonpay.com/api-reference/widget/getsellquote

GET /v3/currencies/{currencyCode}/sell_quote
Returns a set of key-value pairs representing a real-time sell quote for a currency. Supply the currency code, the base amount, your extra fee percentage, the payment method and whether the base amount is inclusive of fees, and MoonPay will return a detailed sell quote.



# Get Sell transaction
Source: https://dev.moonpay.com/api-reference/widget/getselltransaction

GET /v3/sell_transactions/{transactionId}



# Get Sell transaction by External identifier
Source: https://dev.moonpay.com/api-reference/widget/getselltransactionbyexternalid

GET /v3/sell_transactions/ext/{externalTransactionId}
Retrieve a transaction by its externalTransactionId. This is the identifier you assigned the transaction when creating it. This endpoint returns an array of objects because we cannot ensure the uniqueness of externalTransactionId.



# List Sell transactions
Source: https://dev.moonpay.com/api-reference/widget/getselltransactions

GET /v1/sell_transactions



# Get Swap pairs
Source: https://dev.moonpay.com/api-reference/widget/getswappairs

GET /v4/swap/pairs
Returns the list of swap pairs available to the account.



# Get Swap quote
Source: https://dev.moonpay.com/api-reference/widget/getswapquote

GET /v4/swap/{PAIR}/quote
Returns the swap quote for a specific swap pair.



# Get Swap requote
Source: https://dev.moonpay.com/api-reference/widget/getswaprequote

GET /v4/swap/transaction/{transactionId}/requote
Returns a swap transaction re quote by id. Refer to our <a href="/recipes">Recipes section</a> for more detailed examples.



# Get Swap transaction
Source: https://dev.moonpay.com/api-reference/widget/getswaptransaction

GET /v4/swap/transaction/{transactionId}
Returns a swap transaction by id. Refer to our <a href="/recipes">Recipes section</a> for more detailed examples.



# Get virtual accounts
Source: https://dev.moonpay.com/api-reference/widget/getvirtualaccounts

GET /v1/virtual-accounts



# List available payment methods
Source: https://dev.moonpay.com/api-reference/widget/listpaymentmethods

GET /payments/v1/payment-method-config



# Reject Swap requote
Source: https://dev.moonpay.com/api-reference/widget/rejectswaprequote

POST /v4/swap/reject_requote
Rejects a given swap requote. Refer to our <a href="/recipes">Recipes section</a> for more detailed examples.



# Update on ramp virtual account
Source: https://dev.moonpay.com/api-reference/widget/updateonrampvirtualaccount

PATCH /v1/virtual-accounts/onramp/{id}



# Buy
Source: https://dev.moonpay.com/api-reference/widget/webhooks/buy

Currently supported Buy events

## Supported events

`transaction_created` `transaction_failed` `transaction_updated`

Please note that duplicate events MAY occur and in some occasions, may arrive out of order. We ask partners to de-dupe these events. This is a process of removing identical webhook responses.

A complete list of transaction object parameters and values can be found [here](/api-reference/widget/getbuytransaction).

## Examples

<CodeGroup>
  ```json transaction_created theme={null}
  {
    "data": {
      "isFromQuote": true,
      "isRecurring": false,
      "isTicketPayment": false,
      "id": "bda09e91-559f-4e7a-807a-cdec1a903d9d",
      "createdAt": "2022-08-31T10:00:03.640Z",
      "updatedAt": "2022-08-31T10:00:31.251Z",
      "baseCurrencyAmount": 295.45,
      "quoteCurrencyAmount": 0.1819,
      "feeAmount": 3.99,
      "extraFeeAmount": 0,
      "networkFeeAmount": 0.56,
      "areFeesIncluded": true,
      "flow": "principal",
      "status": "completed",
      "walletAddress": "0xc216eD2D6c295579718dbd4a797845CdA70B3C36",
      "walletAddressTag": null,
      "cryptoTransactionId": "0x6751c8fce2e0fb5d57bb4801b31b35a7160fa362e0c5703d44cfd508317ee2f8",
      "failureReason": null,
      "redirectUrl": "<https://api.moonpay.io/v3/three_d_secure?transactionId=bda09e91-559f-4e7a-807a-cdec1a903d9d&sid=6b3652b0-088c-444f-b706-affcdc1ca4db&iframe=true>",
      "returnUrl": "<https://buy-sandbox.moonpay.com/transaction_receipt>",
      "widgetRedirectUrl": null,
      "bankTransferReference": null,
      "baseCurrencyId": "71435a8d-211c-4664-a59e-2a5361a6c5a7",
      "currencyId": "8d305f63-1fd7-4e01-a220-8445e591aec4",
      "customerId": "2fcbcea3-6b62-49f1-b9d1-026d9bfd00b6",
      "cardId": "de063279-203f-4e31-83c3-e51aa844d8c4",
      "bankAccountId": null,
      "eurRate": 1,
      "usdRate": 0.99812,
      "gbpRate": 0.85823,
      "bankDepositInformation": null,
      "externalTransactionId": null,
      "feeAmountDiscount": null,
      "paymentMethod": "credit_debit_card",
      "baseCurrency": {
        "id": "71435a8d-211c-4664-a59e-2a5361a6c5a7",
        "createdAt": "2019-04-22T15:12:07.861Z",
        "updatedAt": "2022-08-16T13:42:26.618Z",
        "type": "fiat",
        "name": "Euro",
        "code": "eur",
        "precision": 2,
        "maxAmount": 10000,
        "minAmount": 30,
        "minBuyAmount": 30,
        "maxBuyAmount": 10000
      },
      "currency": {
        "id": "8d305f63-1fd7-4e01-a220-8445e591aec4",
        "createdAt": "2018-09-28T10:47:49.801Z",
        "updatedAt": "2022-08-25T16:57:25.823Z",
        "type": "crypto",
        "name": "Ethereum",
        "code": "eth",
        "precision": 4,
        "maxAmount": 3,
        "minAmount": 0.01,
        "minBuyAmount": 0.01078,
        "maxBuyAmount": null,
        "addressRegex": "^[0x](0-9A-Fa-f){40}$",
        "testnetAddressRegex": "^[0x](0-9A-Fa-f){40}$",
        "supportsAddressTag": false,
        "addressTagRegex": null,
        "supportsTestMode": true,
        "supportsLiveMode": true,
        "isSuspended": false,
        "isSupportedInUS": true,
        "notAllowedUSStates": ["HI", "NY", "VI"],
        "notAllowedCountries": [],
        "isSellSupported": true,
        "confirmationsRequired": 12,
        "minSellAmount": 0.025,
        "maxSellAmount": 8.5,
        "metadata": {
          "contractAddress": "0x0000000000000000000000000000000000000000",
          "chainId": "1",
          "networkCode": "ethereum"
        }
      },
      "nftTransaction": null,
      "stages": [
        {
          "stage": "stage_one_ordering",
          "status": "success",
          "actions": [],
          "failureReason": null
        },
        {
          "stage": "stage_two_verification",
          "status": "success",
          "actions": [],
          "failureReason": null
        },
        {
          "stage": "stage_three_processing",
          "status": "failed",
          "actions": [],
          "failureReason": "error"
        },
        {
          "stage": "stage_four_delivery",
          "status": "not_started",
          "actions": [],
          "failureReason": null
        }
      ],
      "country": "USA",
      "state": "NJ",
      "cardType": "card",
      "cardPaymentType": "debit",
      "externalCustomerId": "27346528354888",
      "nftToken": null
    },
    "type": "transaction_created",
    "externalCustomerId": "27346528354888"
  }
  ```

  ```json transaction_updated theme={null}
  {
    "data": {
      "isFromQuote": true,
      "isRecurring": false,
      "isTicketPayment": false,
      "id": "bda09e91-559f-4e7a-807a-cdec1a903d9d",
      "createdAt": "2022-08-31T10:00:03.640Z",
      "updatedAt": "2022-08-31T10:00:31.251Z",
      "baseCurrencyAmount": 295.45,
      "quoteCurrencyAmount": 0.1819,
      "feeAmount": 3.99,
      "extraFeeAmount": 0,
      "networkFeeAmount": 0.56,
      "areFeesIncluded": true,
      "flow": "principal",
      "status": "completed",
      "walletAddress": "0xc216eD2D6c295579718dbd4a797845CdA70B3C36",
      "walletAddressTag": null,
      "cryptoTransactionId": "0x6751c8fce2e0fb5d57bb4801b31b35a7160fa362e0c5703d44cfd508317ee2f8",
      "failureReason": null,
      "redirectUrl": "https://api.moonpay.io/v3/three_d_secure?transactionId=bda09e91-559f-4e7a-807a-cdec1a903d9d&sid=6b3652b0-088c-444f-b706-affcdc1ca4db&iframe=true",
      "returnUrl": "https://buy-sandbox.moonpay.com/transaction_receipt",
      "widgetRedirectUrl": null,
      "bankTransferReference": null,
      "baseCurrencyId": "71435a8d-211c-4664-a59e-2a5361a6c5a7",
      "currencyId": "8d305f63-1fd7-4e01-a220-8445e591aec4",
      "customerId": "2fcbcea3-6b62-49f1-b9d1-026d9bfd00b6",
      "cardId": "de063279-203f-4e31-83c3-e51aa844d8c4",
      "bankAccountId": null,
      "eurRate": 1,
      "usdRate": 0.99812,
      "gbpRate": 0.85823,
      "bankDepositInformation": null,
      "externalTransactionId": null,
      "feeAmountDiscount": null,
      "paymentMethod": "credit_debit_card",
      "baseCurrency": {
        "id": "71435a8d-211c-4664-a59e-2a5361a6c5a7",
        "createdAt": "2019-04-22T15:12:07.861Z",
        "updatedAt": "2022-08-16T13:42:26.618Z",
        "type": "fiat",
        "name": "Euro",
        "code": "eur",
        "precision": 2,
        "maxAmount": 10000,
        "minAmount": 30,
        "minBuyAmount": 30,
        "maxBuyAmount": 10000
      },
      "currency": {
        "id": "8d305f63-1fd7-4e01-a220-8445e591aec4",
        "createdAt": "2018-09-28T10:47:49.801Z",
        "updatedAt": "2022-08-25T16:57:25.823Z",
        "type": "crypto",
        "name": "Ethereum",
        "code": "eth",
        "precision": 4,
        "maxAmount": 3,
        "minAmount": 0.01,
        "minBuyAmount": 0.01078,
        "maxBuyAmount": null,
        "addressRegex": "^(0x)[0-9A-Fa-f]{40}$",
        "testnetAddressRegex": "^(0x)[0-9A-Fa-f]{40}$",
        "supportsAddressTag": false,
        "addressTagRegex": null,
        "supportsTestMode": true,
        "supportsLiveMode": true,
        "isSuspended": false,
        "isSupportedInUS": true,
        "notAllowedUSStates": ["HI", "NY", "VI"],
        "notAllowedCountries": [],
        "isSellSupported": true,
        "confirmationsRequired": 12,
        "minSellAmount": 0.025,
        "maxSellAmount": 8.5,
        "metadata": {
          "contractAddress": "0x0000000000000000000000000000000000000000",
          "chainId": "1",
          "networkCode": "ethereum"
        }
      },
      "nftTransaction": null,
      "country": "USA",
      "state": "NJ",
      "externalCustomerId": "27346528354888",
      "nftToken": null
    },
    "type": "transaction_updated",
    "externalCustomerId": "27346528354888"
  }
  ```

  ```json transaction_failed theme={null}
  {
    "data": {
      "isFromQuote": true,
      "isRecurring": false,
      "isTicketPayment": false,
      "id": "621d21ce-13cc-4e95-af0d-771ae156f92a",
      "createdAt": "2022-09-13T10:23:26.751Z",
      "updatedAt": "2022-09-13T10:23:37.505Z",
      "baseCurrencyAmount": 25.74,
      "quoteCurrencyAmount": 0.0144,
      "feeAmount": 3.99,
      "extraFeeAmount": 0,
      "networkFeeAmount": 0.27,
      "areFeesIncluded": true,
      "flow": "principal",
      "status": "failed",
      "walletAddress": "0x00BDBFC6B0584771c28B9092c16AEB31Ad677283",
      "walletAddressTag": null,
      "cryptoTransactionId": null,
      "failureReason": "Failed testnet withdrawal",
      "redirectUrl": "https://api.moonpay.io/v3/payment?transactionId=621d21ce-13cc-4e95-af0d-771ae156f92a&sid=4ed76ab0-65e1-4624-b0d9-9fce62e41f0b",
      "returnUrl": "https://buy-sandbox.moonpay.com/transaction_receipt",
      "widgetRedirectUrl": "https://www.myurl.com",
      "bankTransferReference": null,
      "baseCurrencyId": "edd81f1f-f735-4692-b410-6def107f17d2",
      "currencyId": "8d305f63-1fd7-4e01-a220-8445e591aec4",
      "customerId": "2fcbcea3-6b62-49f1-b9d1-026d9bfd00b6",
      "cardId": "de063279-203f-4e31-83c3-e51aa844d8c4",
      "bankAccountId": null,
      "eurRate": 0.98363,
      "usdRate": 1,
      "gbpRate": 0.8542,
      "bankDepositInformation": null,
      "externalTransactionId": null,
      "feeAmountDiscount": null,
      "paymentMethod": "credit_debit_card",
      "baseCurrency": {
        "id": "edd81f1f-f735-4692-b410-6def107f17d2",
        "createdAt": "2019-04-29T16:55:28.647Z",
        "updatedAt": "2022-08-16T13:42:26.618Z",
        "type": "fiat",
        "name": "US Dollar",
        "code": "usd",
        "precision": 2,
        "maxAmount": 12000,
        "minAmount": 30,
        "minBuyAmount": 30,
        "maxBuyAmount": 12000
      },
      "currency": {
        "id": "8d305f63-1fd7-4e01-a220-8445e591aec4",
        "createdAt": "2018-09-28T10:47:49.801Z",
        "updatedAt": "2022-08-25T16:57:25.823Z",
        "type": "crypto",
        "name": "Ethereum",
        "code": "eth",
        "precision": 4,
        "maxAmount": 3,
        "minAmount": 0.01,
        "minBuyAmount": 0.01078,
        "maxBuyAmount": null,
        "addressRegex": "^(0x)[0-9A-Fa-f]{40}$",
        "testnetAddressRegex": "^(0x)[0-9A-Fa-f]{40}$",
        "supportsAddressTag": false,
        "addressTagRegex": null,
        "supportsTestMode": true,
        "supportsLiveMode": true,
        "isSuspended": false,
        "isSupportedInUS": true,
        "notAllowedUSStates": ["HI", "NY", "RI", "VI"],
        "notAllowedCountries": [],
        "isSellSupported": true,
        "confirmationsRequired": 12,
        "minSellAmount": 0.025,
        "maxSellAmount": 8.5,
        "metadata": {
          "contractAddress": "0x0000000000000000000000000000000000000000",
          "chainId": "1",
          "networkCode": "ethereum"
        }
      },
      "nftTransaction": null,
      "stages": [
        {
          "stage": "stage_one_ordering",
          "status": "success",
          "actions": [],
          "failureReason": null
        },
        {
          "stage": "stage_two_verification",
          "status": "success",
          "actions": [],
          "failureReason": null
        },
        {
          "stage": "stage_three_processing",
          "status": "failed",
          "actions": [],
          "failureReason": "error"
        },
        {
          "stage": "stage_four_delivery",
          "status": "not_started",
          "actions": [],
          "failureReason": null
        }
      ],
      "country": "USA",
      "state": "NJ",
      "cardType": "card",
      "cardPaymentType": "debit",
      "externalCustomerId": "27346528354888",
      "nftToken": null
    },
    "type": "transaction_failed",
    "externalCustomerId": "27346528354888"
  }
  ```
</CodeGroup>

## Properties

```json theme={null}
{
  "event": {
    "method": "POST",
    "headers": {
      "moonpay-signature": "t=1663064622,s=cdd18ef9d85c004638f0e9f770231909d24053b503a8f281991e33280a7a9ba9",
      "moonpay-signature-v2": "t=1663064622,s=44d8318c5ad1720959799062280f5f0030658776c13804d9edd04fd2c4012f14"
    }
  }
}
```


# Cancel Sell transaction by externalId
Source: https://dev.moonpay.com/api-reference/widget/webhooks/cancelselltransactionbyexternalid

DELETE /v3/sell_transactions/ext/{transactionId})



# Overview
Source: https://dev.moonpay.com/api-reference/widget/webhooks/overview



## When to utilize Webhooks

Webhooks are essential for managing behind-the-scenes transactions. They allow you to receive alerts for asynchronous updates to transaction statuses. MoonPay can send webhook events that notify your application whenever an activity occurs on your account. This feature is particularly valuable for tracking changes like transaction status updates, that are not triggered by a direct API request.

These notifications are delivered through HTTP POST requests to any endpoint URLs you've specified in your account's [Webhooks settings](https://dashboard.moonpay.com/developers/#webhooks). MoonPay is capable of sending a single event to multiple webhook endpoints.

## Configuring your Webhook Settings

Webhooks are configured in your MoonPay dashboard's [Webhook settings](https://dashboard.moonpay.com/developers/#webhooks). Click Add Endpoint to reveal a form where you can add a new URL for receiving webhooks.

<Frame>
  <img alt="Webhooks dashboard" />
</Frame>

You can enter any URL as the destination for events. However, this should be a dedicated page on your server that is set up to receive webhook notifications. You can choose to be notified of all event types, or only specific ones.

Using test or live API keys determines whether test events or live events are sent to your configured URL. If you want to send both live and test events to the same URL, you need to create two separate settings. You can add as many URLs as you like.

## Receiving a Webhook Notification

Setting up an endpoint to receive webhook HTTP POST requests in the JSON request body can vary based on your backend stack and hosting environment. Below are some methods to achieve this using different technologies:

### Python with Flask

Flask is a lightweight WSGI web application framework in Python.

```python theme={null}
from flask import Flask, request, jsonify

app = Flask(**name**)

@app.route('/webhook', methods=['POST'])
def webhook(): # Flask automatically parses JSON if the Content-Type is application/json
data = request.json
print(f"Received data: {data}")
return jsonify({"status": "success"}), 200

if **name** == '**main**':
app.run(port=5000)

```

### Node.js with Express

Node.js is widely used for server-side development, and Express is one of the most popular frameworks for Node.js.

```typescript theme={null}
const express = require("express");
const bodyParser = require("body-parser");

const app = express();

// Middleware to parse JSON payload from incoming POST request
app.use(bodyParser.json());

app.post("/webhook", (req, res) => {
  // req.body contains the parsed JSON payload
  const data = req.body;
  console.log(`Received data: ${JSON.stringify(data)}`);
  res.status(200).json({ status: "success" });
});

app.listen(3000, () => {
  console.log("Server started on <http://localhost:3000>");
});
```

### Ruby with Sinatra

Sinatra is a DSL (Domain Specific Language) for quickly creating web applications in Ruby with minimal effort.

```ruby theme={null}
require 'sinatra'
require 'json'

post '/webhook' do # Reading and parsing the JSON payload from the request body
  data = JSON.parse(request.body.read)
  puts "Received data: #{data}"
  [200, { 'Content-Type' => 'application/json' }, { status: 'success' }.to_json]
end

```

### Deployment

After setting up your webhook endpoint, you'll need to deploy it. You can use cloud services like AWS, Google Cloud, Heroku, or any VPS provider for this purpose.

### Secure your Webhook

You may validate incoming requests to ensure they are coming from a trusted source. Visit our [webhooks signature](/api-reference/widget/webhooks/signature) for more information. This is a recommended best practice.

### Test your Webhook

After deployment, you can test your webhook endpoint using Postman or curl to send a simulated POST request.


# Sell
Source: https://dev.moonpay.com/api-reference/widget/webhooks/sell

Currently supported Sell events

## Supported events

* `sell_transaction_created`
* `sell_transaction_updated`
* `sell_transaction_failed`

Complete list of sell transaction object parameters and descriptions can be found [here](https://moonpay.readme.io/reference/getselltransaction).

## Examples

<CodeGroup>
  ```json sell_transaction_created theme={null}
  {
    "data": {
      "id": "b8606f16-5518-4425-8076-87067a291ddf",
      "createdAt": "2023-05-12T17:30:50.390Z",
      "updatedAt": "2023-05-12T17:30:50.390Z",
      "baseCurrencyAmount": 500,
      "feeAmount": 3.99,
      "extraFeeAmount": 0,
      "quoteCurrencyAmount": 38.79,
      "flow": "principal",
      "status": "waitingForDeposit",
      "accountId": "7c565d78-10d9-47d8-aa4b-ed28aa1177dc",
      "customerId": "66eed1c8-e12e-4d77-85f6-008b7b3eeeab",
      "quoteCurrencyId": "edd81f1f-f735-4692-b410-6def107f17d2",
      "baseCurrencyId": "c8b1ef20-3703-4a66-9ea1-c13ce0d893bf",
      "eurRate": 0.9211,
      "usdRate": 1,
      "gbpRate": 0.8027,
      "depositWalletId": null,
      "bankAccountId": "eb5e7e71-087d-40ec-b508-33c6fab38175",
      "refundWalletAddress": "",
      "refundWalletAddressRequestedAt": null,
      "externalTransactionId": null,
      "failureReason": null,
      "depositHash": null,
      "refundHash": null,
      "widgetRedirectUrl": null,
      "confirmations": null,
      "quoteExpiresAt": "2023-05-12T17:50:50.389Z",
      "quoteExpiredEmailSentAt": null,
      "refundApprovalStatus": null,
      "cancelledById": null,
      "blockedById": null,
      "depositMatchedManuallyById": null,
      "createdById": null,
      "incomingCustomerCryptoDepositId": null,
      "payoutMethod": "ach_bank_transfer",
      "integratedSellDepositInfo": null,
      "baseCurrency": {
        "id": "c8b1ef20-3703-4a66-9ea1-c13ce0d893bf",
        "createdAt": "2019-04-10T15:58:46.394Z",
        "updatedAt": "2023-03-08T14:38:22.686Z",
        "type": "crypto",
        "name": "Stellar",
        "code": "xlm",
        "precision": 0,
        "maxAmount": 2000,
        "minAmount": 20,
        "minBuyAmount": 44,
        "maxBuyAmount": null,
        "isSellSupported": true,
        "addressRegex": "^G[A-D]{1}[A-Z2-7]{54}$",
        "testnetAddressRegex": "^G[A-D]{1}[A-Z2-7]{54}$",
        "supportsAddressTag": true,
        "addressTagRegex": "^[0-9A-Za-z]{1,28}$",
        "supportsTestMode": true,
        "supportsLiveMode": true,
        "isSuspended": false,
        "isSupportedInUS": true,
        "notAllowedUSStates": ["HI", "NY", "RI", "VI"],
        "notAllowedCountries": [],
        "confirmationsRequired": 1,
        "minSellAmount": 200,
        "maxSellAmount": 100000,
        "metadata": {
          "contractAddress": null,
          "coinType": "148",
          "chainId": null,
          "networkCode": "stellar"
        }
      },
      "depositWallet": null,
      "quoteCurrency": {
        "id": "edd81f1f-f735-4692-b410-6def107f17d2",
        "createdAt": "2019-04-29T16:55:28.647Z",
        "updatedAt": "2023-03-06T10:11:49.284Z",
        "type": "fiat",
        "name": "US Dollar",
        "code": "usd",
        "precision": 2,
        "maxAmount": 12000,
        "minAmount": 30,
        "minBuyAmount": 30,
        "maxBuyAmount": 12000,
        "isSellSupported": true
      },
      "country": "USA",
      "state": "NJ",
      "externalCustomerId": null
    },
    "type": "sell_transaction_created"
  }
  ```

  ```json sell_transaction_updated theme={null}
  {
    "data": {
      "id": "b8606f16-5518-4425-8076-87067a291ddf",
      "createdAt": "2023-05-12T17:30:50.390Z",
      "updatedAt": "2023-05-12T17:31:04.590Z",
      "baseCurrencyAmount": 500,
      "feeAmount": 3.99,
      "extraFeeAmount": 0,
      "quoteCurrencyAmount": 38.79,
      "flow": "principal",
      "status": "waitingForDeposit",
      "accountId": "7c565d78-10d9-47d8-aa4b-ed28aa1177dc",
      "customerId": "66eed1c8-e12e-4d77-85f6-008b7b3eeeab",
      "quoteCurrencyId": "edd81f1f-f735-4692-b410-6def107f17d2",
      "baseCurrencyId": "c8b1ef20-3703-4a66-9ea1-c13ce0d893bf",
      "eurRate": 0.9211,
      "usdRate": 1,
      "gbpRate": 0.8027,
      "depositWalletId": "226f77bf-d061-4d88-9830-8a58c1094ab1",
      "bankAccountId": "eb5e7e71-087d-40ec-b508-33c6fab38175",
      "refundWalletAddress": "",
      "refundWalletAddressRequestedAt": null,
      "externalTransactionId": null,
      "failureReason": null,
      "depositHash": null,
      "refundHash": null,
      "widgetRedirectUrl": null,
      "confirmations": null,
      "quoteExpiresAt": "2023-05-12T17:50:50.389Z",
      "quoteExpiredEmailSentAt": null,
      "refundApprovalStatus": null,
      "cancelledById": null,
      "blockedById": null,
      "depositMatchedManuallyById": null,
      "createdById": null,
      "incomingCustomerCryptoDepositId": null,
      "payoutMethod": "ach_bank_transfer",
      "integratedSellDepositInfo": null,
      "baseCurrency": {
        "id": "c8b1ef20-3703-4a66-9ea1-c13ce0d893bf",
        "createdAt": "2019-04-10T15:58:46.394Z",
        "updatedAt": "2023-03-08T14:38:22.686Z",
        "type": "crypto",
        "name": "Stellar",
        "code": "xlm",
        "precision": 0,
        "maxAmount": 2000,
        "minAmount": 20,
        "minBuyAmount": 44,
        "maxBuyAmount": null,
        "isSellSupported": true,
        "addressRegex": "^G[A-D]{1}[A-Z2-7]{54}$",
        "testnetAddressRegex": "^G[A-D]{1}[A-Z2-7]{54}$",
        "supportsAddressTag": true,
        "addressTagRegex": "^[0-9A-Za-z]{1,28}$",
        "supportsTestMode": true,
        "supportsLiveMode": true,
        "isSuspended": false,
        "isSupportedInUS": true,
        "notAllowedUSStates": ["HI", "NY", "RI", "VI"],
        "notAllowedCountries": [],
        "confirmationsRequired": 1,
        "minSellAmount": 200,
        "maxSellAmount": 100000,
        "metadata": {
          "contractAddress": null,
          "coinType": "148",
          "chainId": null,
          "networkCode": "stellar"
        }
      },
      "depositWallet": {
        "id": "226f77bf-d061-4d88-9830-8a58c1094ab1",
        "createdAt": "2023-05-12T17:31:04.527Z",
        "updatedAt": "2023-05-12T17:31:04.527Z",
        "walletAddress": "GDPVBFETVZRQRVFUIDN7I55X5HDXS2NVZ5S62DKFUSNKJ5XWUOU2Q3TM",
        "walletAddressTag": null,
        "customerId": "66eed1c8-e12e-4d77-85f6-008b7b3eeeab",
        "currencyId": "c8b1ef20-3703-4a66-9ea1-c13ce0d893bf",
        "btcLegacyAddress": null,
        "type": "Fireblocks",
        "encryptedPrivateKey": null
      },
      "quoteCurrency": {
        "id": "edd81f1f-f735-4692-b410-6def107f17d2",
        "createdAt": "2019-04-29T16:55:28.647Z",
        "updatedAt": "2023-03-06T10:11:49.284Z",
        "type": "fiat",
        "name": "US Dollar",
        "code": "usd",
        "precision": 2,
        "maxAmount": 12000,
        "minAmount": 30,
        "minBuyAmount": 30,
        "maxBuyAmount": 12000,
        "isSellSupported": true
      },
      "country": "USA",
      "state": "NJ",
      "externalCustomerId": null
    },
    "type": "sell_transaction_updated"
  }
  ```

  ```json sell_transaction_failed theme={null}
  {
    "data": {
      "id": "b8606f16-5518-4425-8076-87067a291ddf",
      "createdAt": "2023-05-12T17:30:50.390Z",
      "updatedAt": "2023-05-19T17:31:00.042Z",
      "baseCurrencyAmount": 500,
      "feeAmount": 3.99,
      "extraFeeAmount": 0,
      "quoteCurrencyAmount": 38.79,
      "flow": "principal",
      "status": "failed",
      "accountId": "7c565d78-10d9-47d8-aa4b-ed28aa1177dc",
      "customerId": "66eed1c8-e12e-4d77-85f6-008b7b3eeeab",
      "quoteCurrencyId": "edd81f1f-f735-4692-b410-6def107f17d2",
      "baseCurrencyId": "c8b1ef20-3703-4a66-9ea1-c13ce0d893bf",
      "eurRate": 0.9211,
      "usdRate": 1,
      "gbpRate": 0.8027,
      "depositWalletId": "226f77bf-d061-4d88-9830-8a58c1094ab1",
      "bankAccountId": "eb5e7e71-087d-40ec-b508-33c6fab38175",
      "refundWalletAddress": "",
      "refundWalletAddressRequestedAt": null,
      "externalTransactionId": null,
      "failureReason": "Deposit timeout",
      "depositHash": null,
      "refundHash": null,
      "widgetRedirectUrl": null,
      "confirmations": null,
      "quoteExpiresAt": "2023-05-12T17:50:50.389Z",
      "quoteExpiredEmailSentAt": "2023-05-12T17:51:00.044Z",
      "refundApprovalStatus": null,
      "cancelledById": null,
      "blockedById": null,
      "depositMatchedManuallyById": null,
      "createdById": null,
      "incomingCustomerCryptoDepositId": null,
      "payoutMethod": "ach_bank_transfer",
      "integratedSellDepositInfo": null,
      "baseCurrency": {
        "id": "c8b1ef20-3703-4a66-9ea1-c13ce0d893bf",
        "createdAt": "2019-04-10T15:58:46.394Z",
        "updatedAt": "2023-03-08T14:38:22.686Z",
        "type": "crypto",
        "name": "Stellar",
        "code": "xlm",
        "precision": 0,
        "maxAmount": 2000,
        "minAmount": 20,
        "minBuyAmount": 44,
        "maxBuyAmount": null,
        "isSellSupported": true,
        "addressRegex": "^G[A-D]{1}[A-Z2-7]{54}$",
        "testnetAddressRegex": "^G[A-D]{1}[A-Z2-7]{54}$",
        "supportsAddressTag": true,
        "addressTagRegex": "^[0-9A-Za-z]{1,28}$",
        "supportsTestMode": true,
        "supportsLiveMode": true,
        "isSuspended": false,
        "isSupportedInUS": true,
        "notAllowedUSStates": ["HI", "NY", "RI", "VI"],
        "notAllowedCountries": [],
        "confirmationsRequired": 1,
        "minSellAmount": 200,
        "maxSellAmount": 100000,
        "metadata": {
          "contractAddress": null,
          "coinType": "148",
          "chainId": null,
          "networkCode": "stellar"
        }
      },
      "depositWallet": {
        "id": "226f77bf-d061-4d88-9830-8a58c1094ab1",
        "createdAt": "2023-05-12T17:31:04.527Z",
        "updatedAt": "2023-05-12T17:31:04.527Z",
        "walletAddress": "GDPVBFETVZRQRVFUIDN7I55X5HDXS2NVZ5S62DKFUSNKJ5XWUOU2Q3TM",
        "walletAddressTag": null,
        "customerId": "66eed1c8-e12e-4d77-85f6-008b7b3eeeab",
        "currencyId": "c8b1ef20-3703-4a66-9ea1-c13ce0d893bf",
        "btcLegacyAddress": null,
        "type": "Fireblocks",
        "encryptedPrivateKey": null
      },
      "quoteCurrency": {
        "id": "edd81f1f-f735-4692-b410-6def107f17d2",
        "createdAt": "2019-04-29T16:55:28.647Z",
        "updatedAt": "2023-03-06T10:11:49.284Z",
        "type": "fiat",
        "name": "US Dollar",
        "code": "usd",
        "precision": 2,
        "maxAmount": 12000,
        "minAmount": 30,
        "minBuyAmount": 30,
        "maxBuyAmount": 12000,
        "isSellSupported": true
      },
      "country": "USA",
      "state": "NJ",
      "externalCustomerId": null
    },
    "type": "sell_transaction_failed"
  }
  ```
</CodeGroup>

## Properties

```json theme={null}
{
  "event": {
    "method": "POST",
    "headers": {
      "moonpay-signature": "t=1663064622,s=cdd18ef9d85c004638f0e9f770231909d24053b503a8f281991e33280a7a9ba9",
      "moonpay-signature-v2": "t=1663064622,s=44d8318c5ad1720959799062280f5f0030658776c13804d9edd04fd2c4012f14"
    }
  }
}
```


# Request signing
Source: https://dev.moonpay.com/api-reference/widget/webhooks/signature



## Checking a Webhook Signature

MoonPay signs the webhook events and requests we send to your endpoints. We do so by including a signature in each event’s `Moonpay-Signature-V2` header. This allows you to validate that the events and requests were sent by MoonPay, not by a third party.

Before you can verify `Moonpay-Signature-V2` signatures for webhook events, you need to retrieve your webhook API key from the [Developers page](https://dashboard.moonpay.com/developers/) on the MoonPay dashboard.

The `Moonpay-Signature-V2` header contains a timestamp and one signature. The timestamp is prefixed by t=, and the signature is prefixed by s=.

<CodeGroup>
  ```bash bash Moonpay-Signature-V2: theme={null}
  t=1492774577,s=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
  ```
</CodeGroup>

MoonPay generates signatures using a hash-based message authentication code ([HMAC](https://en.wikipedia.org/wiki/HMAC)) with [SHA-256](https://en.wikipedia.org/wiki/SHA-2).

<Steps>
  <Step>
    Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

    The value for the prefix `t` corresponds to the timestamp, and `s` corresponds to the signature.
  </Step>

  <Step>
    You achieve this by concatenating:

    * The timestamp (as a string)
    * The character . and
    * For a `POST` request, the actual JSON payload (i.e., the request's body). For a `GET` request, the search string (e.g., ?externalCustomerId=adbb317d-cde9-4ebb-93a3-1b271812de06).
  </Step>

  <Step>
    Compute a HMAC with the SHA-256 hash function. Use your account's webhook API key as the key, and use the `signed_payload` string as the message in both cases.

    Compare the signature in the header to the expected signature.
  </Step>
</Steps>


# Swap
Source: https://dev.moonpay.com/api-reference/widget/webhooks/swap

Currently supported Swap events

## Supported events

* `swap_asset_delivery_initiated`
* `swap_transaction_created` `swap_quote_expired`
* `swap_quote_invalid`
* `swap_deposit_wallet_created`
* `swap_deposit_received`
* `swap_transaction_completed`
* `swap_transaction_failed`
* `swap_refund_asset_delivery_initiated`
* `swap_refund_completed`


# Virtual Accounts
Source: https://dev.moonpay.com/api-reference/widget/webhooks/virtual-accounts

Currently supported Virtual Accounts events

## Events

### `virtual_account_status_updated`

Triggered when the status of a virtual account changes.

```json Example payload theme={null}
{
  "virtualAccountId": "9bc86a06-8300-41c8-8cef-d2eaa852164f",
  "externalCustomerId": "external_customer_id_123",
  "status": "completed",
  "timestamp": 1678901234567
}
```

| Field                | Type    | Description                                                              |
| -------------------- | ------- | ------------------------------------------------------------------------ |
| `virtualAccountId`   | string  | Unique identifier (uuid) of the virtual account                          |
| `externalCustomerId` | string  | External identifier of the customer                                      |
| `status`             | string  | Current status of the virtual account (`pending`, `completed`, `failed`) |
| `timestamp`          | integer | Unix timestamp (milliseconds) when the event was triggered               |

### `virtual_account_transaction_status_updated`

Triggered when the status of a transaction within a virtual account changes.

```json Example payload theme={null}
{
  "virtualAccountId": "9bc86a06-8300-41c8-8cef-d2eaa852164f",
  "externalCustomerId": "external_customer_id_123",
  "transactionId": "7a2cbc6f-ddef-4071-9628-a6559cb4ad89",
  "status": "Completed",
  "timestamp": 1678901234567
}
```

| Field                | Type    | Description                                                          |
| -------------------- | ------- | -------------------------------------------------------------------- |
| `virtualAccountId`   | string  | Unique identifier (uuid) of the virtual account                      |
| `externalCustomerId` | string  | External identifier provided for the customer                        |
| `transactionId`      | string  | Unique identifier (uuid) of the transaction                          |
| `status`             | string  | Current status of the transaction (`Pending`, `Completed`, `Failed`) |
| `timestamp`          | integer | Unix timestamp (milliseconds) when the event was triggered           |


# Changelog
Source: https://dev.moonpay.com/platform/changelog

Updates to the MoonPay developer platform

<Update label="May 21, 2026">
  **Challenge events for Apple Pay and Google Pay** — the [Apple Pay
  frame](/platform/frames/apple-pay) and [Google Pay
  frame](/platform/frames/google-pay) now emit a `challenge` event when
  verification is required before a transaction can proceed. Challenge handling
  added to the [Apple Pay SDK
  reference](/platform/sdk-reference/web/setup-apple-pay), [Google Pay SDK
  reference](/platform/sdk-reference/web/setup-google-pay), and manual
  integration guides for
  [web](/platform/guides/manual-integration/web),
  [iOS](/platform/guides/manual-integration/ios), [React
  Native](/platform/guides/manual-integration/react-native), and
  [Flutter](/platform/guides/manual-integration/flutter).

  **TransactionStatus fix** — corrected the `TransactionStatus` enum value from
  `complete` to `completed` in the [Apple Pay
  frame](/platform/frames/apple-pay) and [Google Pay
  frame](/platform/frames/google-pay) references.
</Update>

<Update label="May 20, 2026">
  **Google Pay** — new [Pay with Google
  Pay](/platform/guides/pay-with-google-pay) guide, [Google Pay
  frame](/platform/frames/google-pay) reference, and
  [`setupGooglePay`](/platform/sdk-reference/web/setup-google-pay) SDK method.
  Covers the standalone Google Pay frame integration and manual integration for
  [web](/platform/guides/manual-integration/web),
  [Android](/platform/guides/manual-integration/android), [React
  Native](/platform/guides/manual-integration/react-native), and
  [Flutter](/platform/guides/manual-integration/flutter).
</Update>

<Update label="May 19, 2026">
  **EEA disclosures** — published the exact verbiage required above the Apple
  Pay frame and the card Pay button for customers located in the EEA, with
  separate text for standard crypto-assets and non-MiCA-compliant stablecoins
  (USDT, cUSD, DAI, PYUSD). See [Going
  Live](/platform/overview/going-live#disclosures-eea).
</Update>

<Update label="May 18, 2026">
  **API key header** — server-to-server requests now authenticate with the
  `X-Api-Key` header. See [Using the Platform
  API](/api-reference/platform/documentation/using-the-api#server-side-authentication)
  and [API and SDK
  credentials](/platform/guides/api-and-sdk-credentials#secret-key).
</Update>

<Update label="May 13, 2026">
  **Payment-disclosure geography** — `paymentDisclosures` now identifies the
  customer's geography. `country` is the ISO 3166-1 alpha-3 code,
  `administrativeArea` is included for US state-level disclosures, and `area`
  can identify broader regions such as `"EEA"`.
</Update>

<Update label="May 12, 2026">
  **Going Live** — documented the acceptance criteria for the global rollout
  (except UK). Each requirement is now tagged with a geo, and new sections cover
  Cards, Identity API, and EEA Apple Pay disclosures (verbiage pending). See
  [Going Live](/platform/overview/going-live).
</Update>

<Update label="May 8, 2026">
  **Preview removed** — the Developer Platform is now generally available. The
  "currently in preview" notice has been removed from all docs pages.
</Update>

<Update label="May 8, 2026">
  **Card payments** — new [Pay with card](/platform/guides/pay-with-card) guide
  and frame references for [Add Card](/platform/frames/add-card),
  [Buy](/platform/frames/buy), and [Challenge](/platform/frames/challenge).
  Covers the full integration: listing and managing stored cards, getting a card
  quote, executing transactions via the headless buy frame, and handling
  verification challenges (SCA, 3DS, CVC re-entry, KYC). Also adds the [Delete
  payment method](/api-reference/platform/endpoints/payment-methods/delete) API
  endpoint.
</Update>

<Update label="May 5, 2026">
  **Reset frame** — new headless frame at `/platform/v1/reset` that lets you log
  a customer out by clearing their authentication state on MoonPay's domain.
  Reports completion via postMessage. See [Reset](/platform/frames/reset).
</Update>

<Update label="May 5, 2026">
  **Unified docs site** — Platform and Widget docs now live under a single
  Mintlify site with separate top-level tabs. Legacy `/overview/*`, `/guides/*`,
  `/frames/*`, `/sdk-reference/*`, and `/api-reference/*` URLs redirect to their
  new `/platform/*` paths.
</Update>

<Update label="May 1, 2026">
  **Manual integration fixes** — corrected the WebView samples to post the
  payload as a string, base64-decode credentials, and handle JS dialogs. Affects
  [web](/platform/guides/manual-integration/web),
  [iOS](/platform/guides/manual-integration/ios),
  [Android](/platform/guides/manual-integration/android), [React
  Native](/platform/guides/manual-integration/react-native), and
  [Flutter](/platform/guides/manual-integration/flutter) guides.
</Update>

<Update label="May 1, 2026">
  **Fee language** updated across guides to clarify partner vs. ecosystem fees.
</Update>

<Update label="April 30, 2026">
  **Revoke session** — `DELETE /platform/v1/sessions` invalidates an active
  session token. See [Revoke a
  session](/api-reference/platform/endpoints/sessions/revoke).
</Update>

<Update label="April 29, 2026">
  **Sessions endpoint renamed** — `POST /platform/v1/session` is now `POST
      /platform/v1/sessions` (plural). The old path continues to work; new
  integrations should use the plural form.
</Update>

<Update label="April 28, 2026">
  **Apple Pay going-live guide** — added production-readiness details for the
  Apple Pay frame, including merchant verification and domain registration
  steps. See [Pay with Apple Pay](/platform/guides/pay-with-apple-pay).
</Update>

<Update label="April 27, 2026">
  **`customerId` in connect/check payload** — the `complete` postMessage event
  now documents `customer.id`, and the session-create request documents the
  `customerId` field for returning users (skip the connect flow when you already
  have one).
</Update>

<Update label="April 20, 2026">
  **Manual integration credentials** — the manual integration guides now use
  `clientToken` (not `sessionToken`) to initialize frames, matching the
  early-credential-issuance flow.
</Update>

<Update label="April 17, 2026">
  **US payment-disclosure rails narrowed** — the `paymentDisclosures` capability
  is now documented as scoped to NY and WA within the US. Customers in other US
  states will not receive a `paymentDisclosures` requirement.
</Update>

<Update label="April 17, 2026">
  **HKDF examples** — manual integration code samples consistently pass
  `undefined` for the `info` parameter of `hkdf()`.
</Update>

<Update label="April 10, 2026">
  **Acceptance criteria page** — new compliance checklist outlining the
  requirements for going live. See [Going live](/platform/overview/going-live).
</Update>

<Update label="April 10, 2026">
  **Manual integration moved** — the per-platform manual integration pages now
  live under [Guides → Manual
  Integration](/platform/guides/manual-integration/overview).
</Update>

<Update label="April 10, 2026">
  **Using agents** — new page covering MCP client setup for Claude Code and
  Codex, so you can wire your agent to MoonPay's developer docs. See [Using
  agents](/platform/overview/using-agents).
</Update>

<Update label="April 10, 2026">
  **Manual integration docs** — initial documented integrations for web, iOS,
  Android, React Native, and Flutter (graduated from hidden drafts).
</Update>

<Update label="April 9, 2026">
  **Early credential issuance** — the credentials-flow guide now reflects that
  `clientToken` and `accessToken` are issued before authentication completes, so
  partners can initialize sensitive frames sooner.
</Update>

<Update label="April 9, 2026">
  **Connect-flow low-friction callout** — added guidance to the connect-flow
  guide about minimizing handoffs back to MoonPay-hosted UI.
</Update>

<Update label="April 9, 2026">
  **Apple Pay frame height** — corrected the documented frame height for the
  Apple Pay frame.
</Update>

<Update label="March 2026">
  Quote API: `fees.partner` field renamed to `fees.ecosystem`.

  Apple Pay: documented test-mode and frame sandbox requirements, plus a
  corrected frame size.

  Customer capabilities and payment-disclosure requirements expanded.

  New widget-fallback frame and integration guide.

  Frames protocol: documented `version: 2` and added the versioning section.

  Frame URLs migrated from `/v2/*` to `/platform/*` across all docs.
</Update>

<Update label="February 2026">
  OpenAPI now served live from `https://api.moonpay.com/platform/openapi.json`
  rather than checked into the repo.

  Removed historical `pk_test` / `pk_live` references in favor of the new
  credential model.

  Initial Apple Pay frame size and frame sandbox requirements published.

  Mintlify upgrade and a content-style-guide pass across guides and frames docs.
</Update>


# Add Card
Source: https://dev.moonpay.com/platform/frames/add-card

Details on working with the Add Card frame used in the [Pay with card](/platform/guides/pay-with-card) flow.

## URL

```
https://blocks.moonpay.com/platform/v1/add-card
```

## Requirements

### Size

Render the frame in a modal or sheet. Width and height are flexible — size the
container to fit your UI.

<Note>
  The Add Card frame uses MoonPay's existing card input UI. A redesign is
  planned to streamline the experience and explore hosted fields for full design
  customization.
</Note>

## Initialization parameters

| Property      | Type     | Required | Description                                                                                                                                                                                    |
| ------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientToken` | `string` | ✅        | The [client token](/platform/guides/api-and-sdk-credentials#client-token) returned from the [connect flow](/platform/guides/connect-a-customer).                                               |
| `channelId`   | `string` | ✅        | A unique identifier for the frame generated on your client. This value is attached to each `postMessage` payload to help identify messages.<br /><br />The format of this string is up to you. |

## Events

All events are dispatched using the message pattern described in the [frames
protocol](/platform/frames/overview#frames-protocol#messages). Below are the
event payloads specific to the Add Card frame.

### Outbound events

<Badge>
  frame->parent
</Badge>

These events are sent from this frame to the parent window.

#### `handshake`

The frame requests that you open a message channel.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type HandshakeEvent = Message<{
    kind: "handshake";
  }>;
  ```
</CodeGroup>

#### `ready`

The frame finished loading and the card input UI is fully rendered.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ready"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ReadyEvent = Message<{
    kind: "ready";
  }>;
  ```
</CodeGroup>

#### `complete`

The card was added successfully. Use `card.id` to get a quote without
re-fetching payment methods.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "card": {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "type": "card",
        "cardType": "credit",
        "brand": "visa",
        "last4": "4242",
        "expirationMonth": "12",
        "expirationYear": "2027",
        "availability": { "active": true }
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type CardResponse = {
    id: string;
    type: "card";
    cardType: "credit" | "debit" | "unknown";
    brand: "visa" | "mastercard" | "maestro" | "american_express" | "other";
    last4: string;
    expirationMonth: string;
    expirationYear: string;
    availability: { active: boolean };
  };

  type AddCardCompleteEvent = Message<{
    kind: "complete";
    payload: {
      card: CardResponse;
    };
  }>;
  ```
</CodeGroup>

#### `error`

An error occurred during card addition.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "error",
    "payload": {
      "code": "generic",
      "message": "Card creation failed."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AddCardErrorEvent = Message<{
    kind: "error";
    payload: {
      code: "configurationError" | "generic";
      /** A developer-facing error message. Not intended to be rendered in UI. */
      message: string;
    };
  }>;
  ```
</CodeGroup>

| Code                 | Description                      |
| -------------------- | -------------------------------- |
| `configurationError` | Missing or invalid `clientToken` |
| `generic`            | Card creation failed             |

### Inbound events

<Badge>
  parent->frame
</Badge>

These events are sent from the parent window to this frame.

#### `ack`

Acknowledge the [handshake](#handshake).

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AckEvent = Message<{
    kind: "ack";
  }>;
  ```
</CodeGroup>


# Apple Pay
Source: https://dev.moonpay.com/platform/frames/apple-pay

Details on working with the [Apple Pay](/platform/guides/pay-with-apple-pay) frame.

## URL

```html theme={null}
https://blocks.moonpay.com/platform/v1/apple-pay
```

## Requirements

### Size

The frame container **height must be 44px**. Width is flexible; the Apple Pay button inside the frame uses 100% of the container width.

### Permissions

The `payment` [permission policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes) is required.

In [test mode](/platform/overview/test-mode#apple-pay), the frame uses `window.confirm` to simulate the Apple Pay payment. If your iframe uses the [`sandbox`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe#sandbox) attribute, you will need to include `allow-modals`.

```tsx Example theme={null}
<iframe
  src="https://blocks.moonpay.com/platform/v1/apple-pay"
  allow="payment"
/>
```

## Initialization parameters

| Property                | Type     | Required | Description                                                                                                                                                                                    |
| ----------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientToken`           | `string` | ✅        | The [client token](/platform/guides/api-and-sdk-credentials#client-token) returned from the [connect flow](/platform/guides/connect-a-customer).                                               |
| `channelId`             | `string` | ✅        | A unique identifier for the frame generated on your client. This value is attached to each `postMessage` payload to help identify messages.<br /><br />The format of this string is up to you. |
| `signature`             | `string` | ✅        | The quote `signature` from the quote endpoint. Pass `signature` as returned.                                                                                                                   |
| `externalTransactionId` | `string` |          | Your own identifier for the transaction. Stored and associated with the MoonPay transaction for correlation.                                                                                   |

## Events

All events are dispatched using the message pattern described in the [frames protocol](/platform/frames/overview#frames-protocol#messages). Below are the event payloads specific to the Apple Pay frame.

### Outbound events

<Badge>
  frame->parent
</Badge>

These events are sent from this frame to the parent window.

#### `handshake`

The frame requests that you open a message channel.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type HandshakeEvent = Message<{
    kind: "handshake";
  }>;
  ```
</CodeGroup>

#### `ready`

The frame finished loading and the UI is fully rendered. You can use this to coordinate UI transitions if needed.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ready"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ReadyEvent = Message<{
    kind: "ready";
  }>;
  ```
</CodeGroup>

#### `complete`

The transaction is complete. Use the transaction ID to track status updates (for example, by polling or via webhooks).

<CodeGroup>
  ```json Example (success) theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "transaction": {
        "id": "txn_01",
        "status": "pending"
      }
    }
  }
  ```

  ```json Example (fail) theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "transaction": {
        "status": "failed",
        "failureReason": "The payment could not be completed with the selected card."
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  enum TransactionStatus {
    /** The transaction has successfully completed. The payment has been made and the crypto has been transferred. **/
    completed = "completed",
    /** The payment has been completed and the crypto transfer is underway. **/
    pending = "pending",
    /** The transaction has failed. No payment was applied and the crypto was not transferred. **/
    failed = "failed",
  }

  type Transaction =
    | {
        /** The MoonPay identifier for this transaction. **/
        id: string;
        /** The status of the transaction. **/
        status: TransactionStatus.completed | TransactionStatus.pending;
      }
    | {
        status: TransactionStatus.failed;
        /** A developer-friendly error message detailing the reason for the transaction failure. **/
        failureReason: string;
      };

  type ApplePayCompleteEvent = Message<{
    kind: "complete";
    payload: {
      transaction: Transaction;
    };
  }>;
  ```
</CodeGroup>

#### `challenge`

Verification is required before the transaction can proceed. Render the
[challenge frame](/platform/frames/challenge) at the provided URL. Do not
construct the URL yourself — use it as-is.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "challenge",
    "payload": {
      "kind": "frame",
      "url": "https://blocks.moonpay.com/platform/v1/challenge?challengeToken=..."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ApplePayChallengeEvent = Message<{
    kind: "challenge";
    payload: {
      kind: string;
      /** Fully-formed URL to pass directly as the challenge frame src. */
      url: string;
    };
  }>;
  ```
</CodeGroup>

#### `error`

This event dispatches errors that occur in the flow and, if available, provides steps for recovery.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "error",
    "payload": {
      "code": "applePayUnavailable",
      "message": "Apple Pay is not supported."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ApplePayError = Message<{
    kind: "error";
    payload: {
      code:
        | "configurationError"
        | "quoteExpired"
        | "invalidQuote"
        | "applePayUnavailable"
        | "generic";
      /** A developer-facing error message with details on recovery or documentation. This message is not intended to be rendered in UI. */
      message: string;
    };
  }>;
  ```
</CodeGroup>

| Code                  | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| `configurationError`  | The frame configuration is invalid. Check initialization parameters. |
| `quoteExpired`        | The quote has expired. Fetch a new quote and send it via `setQuote`. |
| `invalidQuote`        | The quote signature is invalid or malformed.                         |
| `applePayUnavailable` | Apple Pay is not available in the current environment or browser.    |
| `generic`             | An unexpected error occurred.                                        |

### Inbound events

<Badge>
  parent->frame
</Badge>

These events are sent from the parent window to this frame.

#### `ack`

Acknowledge the [handshake](#handshake).

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AckEvent = Message<{
    kind: "ack";
  }>;
  ```
</CodeGroup>

#### `setQuote`

Provide a new quote to the frame. Pass `signature` as returned by the quote endpoint. Upon receiving this event, the frame disables the Apple Pay button until the quote is revalidated.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "setQuote",
    "payload": {
      "quote": {
        "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type SetQuoteEvent = Message<{
    kind: "setQuote";
    payload: {
      quote: {
        /** The signature from a valid quote. **/
        signature: string;
      };
    };
  }>;
  ```
</CodeGroup>


# Buy
Source: https://dev.moonpay.com/platform/frames/buy

Details on working with the headless Buy frame used in the [Pay with card](/platform/guides/pay-with-card) flow.

The Buy frame is a headless frame. It evaluates transaction requirements, creates
the transaction, and completes post-transaction processing — all without
rendering any UI. Your confirmation screen, loading states, and purchase button
remain fully under your control.

## URL

```
https://blocks.moonpay.com/platform/v1/buy
```

## Requirements

### Size

The frame is headless. Mount it with zero dimensions so it does not affect your
layout:

```tsx Example theme={null}
<iframe
  src="https://blocks.moonpay.com/platform/v1/buy?..."
  style="position: absolute; width: 0; height: 0; border: none; overflow: hidden;"
/>
```

## Initialization parameters

| Property                | Type     | Required | Description                                                                                                                                                                                    |
| ----------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientToken`           | `string` | ✅        | The [client token](/platform/guides/api-and-sdk-credentials#client-token) returned from the [connect flow](/platform/guides/connect-a-customer).                                               |
| `channelId`             | `string` | ✅        | A unique identifier for the frame generated on your client. This value is attached to each `postMessage` payload to help identify messages.<br /><br />The format of this string is up to you. |
| `signature`             | `string` | ✅        | The quote `signature` from the [quote endpoint](/api-reference/platform/endpoints/quotes/get). Pass `signature` as returned.                                                                   |
| `externalTransactionId` | `string` |          | Your own identifier for the transaction. Stored and associated with the MoonPay transaction for correlation.                                                                                   |

## Events

All events are dispatched using the message pattern described in the [frames
protocol](/platform/frames/overview#frames-protocol#messages). Below are the
event payloads specific to the Buy frame.

### Outbound events

<Badge>
  frame->parent
</Badge>

These events are sent from this frame to the parent window.

#### `handshake`

The frame requests that you open a message channel.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type HandshakeEvent = Message<{
    kind: "handshake";
  }>;
  ```
</CodeGroup>

#### `ready`

The buy pipeline is starting. Use this to show a loading indicator in your UI.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ready"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ReadyEvent = Message<{
    kind: "ready";
  }>;
  ```
</CodeGroup>

#### `complete`

The transaction is complete. Use the transaction ID to track final status via
polling.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "transaction": {
        "id": "txn_01",
        "status": "pending"
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type BuyCompleteEvent = Message<{
    kind: "complete";
    payload: {
      transaction: {
        id: string;
        status: "pending" | "completed" | "failed";
      };
    };
  }>;
  ```
</CodeGroup>

#### `challenge`

Verification is required before the transaction can proceed. Render the
[challenge frame](/platform/frames/challenge) at the provided URL. Do not
construct the URL yourself — use it as-is.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "challenge",
    "payload": {
      "kind": "frame",
      "url": "https://blocks.moonpay.com/platform/v1/challenge?challengeToken=..."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type BuyChallengeEvent = Message<{
    kind: "challenge";
    payload: {
      kind: string;
      /** Fully-formed URL to pass directly as the challenge frame src. */
      url: string;
    };
  }>;
  ```
</CodeGroup>

#### `error`

A terminal error occurred. Remove the frame and surface the message to the
developer.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "error",
    "payload": {
      "code": "invalidQuote",
      "message": "Unable to decode the quote signature."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type BuyErrorEvent = Message<{
    kind: "error";
    payload: {
      code: "configurationError" | "invalidQuote" | "generic";
      /** A developer-facing error message. Not intended to be rendered in UI. */
      message: string;
    };
  }>;
  ```
</CodeGroup>

| Code                 | Description                              |
| -------------------- | ---------------------------------------- |
| `configurationError` | Missing or invalid `signature` parameter |
| `invalidQuote`       | Unable to decode the quote signature     |
| `generic`            | Unspecified error                        |

### Inbound events

<Badge>
  parent->frame
</Badge>

These events are sent from the parent window to this frame.

#### `ack`

Acknowledge the [handshake](#handshake).

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AckEvent = Message<{
    kind: "ack";
  }>;
  ```
</CodeGroup>

#### `setQuote`

Provide a new quote to the frame. Send this when the current quote expires
before the customer completes the purchase. Pass `signature` as returned by the
quote endpoint.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "setQuote",
    "payload": {
      "quote": {
        "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type SetQuoteEvent = Message<{
    kind: "setQuote";
    payload: {
      quote: {
        /** The signature from a valid quote. */
        signature: string;
      };
    };
  }>;
  ```
</CodeGroup>


# Challenge
Source: https://dev.moonpay.com/platform/frames/challenge

Details on working with the Challenge frame used in the [Pay with card](/platform/guides/pay-with-card) flow.

The Challenge frame handles all verification steps required to complete a card
transaction. The URL is provided by the [buy frame's](/platform/frames/buy)
`challenge` event — do not construct it yourself.

The frame is self-driving: after the handshake, there are no further
parent-to-child messages. It sequences through all required verification steps,
creates the transaction, and emits `complete` when the pipeline finishes.

## URL

Provided by the buy frame's `challenge` event payload. Do not modify it.

## Requirements

### Size

Render the frame in a modal or full sheet so the customer can complete
verification. The frame adapts to any size, but a full-screen or large modal
works best for flows like 3D Secure that load bank-hosted pages.

## Initialization parameters

| Property         | Type     | Required | Description                                                                                                       |
| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `clientToken`    | `string` | ✅        | Included automatically in the challenge URL for CSP compliance. Do not remove it.                                 |
| `channelId`      | `string` | ✅        | Generate a fresh channel ID on your side and append it to the challenge URL before setting it as the frame `src`. |
| `challengeToken` | `string` | ✅        | Opaque token. Do not modify or parse it.                                                                          |

## Events

All events are dispatched using the message pattern described in the [frames
protocol](/platform/frames/overview#frames-protocol#messages). Below are the
event payloads specific to the Challenge frame.

### Outbound events

<Badge>
  frame->parent
</Badge>

These events are sent from this frame to the parent window.

#### `handshake`

The frame requests that you open a message channel.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_challenge_1" },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type HandshakeEvent = Message<{
    kind: "handshake";
  }>;
  ```
</CodeGroup>

#### `ready`

The challenge UI is rendered and visible to the customer.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_challenge_1" },
    "kind": "ready"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ReadyEvent = Message<{
    kind: "ready";
  }>;
  ```
</CodeGroup>

#### `complete`

All verification steps resolved and the transaction pipeline finished. Remove
the challenge frame **and** the buy frame, then navigate to the confirmation
screen.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_challenge_1" },
    "kind": "complete",
    "payload": {
      "flow": "buy",
      "transaction": {
        "id": "txn_01",
        "status": "pending"
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ChallengeCompleteEvent = Message<{
    kind: "complete";
    payload: {
      flow: "buy";
      transaction: {
        id: string;
        status: "pending" | "completed" | "failed";
      };
    };
  }>;
  ```
</CodeGroup>

#### `cancelled`

The customer dismissed the challenge. Remove the challenge frame and buy frame,
then offer a retry path.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_challenge_1" },
    "kind": "cancelled",
    "payload": {
      "flow": "buy"
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ChallengeCancelledEvent = Message<{
    kind: "cancelled";
    payload: {
      flow: "buy";
      transactionId?: string;
      challengeToken?: string;
    };
  }>;
  ```
</CodeGroup>

#### `error`

The challenge failed. Remove the challenge frame and buy frame, then surface the
message to the developer.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_challenge_1" },
    "kind": "error",
    "payload": {
      "code": "generic",
      "message": "Challenge failed."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ChallengeErrorEvent = Message<{
    kind: "error";
    payload: {
      code: "configurationError" | "invalidToken" | "generic";
      /** A developer-facing error message. Not intended to be rendered in UI. */
      message: string;
    };
  }>;
  ```
</CodeGroup>

| Code                 | Description                           |
| -------------------- | ------------------------------------- |
| `configurationError` | Frame initialization failed           |
| `invalidToken`       | Challenge token is invalid or expired |
| `generic`            | Unspecified error                     |

### Inbound events

<Badge>
  parent->frame
</Badge>

#### `ack`

Acknowledge the [handshake](#handshake). This is the only message you send to
the challenge frame — it is self-driving after the handshake.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_challenge_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AckEvent = Message<{
    kind: "ack";
  }>;
  ```
</CodeGroup>


# Check
Source: https://dev.moonpay.com/platform/frames/check

Check if a customer has an active connection.

The check frame is a lightweight, headless page hosted on a MoonPay domain. Use it to check whether the customer already has an active connection.

The frame always returns encrypted credentials. If the customer is connected, these are authenticated credentials. If the customer is not connected (or their connection has expired), these are anonymous credentials — store them and use the `clientToken` to initialize the connect flow.

## URL

```html theme={null}
https://blocks.moonpay.com/platform/v1/check-connection
```

## Requirements

### Key exchange

Credentials returned from the frame are encrypted to protect their content since they are sent over `postMessage`. You need to generate an [X25519](https://datatracker.ietf.org/doc/html/rfc7748#section-5) keypair and pass the public key into the frame. The frame uses your public key to encrypt the payload, ensuring only you can read it with your private key.

<Warning>
  Never persist the private key to disk or storage. Hold it in memory only for
  the duration of the session.
</Warning>

<Frame>
  <img alt="Frame credential verification lifecycle" />

  <img alt="Frame credential verification lifecycle" />
</Frame>

The frame uses the [@noble/curves](https://github.com/paulmillr/noble-curves) library internally. On web and React Native, you can use this same library to generate your keypair and handle decryption. For native platforms, use a compatible utility like [CryptoKit](https://developer.apple.com/documentation/cryptokit/curve25519) on iOS or [KeyPairGenerator](https://developer.android.com/reference/java/security/KeyPairGenerator) on Android.

<Accordion title="Example crypto module for web" icon="brackets-curly">
  The following example shows how to generate a keypair and decrypt credentials using `@noble/curves`. You'll want to add your own error handling and input validation for production use.

  <CodeGroup>
    ```sh pnpm theme={null}
    pnpm i @noble/curves @noble/hashes @noble/ciphers
    ```

    ```sh bun theme={null}
    bun add @noble/curves @noble/hashes @noble/ciphers
    ```

    ```sh npm theme={null}
    npm i @noble/curves @noble/hashes @noble/ciphers
    ```
  </CodeGroup>

  ```ts crypto.ts theme={null}
  // An example module for generating keypairs and decrypting client credentials.
  // This should not be used as-is in production!

  import { gcm } from "@noble/ciphers/aes.js";
  import { x25519 } from "@noble/curves/ed25519.js";
  import { hkdf } from "@noble/hashes/hkdf.js";
  import { sha256 } from "@noble/hashes/sha2.js";

  /** The credentials returned from the connect flow. */
  export type ClientCredentials = {
    /** A JWT used to authenticate client requests to the Moonpay API. */
    accessToken: string;
    /** A JWT used to initialize authenticated frames such as Apple Pay. */
    clientToken: string;
    /** An [ISO 8601 timestamp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) representing the expiration time of the tokens. */
    expiresAt: string;
  };

  /** X25519 `privateKey` and `publicKey`as hex strings. */
  export type KeyPair = Record<"privateKey" | "publicKey", string>;

  export type DecryptClientCredentialsResult =
    | { ok: true; value: ClientCredentials }
    | { ok: false; error: string };

  const hexToBytes = (hex: string): Uint8Array => {
    if (hex.length % 2 !== 0) {
      throw new Error("Invalid hex string");
    }

    const bytes = new Uint8Array(hex.length / 2);
    for (let i = 0; i < bytes.length; i++) {
      bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
    }
    return bytes;
  };

  const bytesToHex = (bytes: Uint8Array): string => {
    return Array.from(bytes)
      .map((b) => b.toString(16).padStart(2, "0"))
      .join("");
  };

  /** Decrypts an encrypted `ClientCredentials`. */
  export const decryptClientCredentials = (
    /** A base64-encoded string representing the encrypted JSON payload. **/
    encryptedCredentials: string,
    /** The recipient's X25519 private key as a hex string. **/
    privateKeyHex: string,
  ): DecryptClientCredentialsResult => {
    // Base64 decode the encrypted credentials
    const payload = atob(encryptedCredentials);

    // Guard and validate this deserialization
    const parsedPayload = JSON.parse(payload);
    // Convert the private key from a hex string to a `Uint8Array`
    const privateKey = hexToBytes(privateKeyHex);
    // Convert the ephemeral public key from a hex string to a `Uint8Array`
    const publicKey = hexToBytes(parsedPayload.ephemeralPublicKey);
    const ivBytes = hexToBytes(parsedPayload.iv);
    const ciphertextBytes = hexToBytes(parsedPayload.ciphertext);
    const sharedSecret = x25519.getSharedSecret(privateKey, publicKey);

    const encryptionKey = hkdf(sha256, sharedSecret, undefined, undefined, 32);
    const cipher = gcm(encryptionKey, ivBytes);
    const plainTextBytes = cipher.decrypt(ciphertextBytes);
    const plaintext = new TextDecoder().decode(plainTextBytes);

    let parsed: unknown;
    try {
      parsed = JSON.parse(plaintext);
    } catch {
      return { ok: false, error: "Failed to parse decrypted payload as JSON" };
    }

    // Validate the decrypted payload
    if (
      typeof parsed !== "object" ||
      parsed === null ||
      typeof (parsed as Record<string, unknown>).accessToken !== "string" ||
      typeof (parsed as Record<string, unknown>).clientToken !== "string" ||
      typeof (parsed as Record<string, unknown>).expiresAt !== "string"
    ) {
      return { ok: false, error: "Decrypted payload missing required fields" };
    }

    return { ok: true, value: parsed as ClientCredentials };
  };

  /** Generates a new X25519 key pair encryption. */
  export const generateKeyPair = (): KeyPair => {
    const { secretKey: privateKey, publicKey } = x25519.keygen();

    return {
      privateKey: bytesToHex(privateKey),
      publicKey: bytesToHex(publicKey),
    };
  };
  ```
</Accordion>

<Accordion title="Example crypto module for React Native" icon="mobile">
  The following example shows how to generate a keypair and decrypt credentials using `@noble/curves`. You'll want to add your own error handling and input validation for production use.

  In React Native, yuo will need a [polyfill for `getRandomValues`](https://github.com/LinusU/react-native-get-random-values) ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)) which is only available in browsers.

  <CodeGroup>
    ```sh pnpm theme={null}
    pnpm i react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers
    ```

    ```sh bun theme={null}
    bun add react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers
    ```

    ```sh npm theme={null}
    npm i react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers
    ```
  </CodeGroup>

  ```ts crypto.ts theme={null}
  // An example module for generating keypairs and decrypting client credentials.
  // This should not be used as-is in production!

  import { gcm } from "@noble/ciphers/aes.js";
  import { x25519 } from "@noble/curves/ed25519.js";
  import { hkdf } from "@noble/hashes/hkdf.js";
  import { sha256 } from "@noble/hashes/sha2.js";
  // React Native polyfill for getRandomValues
  import "react-native-get-random-values";

  /** The credentials returned from the connect flow. */
  export type ClientCredentials = {
    /** A JWT used to authenticate client requests to the Moonpay API. */
    accessToken: string;
    /** A JWT used to initialize authenticated frames such as Apple Pay. */
    clientToken: string;
    /** An [ISO 8601 timestamp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) representing the expiration time of the tokens. */
    expiresAt: string;
  };

  /** X25519 `privateKey` and `publicKey`as hex strings. */
  export type KeyPair = Record<"privateKey" | "publicKey", string>;

  export type DecryptClientCredentialsResult =
    | { ok: true; value: ClientCredentials }
    | { ok: false; error: string };

  const hexToBytes = (hex: string): Uint8Array => {
    if (hex.length % 2 !== 0) {
      throw new Error("Invalid hex string");
    }

    const bytes = new Uint8Array(hex.length / 2);
    for (let i = 0; i < bytes.length; i++) {
      bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
    }
    return bytes;
  };

  const bytesToHex = (bytes: Uint8Array): string => {
    return Array.from(bytes)
      .map((b) => b.toString(16).padStart(2, "0"))
      .join("");
  };

  /** Decrypts an encrypted `ClientCredentials`. */
  export const decryptClientCredentials = (
    /** A base64-encoded string representing the encrypted JSON payload. **/
    encryptedCredentials: string,
    /** The recipient's X25519 private key as a hex string. **/
    privateKeyHex: string,
  ): DecryptClientCredentialsResult => {
    // Base64 decode the encrypted credentials
    const payload = atob(encryptedCredentials);

    // Guard and validate this deserialization
    const parsedPayload = JSON.parse(payload);
    // Convert the private key from a hex string to a `Uint8Array`
    const privateKey = hexToBytes(privateKeyHex);
    // Convert the ephemeral public key from a hex string to a `Uint8Array`
    const publicKey = hexToBytes(parsedPayload.ephemeralPublicKey);
    const ivBytes = hexToBytes(parsedPayload.iv);
    const ciphertextBytes = hexToBytes(parsedPayload.ciphertext);
    const sharedSecret = x25519.getSharedSecret(privateKey, publicKey);

    const encryptionKey = hkdf(sha256, sharedSecret, undefined, undefined, 32);
    const cipher = gcm(encryptionKey, ivBytes);
    const plainTextBytes = cipher.decrypt(ciphertextBytes);
    const plaintext = new TextDecoder().decode(plainTextBytes);

    let parsed: unknown;
    try {
      parsed = JSON.parse(plaintext);
    } catch {
      return { ok: false, error: "Failed to parse decrypted payload as JSON" };
    }

    // Validate the decrypted payload
    if (
      typeof parsed !== "object" ||
      parsed === null ||
      typeof (parsed as Record<string, unknown>).accessToken !== "string" ||
      typeof (parsed as Record<string, unknown>).clientToken !== "string" ||
      typeof (parsed as Record<string, unknown>).expiresAt !== "string"
    ) {
      return { ok: false, error: "Decrypted payload missing required fields" };
    }

    return { ok: true, value: parsed as ClientCredentials };
  };

  /** Generates a new X25519 key pair encryption. */
  export const generateKeyPair = (): KeyPair => {
    const { secretKey: privateKey, publicKey } = x25519.keygen();

    return {
      privateKey: bytesToHex(privateKey),
      publicKey: bytesToHex(publicKey),
    };
  };
  ```
</Accordion>

## Initialization parameters

| Property       | Type     | Required | Description                                                                                                                                                                                                                                                         |
| -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sessionToken` | `string` | ✅        | The [session token](/platform/guides/api-and-sdk-credentials#session-token) obtained from your server when [creating a session](/platform/guides/connect-a-customer#create-a-session).                                                                              |
| `publicKey`    | `string` | ✅        | An ephemeral public key generated on the client. See [requirements](#requirements) for details.<br /><br />The frame uses this key to encrypt the [client credentials](/platform/guides/api-and-sdk-credentials#client-credentials) returned from the connect flow. |
| `channelId`    | `string` | ✅        | A unique identifier for the frame generated on your client. This value is attached to each `postMessage` payload to help identify messages.<br /><br />The format of this string is up to you.                                                                      |

## Events

All events are dispatched using the message pattern described in the [frames protocol](/platform/frames/overview#frames-protocol#messages). Below are the event payloads specific to the check frame.

### Outbound events

<Badge>
  frame->parent
</Badge>

These events are sent from this frame to the parent window.

#### `handshake`

The frame requests that you open a message channel.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type HandshakeEvent = Message<{
    kind: "handshake";
  }>;
  ```
</CodeGroup>

#### `complete`

The frame finished checking the customer’s connection status.

<CodeGroup>
  ```json Example expandable theme={null}
  // Active
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "status": "active",
      "customer": {
        "id": "Y3VzX2FiYzEyMw=="
      },
      "credentials": "<encrypted_value>",
      "capabilities": {
        "ramps": {
          "requirements": {}
        }
      }
    }
  }

  // Pending
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "status": "pending"
    }
  }

  // Unavailable
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "status": "unavailable"
    }
  }

  // Failed
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "status": "failed",
      "reason": "Unable to create MoonPay account."
    }
  }

  // Connection required
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "status": "connectionRequired",
      "credentials": "<encrypted_value>"
    }
  }
  ```

  ```ts twoslash TypeScript definition expandable theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  enum ConnectionStatus {
    /** The connection is valid and can be used. **/
    active = "active",
    /** The connection could not be completed. This typically occurs for customers whose KYC decisions are delayed. Often these cases are resolved out of band and the customer can connect on a subsequent visit to your app. **/
    pending = "pending",
    /** The connection cannot be used at the current time. This typically occurs when a KYC-verified customer is using a device or application from a restricted location. **/
    unavailable = "unavailable",
    /** The connection was not created or is invalid and should not be retried. This usually happens if a customer fails KYC or cannot be onboarded to MoonPay. It can also happen if a customer rejects a connection to your application. In these cases, direct the customer to an alternate flow within your app. **/
    failed = "failed",
    /** A new connection needs to be created. **/
    connectionRequired = "connectionRequired",
  }

  type PaymentDisclosuresRequirement = {
    /** The customer's ISO 3166-1 alpha-3 residential country code. E.g. `"USA"` or `"FRA"` */
    country: string;
    /** The state or province code, when disclosures apply to a subdivision. E.g. `"NY"` or `"WA"` */
    administrativeArea?: string;
    /** The broader regulatory area for the country, when applicable. Currently `"EEA"`. */
    area?: string;
  };

  type CustomerCapabilities = {
    ramps: {
      requirements: {
        /** Present when disclosure geography is available. Use `country`, `administrativeArea`, and `area` to determine which disclosure, if any, applies. **/
        paymentDisclosures?: PaymentDisclosuresRequirement;
      };
    };
  };

  type ActiveConnection = {
    status: ConnectionStatus.active;
    /** The MoonPay customer associated with this connection. **/
    customer: {
      /** The MoonPay customer identifier. **/
      id: string;
    };
    /** Encrypted client credentials containing the accessToken and clientToken. Once decrypted, the value contains a stringified JSON object with the following structure:
     *
     * {
     *   "accessToken": "<token>",
     *   "clientToken": "<token>",
     *   "expiresAt": "<iso8601>",
     * }
     *
     * - `accessToken`: A token that can be used to make API requests from the client.
     * - `clientToken`: A token that can be used to initialize sensitive frames such as Apple Pay.
     * - `expiresAt`: An ISO 8601 formatted string indicating when the tokens expire.
     **/
    credentials: string;
    /**
     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted string.
     *
     * Example: `2026-06-15T13:00:23Z`
     */
    expiresAt: string;
    /** Regulatory capabilities for the connected customer. **/
    capabilities: CustomerCapabilities;
  };

  type PendingConnection = {
    status: ConnectionStatus.pending;
  };

  type UnavailableConnection = {
    status: ConnectionStatus.unavailable;
  };

  type FailedConnection = {
    status: ConnectionStatus.failed;
    /** A developer-friendly description for the failure. **/
    reason: string;
  };

  type RequiredConnection = {
    status: ConnectionStatus.connectionRequired;
    /** Encrypted anonymous client credentials. Store these and use the decrypted `clientToken` to initialize the connect frame.
     *
     * Once decrypted, the value contains a stringified JSON object with the following structure:
     * {
     *   "accessToken": "<token>",
     *   "clientToken": "<token>",
     *   "expiresAt": "<iso8601>",
     * }
     *
     * When authentication completes via the connect frame, replace these with the authenticated credentials returned from the connect flow.
     **/
    credentials: string;
  };

  type ConnectionCompleteEvent = Message<{
    kind: "complete";
    payload:
      | ActiveConnection
      | PendingConnection
      | UnavailableConnection
      | FailedConnection
      | RequiredConnection;
  }>;
  ```
</CodeGroup>

#### `error`

This event dispatches errors that occur in the flow and, if available, provides steps for recovery.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "error",
    "payload": {
      "code": "ipAddressMismatch",
      "message": "The client IP address does not match the session."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ConnectFlowError = Message<{
    kind: "error";
    payload: {
      code: "ipAddressMismatch" | "invalidSessionToken" | "generic";
      /** A developer-facing error message with details on recovery or documentation. This message is not intended to be rendered in UI. */
      message: string;
    };
  }>;
  ```
</CodeGroup>

### Inbound events

<Badge>
  parent->frame
</Badge>

These events are sent from the parent window to this frame.

#### `ack`

Acknowledge the [handshake](#handshake).

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AckEvent = Message<{
    kind: "ack";
  }>;
  ```
</CodeGroup>


# Connect flow
Source: https://dev.moonpay.com/platform/frames/connect

Details on working with the [connect](/platform/guides/connect-a-customer) frame.

## URL

```html theme={null}
https://blocks.moonpay.com/platform/v1/connect
```

## Requirements

### Permissions

The following [permission policies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes) are required:

* `accelerometer`
* `autoplay`
* `camera`
* `encrypted-media`
* `gyroscope`

```tsx Example theme={null}
<iframe
  src="https://blocks.moonpay.com/platform/v1/connect"
  allow="accelerometer; autoplay; camera; encrypted-media; gyroscope"
/>
```

### Key exchange

Credentials returned from the frame are encrypted to protect their content since they are sent over `postMessage`. You need to generate an [X25519](https://datatracker.ietf.org/doc/html/rfc7748#section-5) keypair and pass the public key into the frame. The frame uses your public key to encrypt the payload, ensuring only you can read it with your private key.

<Warning>
  Never persist the private key to disk or storage. Hold it in memory only for
  the duration of the session.
</Warning>

<Frame>
  <img alt="Frame credential verification lifecycle" />

  <img alt="Frame credential verification lifecycle" />
</Frame>

The frame uses the [@noble/curves](https://github.com/paulmillr/noble-curves) library internally. On web and React Native, you can use this same library to generate your keypair and handle decryption. For native platforms, use a compatible utility like [CryptoKit](https://developer.apple.com/documentation/cryptokit/curve25519) on iOS or [KeyPairGenerator](https://developer.android.com/reference/java/security/KeyPairGenerator) on Android.

<Accordion title="Example crypto module for web" icon="brackets-curly">
  The following example shows how to generate a keypair and decrypt credentials using `@noble/curves`. You'll want to add your own error handling and input validation for production use.

  <CodeGroup>
    ```sh pnpm theme={null}
    pnpm i @noble/curves @noble/hashes @noble/ciphers
    ```

    ```sh bun theme={null}
    bun add @noble/curves @noble/hashes @noble/ciphers
    ```

    ```sh npm theme={null}
    npm i @noble/curves @noble/hashes @noble/ciphers
    ```
  </CodeGroup>

  ```ts crypto.ts theme={null}
  // An example module for generating keypairs and decrypting client credentials.
  // This should not be used as-is in production!

  import { gcm } from "@noble/ciphers/aes.js";
  import { x25519 } from "@noble/curves/ed25519.js";
  import { hkdf } from "@noble/hashes/hkdf.js";
  import { sha256 } from "@noble/hashes/sha2.js";

  /** The credentials returned from the connect flow. */
  export type ClientCredentials = {
    /** A JWT used to authenticate client requests to the Moonpay API. */
    accessToken: string;
    /** A JWT used to initialize authenticated frames such as Apple Pay. */
    clientToken: string;
    /** An [ISO 8601 timestamp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) representing the expiration time of the tokens. */
    expiresAt: string;
  };

  /** X25519 `privateKey` and `publicKey`as hex strings. */
  export type KeyPair = Record<"privateKey" | "publicKey", string>;

  export type DecryptClientCredentialsResult =
    | { ok: true; value: ClientCredentials }
    | { ok: false; error: string };

  const hexToBytes = (hex: string): Uint8Array => {
    if (hex.length % 2 !== 0) {
      throw new Error("Invalid hex string");
    }

    const bytes = new Uint8Array(hex.length / 2);
    for (let i = 0; i < bytes.length; i++) {
      bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
    }
    return bytes;
  };

  const bytesToHex = (bytes: Uint8Array): string => {
    return Array.from(bytes)
      .map((b) => b.toString(16).padStart(2, "0"))
      .join("");
  };

  /** Decrypts an encrypted `ClientCredentials`. */
  export const decryptClientCredentials = (
    /** A base64-encoded string representing the encrypted JSON payload. **/
    encryptedCredentials: string,
    /** The recipient's X25519 private key as a hex string. **/
    privateKeyHex: string,
  ): DecryptClientCredentialsResult => {
    // Base64 decode the encrypted credentials
    const payload = atob(encryptedCredentials);

    // Guard and validate this deserialization
    const parsedPayload = JSON.parse(payload);
    // Convert the private key from a hex string to a `Uint8Array`
    const privateKey = hexToBytes(privateKeyHex);
    // Convert the ephemeral public key from a hex string to a `Uint8Array`
    const publicKey = hexToBytes(parsedPayload.ephemeralPublicKey);
    const ivBytes = hexToBytes(parsedPayload.iv);
    const ciphertextBytes = hexToBytes(parsedPayload.ciphertext);
    const sharedSecret = x25519.getSharedSecret(privateKey, publicKey);

    const encryptionKey = hkdf(sha256, sharedSecret, undefined, undefined, 32);
    const cipher = gcm(encryptionKey, ivBytes);
    const plainTextBytes = cipher.decrypt(ciphertextBytes);
    const plaintext = new TextDecoder().decode(plainTextBytes);

    let parsed: unknown;
    try {
      parsed = JSON.parse(plaintext);
    } catch {
      return { ok: false, error: "Failed to parse decrypted payload as JSON" };
    }

    // Validate the decrypted payload
    if (
      typeof parsed !== "object" ||
      parsed === null ||
      typeof (parsed as Record<string, unknown>).accessToken !== "string" ||
      typeof (parsed as Record<string, unknown>).clientToken !== "string" ||
      typeof (parsed as Record<string, unknown>).expiresAt !== "string"
    ) {
      return { ok: false, error: "Decrypted payload missing required fields" };
    }

    return { ok: true, value: parsed as ClientCredentials };
  };

  /** Generates a new X25519 key pair encryption. */
  export const generateKeyPair = (): KeyPair => {
    const { secretKey: privateKey, publicKey } = x25519.keygen();

    return {
      privateKey: bytesToHex(privateKey),
      publicKey: bytesToHex(publicKey),
    };
  };
  ```
</Accordion>

<Accordion title="Example crypto module for React Native" icon="mobile">
  The following example shows how to generate a keypair and decrypt credentials using `@noble/curves`. You'll want to add your own error handling and input validation for production use.

  In React Native, yuo will need a [polyfill for `getRandomValues`](https://github.com/LinusU/react-native-get-random-values) ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)) which is only available in browsers.

  <CodeGroup>
    ```sh pnpm theme={null}
    pnpm i react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers
    ```

    ```sh bun theme={null}
    bun add react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers
    ```

    ```sh npm theme={null}
    npm i react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers
    ```
  </CodeGroup>

  ```ts crypto.ts theme={null}
  // An example module for generating keypairs and decrypting client credentials.
  // This should not be used as-is in production!

  import { gcm } from "@noble/ciphers/aes.js";
  import { x25519 } from "@noble/curves/ed25519.js";
  import { hkdf } from "@noble/hashes/hkdf.js";
  import { sha256 } from "@noble/hashes/sha2.js";
  // React Native polyfill for getRandomValues
  import "react-native-get-random-values";

  /** The credentials returned from the connect flow. */
  export type ClientCredentials = {
    /** A JWT used to authenticate client requests to the Moonpay API. */
    accessToken: string;
    /** A JWT used to initialize authenticated frames such as Apple Pay. */
    clientToken: string;
    /** An [ISO 8601 timestamp](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString) representing the expiration time of the tokens. */
    expiresAt: string;
  };

  /** X25519 `privateKey` and `publicKey`as hex strings. */
  export type KeyPair = Record<"privateKey" | "publicKey", string>;

  export type DecryptClientCredentialsResult =
    | { ok: true; value: ClientCredentials }
    | { ok: false; error: string };

  const hexToBytes = (hex: string): Uint8Array => {
    if (hex.length % 2 !== 0) {
      throw new Error("Invalid hex string");
    }

    const bytes = new Uint8Array(hex.length / 2);
    for (let i = 0; i < bytes.length; i++) {
      bytes[i] = parseInt(hex.substr(i * 2, 2), 16);
    }
    return bytes;
  };

  const bytesToHex = (bytes: Uint8Array): string => {
    return Array.from(bytes)
      .map((b) => b.toString(16).padStart(2, "0"))
      .join("");
  };

  /** Decrypts an encrypted `ClientCredentials`. */
  export const decryptClientCredentials = (
    /** A base64-encoded string representing the encrypted JSON payload. **/
    encryptedCredentials: string,
    /** The recipient's X25519 private key as a hex string. **/
    privateKeyHex: string,
  ): DecryptClientCredentialsResult => {
    // Base64 decode the encrypted credentials
    const payload = atob(encryptedCredentials);

    // Guard and validate this deserialization
    const parsedPayload = JSON.parse(payload);
    // Convert the private key from a hex string to a `Uint8Array`
    const privateKey = hexToBytes(privateKeyHex);
    // Convert the ephemeral public key from a hex string to a `Uint8Array`
    const publicKey = hexToBytes(parsedPayload.ephemeralPublicKey);
    const ivBytes = hexToBytes(parsedPayload.iv);
    const ciphertextBytes = hexToBytes(parsedPayload.ciphertext);
    const sharedSecret = x25519.getSharedSecret(privateKey, publicKey);

    const encryptionKey = hkdf(sha256, sharedSecret, undefined, undefined, 32);
    const cipher = gcm(encryptionKey, ivBytes);
    const plainTextBytes = cipher.decrypt(ciphertextBytes);
    const plaintext = new TextDecoder().decode(plainTextBytes);

    let parsed: unknown;
    try {
      parsed = JSON.parse(plaintext);
    } catch {
      return { ok: false, error: "Failed to parse decrypted payload as JSON" };
    }

    // Validate the decrypted payload
    if (
      typeof parsed !== "object" ||
      parsed === null ||
      typeof (parsed as Record<string, unknown>).accessToken !== "string" ||
      typeof (parsed as Record<string, unknown>).clientToken !== "string" ||
      typeof (parsed as Record<string, unknown>).expiresAt !== "string"
    ) {
      return { ok: false, error: "Decrypted payload missing required fields" };
    }

    return { ok: true, value: parsed as ClientCredentials };
  };

  /** Generates a new X25519 key pair encryption. */
  export const generateKeyPair = (): KeyPair => {
    const { secretKey: privateKey, publicKey } = x25519.keygen();

    return {
      privateKey: bytesToHex(privateKey),
      publicKey: bytesToHex(publicKey),
    };
  };
  ```
</Accordion>

## Initialization parameters

| Property      | Type     | Required | Description                                                                                                                                                                                                                                                         |
| ------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientToken` | `string` | ✅        | The anonymous client token obtained after decrypting the `credentials` returned by the [check frame](/platform/frames/check) when the status is `connectionRequired`.                                                                                               |
| `publicKey`   | `string` | ✅        | An ephemeral public key generated on the client. See [requirements](#requirements) for details.<br /><br />The frame uses this key to encrypt the [client credentials](/platform/guides/api-and-sdk-credentials#client-credentials) returned from the connect flow. |
| `channelId`   | `string` | ✅        | A unique identifier for the frame generated on your client. This value is attached to each `postMessage` payload to help identify messages.<br /><br />The format of this string is up to you.                                                                      |
| `theme`       | `string` |          | Pass `dark` or `light` to force a specific appearance. If you omit this, the frame uses the user's system appearance.                                                                                                                                               |

## Events

All events are dispatched using the message pattern described in the [frames protocol](/platform/frames/overview#frames-protocol#messages). Below are the event payloads specific to the connect frame.

### Outbound events

<Badge>
  frame->parent
</Badge>

These events are sent from this frame to the parent window.

#### `handshake`

The frame requests that you open a message channel.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": {
      "channelId": "ch_1"
    },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type HandshakeEvent = Message<{
    kind: "handshake";
  }>;
  ```
</CodeGroup>

#### `ready`

The frame finished loading and the UI is fully rendered. You can use this to coordinate UI transitions, but you don’t need it to complete the flow.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ready"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ReadyEvent = Message<{
    kind: "ready";
  }>;
  ```
</CodeGroup>

#### `complete`

The connect flow finished. If it succeeds, the payload includes encrypted client credentials.

<CodeGroup>
  ```json Example expandable theme={null}
  // Active
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "status": "active",
      "customer": {
        "id": "Y3VzX2FiYzEyMw=="
      },
      "credentials": "<encrypted_value>",
      "capabilities": {
        "ramps": {
          "requirements": {}
        }
      }
    }
  }

  // Pending
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "status": "pending"
    }
  }

  // Unavailable
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "status": "unavailable"
    }
  }

  // Failed
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "status": "failed",
      "reason": "Unable to create MoonPay account."
    }
  }
  ```

  ```ts twoslash TypeScript definition expandable theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  enum ConnectionStatus {
    /** The connection is valid and can be used. **/
    active = "active",
    /** The connection could not be completed. This typically occurs for customers whose KYC decisions are delayed. Often these cases are resolved out of band and the customer can connect on a subsequent visit to your app. **/
    pending = "pending",
    /** The connection cannot be used at the current time. This typically occurs when a KYC-verified customer is using a device or application from a restricted location. **/
    unavailable = "unavailable",
    /** The connection was not created or is invalid and should not be retried. This usually happens if a customer fails KYC or cannot be onboarded to MoonPay. It can also happen if a customer rejects a connection to your application. In these cases, direct the customer to an alternate flow within your app. **/
    failed = "failed",
  }

  type PaymentDisclosuresRequirement = {
    /** The customer's ISO 3166-1 alpha-3 residential country code. E.g. `"USA"` or `"FRA"` */
    country: string;
    /** The state or province code, when disclosures apply to a subdivision. E.g. `"NY"` or `"WA"` */
    administrativeArea?: string;
    /** The broader regulatory area for the country, when applicable. Currently `"EEA"`. */
    area?: string;
  };

  type CustomerCapabilities = {
    ramps: {
      requirements: {
        /** Present when disclosure geography is available. Use `country`, `administrativeArea`, and `area` to determine which disclosure, if any, applies. **/
        paymentDisclosures?: PaymentDisclosuresRequirement;
      };
    };
  };

  type ActiveConnection = {
    status: ConnectionStatus.active;
    /** The MoonPay customer associated with this connection. **/
    customer: {
      /** The MoonPay customer identifier. **/
      id: string;
    };
    /** Encrypted client credentials containing the accessToken and clientToken. Once decrypted, the value contains a stringified JSON object with the following structure:
     *
     * {
     *   "accessToken": "<token>",
     *   "clientToken": "<token>",
     *   "expiresAt": "<iso8601>",
     * }
     *
     * - `accessToken`: A token that can be used to make API requests from the client.
     * - `clientToken`: A token that can be used to initialize sensitive frames such as Apple Pay.
     * - `expiresAt`: An ISO 8601 formatted string indicating when the tokens expire.
     **/
    credentials: string;
    /**
     * An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) formatted string.
     *
     * Example: `2026-06-15T13:00:23Z`
     */
    expiresAt: string;
    /** Regulatory capabilities for the connected customer. **/
    capabilities: CustomerCapabilities;
  };

  type PendingConnection = {
    status: ConnectionStatus.pending;
  };

  type UnavailableConnection = {
    status: ConnectionStatus.unavailable;
  };

  type FailedConnection = {
    status: ConnectionStatus.failed;
    /** A developer-friendly description for the failure. **/
    reason: string;
  };

  type ConnectionCompleteEvent = Message<{
    kind: "complete";
    payload:
      | ActiveConnection
      | PendingConnection
      | UnavailableConnection
      | FailedConnection;
  }>;
  ```
</CodeGroup>

#### `error`

This event dispatches errors that occur in the flow and, if available, provides steps for recovery.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "error",
    "payload": {
      "code": "ipAddressMismatch",
      "message": "The client IP address does not match the session."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ConnectFlowError = Message<{
    kind: "error";
    payload: {
      code: "ipAddressMismatch" | "invalidSessionToken" | "generic";
      /** A developer-facing error message with details on recovery or documentation. This message is not intended to be rendered in UI. */
      message: string;
    };
  }>;
  ```
</CodeGroup>

### Inbound events

<Badge>
  parent->frame
</Badge>

These events are sent from the parent window to this frame.

#### `ack`

Acknowledge the [handshake](#handshake).

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AckEvent = Message<{
    kind: "ack";
  }>;
  ```
</CodeGroup>


# Google Pay
Source: https://dev.moonpay.com/platform/frames/google-pay

Details on working with the [Google Pay](/platform/guides/pay-with-google-pay) frame.

## URL

```html theme={null}
https://blocks.moonpay.com/platform/v1/google-pay
```

## Requirements

### Size

The frame container **height must be 44px**. Width is flexible; the Google Pay button inside the frame uses 100% of the container width.

### Permissions

The `payment` [permission policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes) is required.

When using a sandboxed iframe, include `allow-scripts`, `allow-popups`, `allow-same-origin`, and `allow-forms`. See [Google Pay inside sandboxed iframe for PCI DSS v4 compliance](https://developers.googleblog.com/google-pay-inside-sandboxed-iframe-for-pci-dss-v4-compliance/) for details.

```tsx Example theme={null}
<iframe
  src="https://blocks.moonpay.com/platform/v1/google-pay"
  allow="payment"
/>
```

## Initialization parameters

| Property                | Type     | Required | Description                                                                                                                                                                                    |
| ----------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clientToken`           | `string` | ✅        | The [client token](/platform/guides/api-and-sdk-credentials#client-token) returned from the [connect flow](/platform/guides/connect-a-customer).                                               |
| `channelId`             | `string` | ✅        | A unique identifier for the frame generated on your client. This value is attached to each `postMessage` payload to help identify messages.<br /><br />The format of this string is up to you. |
| `signature`             | `string` | ✅        | The quote `signature` from the quote endpoint. Pass `signature` as returned.                                                                                                                   |
| `externalTransactionId` | `string` |          | Your own identifier for the transaction. Stored and associated with the MoonPay transaction for correlation.                                                                                   |

## Events

All events are dispatched using the message pattern described in the [frames protocol](/platform/frames/overview#frames-protocol#messages). Below are the event payloads specific to the Google Pay frame.

### Outbound events

<Badge>
  frame->parent
</Badge>

These events are sent from this frame to the parent window.

#### `handshake`

The frame requests that you open a message channel.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type HandshakeEvent = Message<{
    kind: "handshake";
  }>;
  ```
</CodeGroup>

#### `ready`

The frame finished loading and the UI is fully rendered. You can use this to coordinate UI transitions if needed.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ready"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ReadyEvent = Message<{
    kind: "ready";
  }>;
  ```
</CodeGroup>

#### `complete`

The transaction is complete. Use the transaction ID to track status updates (for example, by polling or via webhooks).

<CodeGroup>
  ```json Example (success) theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "transaction": {
        "id": "txn_01",
        "status": "pending"
      }
    }
  }
  ```

  ```json Example (fail) theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "transaction": {
        "status": "failed",
        "failureReason": "The payment could not be completed with the selected card."
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  enum TransactionStatus {
    /** The transaction has successfully completed. The payment has been made and the crypto has been transferred. **/
    completed = "completed",
    /** The payment has been completed and the crypto transfer is underway. **/
    pending = "pending",
    /** The transaction has failed. No payment was applied and the crypto was not transferred. **/
    failed = "failed",
  }

  type Transaction =
    | {
        /** The MoonPay identifier for this transaction. **/
        id: string;
        /** The status of the transaction. **/
        status: TransactionStatus.completed | TransactionStatus.pending;
      }
    | {
        status: TransactionStatus.failed;
        /** A developer-friendly error message detailing the reason for the transaction failure. **/
        failureReason: string;
      };

  type GooglePayCompleteEvent = Message<{
    kind: "complete";
    payload: {
      transaction: Transaction;
    };
  }>;
  ```
</CodeGroup>

#### `challenge`

Verification is required before the transaction can proceed. Render the
[challenge frame](/platform/frames/challenge) at the provided URL. Do not
construct the URL yourself — use it as-is.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "challenge",
    "payload": {
      "kind": "frame",
      "url": "https://blocks.moonpay.com/platform/v1/challenge?challengeToken=..."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type GooglePayChallengeEvent = Message<{
    kind: "challenge";
    payload: {
      kind: string;
      /** Fully-formed URL to pass directly as the challenge frame src. */
      url: string;
    };
  }>;
  ```
</CodeGroup>

#### `error`

This event dispatches errors that occur in the flow and, if available, provides steps for recovery.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "error",
    "payload": {
      "code": "configurationError",
      "message": "The frame configuration is invalid."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type GooglePayError = Message<{
    kind: "error";
    payload: {
      code:
        | "configurationError"
        | "quoteExpired"
        | "invalidQuote"
        | "googlePayUnavailable"
        | "generic";
      /** A developer-facing error message with details on recovery or documentation. This message is not intended to be rendered in UI. */
      message: string;
    };
  }>;
  ```
</CodeGroup>

| Code                   | Description                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| `configurationError`   | The frame configuration is invalid. Check initialization parameters. |
| `quoteExpired`         | The quote has expired. Fetch a new quote and send it via `setQuote`. |
| `invalidQuote`         | The quote signature is invalid or malformed.                         |
| `googlePayUnavailable` | Google Pay is not available in the current environment or browser.   |
| `generic`              | An unexpected error occurred.                                        |

### Inbound events

<Badge>
  parent->frame
</Badge>

These events are sent from the parent window to this frame.

#### `ack`

Acknowledge the [handshake](#handshake).

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AckEvent = Message<{
    kind: "ack";
  }>;
  ```
</CodeGroup>

#### `setQuote`

Provide a new quote to the frame. Pass `signature` as returned by the quote endpoint. Upon receiving this event, the frame disables the Google Pay button until the quote is revalidated.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "setQuote",
    "payload": {
      "quote": {
        "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type SetQuoteEvent = Message<{
    kind: "setQuote";
    payload: {
      quote: {
        /** The signature from a valid quote. **/
        signature: string;
      };
    };
  }>;
  ```
</CodeGroup>


# Overview
Source: https://dev.moonpay.com/platform/frames/overview

Protocol details for co-branded and headless [frames](/platform/overview/core-concepts#frames).

Frames communicate with your app using `postMessage`. Each frame defines its own events and payloads. If you use the MoonPay SDK, it handles message serialization, validation, and dispatch for you. If you integrate frames directly (for example, with your own WebView or iframe wrapper), this page documents the shared protocol so you know what to implement.

## Libraries

<Badge>
  Coming soon!
</Badge>

If you’re not using the SDK, MoonPay libraries can help you manage `postMessage` communication on web and mobile (via WebViews). Until those ship, use the protocol details below to build your own bridge.

## Frames protocol

### Messages

Frames use an event-driven model. You and the frame exchange events using a strongly typed message structure. Treat these messages like an API contract between two parties: the parent window (or app) and the frame.

#### Transport

In both web and mobile apps, frames send and receive messages over `postMessage` as **stringified JSON**.

If you integrate directly, you handle serialization and validation yourself. If you use the SDK, it handles this for you.

#### Format

Every message follows the same envelope format. The `kind` tells you what event you’re handling, and the `payload` shape depends on that `kind`.

| Field            | Type                   | Required | Description                                                                           |
| ---------------- | ---------------------- | -------- | ------------------------------------------------------------------------------------- |
| `version`        | `2`                    | ✅        | The frames protocol version.<br /><br />This value will always be `2`.                |
| `meta`           | `object`               | ✅        | Transport metadata for the message.                                                   |
| `meta.channelId` | `string`               | ✅        | A unique identifier for messages between frames.                                      |
| `kind`           | `enum<FrameEventKind>` | ✅        | The name of the event.                                                                |
| `payload`        | `object`               |          | An object containing the data for different events. This value depends on the `kind`. |

<CodeGroup>
  ```json Example payload (deserialized) theme={null}
  {
    "version": 2,
    "meta": {
      "channelId": "some_unique_value"
    },
    "kind": "example",
    "payload": {
      "example": "an example payload"
    }
  }
  ```

  ```json Example payload (serialized) theme={null}
  "{\"version\":\"2\",\"meta\":{\"channelId\":\"some_unique_value\"},\"kind\":\"example\",\"payload\":{\"example\":\"an example payload\"}}"
  ```
</CodeGroup>

#### Validation and safety checks

You’ll have an easier time (and fewer mysterious bugs) if you validate messages like you would any external input:

* **Check the origin and sender**: only accept messages from the frame origin(s) you expect, and ignore everything else.
* **Parse defensively**: `postMessage` delivers strings; treat JSON parsing as fallible and handle errors.
* **Verify the envelope**: reject messages that don’t match the expected `version`, don’t include a `meta.channelId`, or use an unknown `kind`.
* **Route by `channelId`**: if you can have multiple frames open at once, use `meta.channelId` to keep messages from crossing streams.

### Lifecycle

Each frame follows the same basic handshake lifecycle to establish a bi-directional channel with your app. The SDK manages this automatically and gives you an events callback; in a direct integration, you implement these steps yourself.

```mermaid theme={null}
sequenceDiagram
    %% autonumber

    participant a as App
    participant f as Frame

    %% -----------------

    activate f
      a ->> a: Generate a channel ID
      a ->> f: Inject the WebView or iframe with<br />URL params including a channelId.

      alt If no handshake request received in 5s
        a -x a: Handle loading error
      end

      f ->> a: Send handshake w/channel ID
      a ->> f: Reply with ack (w/channel ID)

      f ->> f: Validate params

      break Invalid params
        f -x a: Send error and terminate the connection
      end


        f <<->> a: Bi-directional channel opened


    deactivate f
```

In practice, you’ll typically: generate a channel, wait for the handshake, ack it, then start handling `kind` events for that channel. If the handshake doesn’t arrive quickly, fail fast and show a useful error to the developer (or retry, if that fits your app).


# Reset
Source: https://dev.moonpay.com/platform/frames/reset

Clear a user's session and authentication state

The reset frame is a headless page hosted on a MoonPay domain. Use it to clear the user's authentication tokens stored on MoonPay's domain, allowing partners to log users out. The frame communicates completion or errors to the parent window via postMessage.

## URL

```html theme={null}
https://blocks.moonpay.com/platform/v1/reset
```

## Initialization parameters

| Parameter   | Type     | Required | Description                                                                                                                                                                                    |
| ----------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `channelId` | `string` | ✅        | A unique identifier for the frame generated on your client. This value is attached to each `postMessage` payload to help identify messages.<br /><br />The format of this string is up to you. |
| `apiKey`    | `string` |          | Your publishable API key.                                                                                                                                                                      |
| `language`  | `string` |          | Language code for localization.                                                                                                                                                                |
| `theme`     | `string` |          | `light` or `dark`.                                                                                                                                                                             |

## Events

All events are dispatched using the message pattern described in the [frames protocol](/frames/overview#frames-protocol#messages). Below are the event payloads specific to the reset frame.

### Outbound events

<Badge>
  frame->parent
</Badge>

These events are sent from this frame to the parent window.

#### `handshake`

Sent when the frame loads. The parent must respond with `ack`.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type HandshakeEvent = Message<{
    kind: "handshake";
  }>;
  ```
</CodeGroup>

#### `complete`

Sent when the user's session has been successfully cleared.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ResetCompleteEvent = Message<{
    kind: "complete";
  }>;
  ```
</CodeGroup>

#### `error`

Sent when the reset fails.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "error",
    "payload": {
      "code": "generic",
      "message": "Failed to clear session"
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ResetErrorEvent = Message<{
    kind: "error";
    payload: {
      code: "generic";
      /** A developer-facing error message with details on recovery or documentation. This message is not intended to be rendered in UI. */
      message: string;
    };
  }>;
  ```
</CodeGroup>

### Inbound events

<Badge>
  parent->frame
</Badge>

These events are sent from the parent window to this frame.

#### `ack`

Must be sent in response to `handshake`. The frame will not proceed until it receives this.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AckEvent = Message<{
    kind: "ack";
  }>;
  ```
</CodeGroup>


# Widget
Source: https://dev.moonpay.com/platform/frames/widget

Details on working with the [widget](/platform/guides/pay-with-widget) frame.

## URL

```html theme={null}
https://blocks.moonpay.com/platform/v1/widget
```

## Requirements

### Permissions

The `payment` [permission policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes) is required.

```tsx Example theme={null}
<iframe src="https://blocks.moonpay.com/platform/v1/widget" allow="payment" />
```

## Initialization parameters

| Property         | Type     | Required | Description                                                                                                                                                                                    |
| ---------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `flow`           | `string` | ✅        | The transaction flow. Currently only `buy` is supported.                                                                                                                                       |
| `clientToken`    | `string` | ✅        | The [client token](/platform/guides/api-and-sdk-credentials#client-token) returned from the [connect flow](/platform/guides/connect-a-customer).                                               |
| `quoteSignature` | `string` | ✅        | The quote `signature` from the quote endpoint. Pass `signature` as returned.                                                                                                                   |
| `channelId`      | `string` | ✅        | A unique identifier for the frame generated on your client. This value is attached to each `postMessage` payload to help identify messages.<br /><br />The format of this string is up to you. |

## Events

All events are dispatched using the message pattern described in the [frames protocol](/platform/frames/overview#frames-protocol#messages). Below are the event payloads specific to the widget frame.

### Outbound events

<Badge>
  frame->parent
</Badge>

These events are sent from this frame to the parent window.

#### `handshake`

The frame requests that you open a message channel.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "handshake"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type HandshakeEvent = Message<{
    kind: "handshake";
  }>;
  ```
</CodeGroup>

#### `ready`

The widget finished loading and the UI is visible.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ready"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type ReadyEvent = Message<{
    kind: "ready";
  }>;
  ```
</CodeGroup>

#### `transactionCreated`

A transaction has been initiated. The customer may still need to complete additional steps such as 3-D Secure authorization.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "transactionCreated",
    "payload": {
      "transaction": {
        "id": "txn_01",
        "status": "waitingAuthorization"
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type TransactionCreatedEvent = Message<{
    kind: "transactionCreated";
    payload: {
      transaction: {
        /** The MoonPay identifier for this transaction. **/
        id: string;
        /** The current status of the transaction. **/
        status: string;
      };
    };
  }>;
  ```
</CodeGroup>

#### `complete`

The transaction has reached a terminal state. Use the transaction ID to track status updates via polling or webhooks.

<CodeGroup>
  ```json Example (success) theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "transaction": {
        "id": "txn_01",
        "status": "complete"
      }
    }
  }
  ```

  ```json Example (fail) theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "complete",
    "payload": {
      "transaction": {
        "status": "failed",
        "failureReason": "The payment could not be completed."
      }
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  enum TransactionStatus {
    complete = "complete",
    pending = "pending",
    failed = "failed",
  }

  type Transaction =
    | {
        /** The MoonPay identifier for this transaction. **/
        id: string;
        /** The status of the transaction. **/
        status: TransactionStatus.complete | TransactionStatus.pending;
      }
    | {
        status: TransactionStatus.failed;
        /** A developer-friendly error message detailing the reason for the transaction failure. **/
        failureReason: string;
      };

  type WidgetCompleteEvent = Message<{
    kind: "complete";
    payload: {
      transaction: Transaction;
    };
  }>;
  ```
</CodeGroup>

#### `error`

An error occurred in the widget flow.

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "error",
    "payload": {
      "code": "apiError",
      "message": "Failed to build widget URL."
    }
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type WidgetError = Message<{
    kind: "error";
    payload: {
      code: "configurationError" | "apiError" | "generic";
      /** A developer-facing error message. Not intended for end-user display. */
      message: string;
    };
  }>;
  ```
</CodeGroup>

### Inbound events

<Badge>
  parent->frame
</Badge>

These events are sent from the parent window to this frame.

#### `ack`

Acknowledge the [handshake](#handshake).

<CodeGroup>
  ```json Example theme={null}
  {
    "version": 2,
    "meta": { "channelId": "ch_1" },
    "kind": "ack"
  }
  ```

  ```ts twoslash TypeScript definition theme={null}
  type Message<T> = T & {
    version: 2;
    meta: { channelId: string };
  };

  type AckEvent = Message<{
    kind: "ack";
  }>;
  ```
</CodeGroup>


# API and SDK credentials
Source: https://dev.moonpay.com/platform/guides/api-and-sdk-credentials

Understand the tokens and credentials you need for your integration.

<Callout icon="key">
  During the preview, we will work with you directly to set up your account and
  credentials.
</Callout>

## Server credentials

### Secret key

A server-to-server credential passed in the `X-Api-Key` request header.

<Warning>
  Keep your secret key secure and never expose it. Never commit it to your
  codebase or send it to your frontend.
</Warning>

<CodeGroup>
  ```text Test mode theme={null}
  X-Api-Key: sk_test_123
  ```

  ```text Live mode theme={null}
  X-Api-Key: sk_live_123
  ```
</CodeGroup>

## Client credentials

Use these to make API requests from your frontend and initialize frames for
sensitive actions.

<Warning>
  Never persist client credentials to disk or storage. Hold them in memory only.
  Use your server to get a new `sessionToken` on each app visit. When you
  receive new credentials (for example, authenticated credentials after a
  connect flow), replace the previously stored ones.
</Warning>

### Session token

A token you create on your server and send to your frontend. You use it to start a [connect flow](/platform/guides/connect-a-customer).

### Access token

A token returned from the [check frame](/platform/frames/check) and the [connect frame](/platform/frames/connect). Use it to make API requests from your frontend (via the SDK or directly), such as:

* Getting quotes
* Listing payment methods
* Listing transactions

Anonymous credentials returned when `connectionRequired` give you a scoped access token. Authenticated credentials returned after the connect flow give you a fully-privileged one. Always replace stored credentials when you receive new ones.

This token is intended for client use and shouldn’t be persisted to disk.

### Client token

A token returned from the [check frame](/platform/frames/check) and the [connect frame](/platform/frames/connect). Use it to initialize subsequent frames (for example, the Apple Pay frame or the connect frame). Within frames, this token is used to make authenticated requests.

When `connectionRequired` is returned, pass this anonymous `clientToken` to the connect frame. After authentication, replace it with the `clientToken` from the authenticated credentials.

This token is intended for client use and shouldn’t be persisted to disk.


# Connect a customer
Source: https://dev.moonpay.com/platform/guides/connect-a-customer

Connect a customer's MoonPay account to your app.

Connect a customer's MoonPay account so you can list payment methods, get executable quotes, and execute transactions. Before you start, review the [requirements](/platform/overview/requirements).

## Prerequisites

* A server that can create session tokens with your secret key.
* A client that can render frames (SDK or manual integration).

Connecting is a one or two-step process depending on whether the customer is new or returning:

* If the customer has never connected, render the co-branded connect frame.
* If the customer has connected before, first check whether their connection is still valid. You only need to render UI again if the connection has [expired](#connection-required).

For all cases, first [create a session](#create-a-session), then [check if a connection exists](#check-connection). If a connection is required, initialize the [connect flow](#connect-flow).

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor c as customer

    participant s as Your server

    box Your app
        participant fe as Your frontend
        participant cf as MoonPay frame<br/>(check connection)
        participant cnf as MoonPay frame<br />(connection UI)
    end

    participant api as MoonPay API

    %% -----------------

    c ->> fe: Customer visits app and signs in
    fe ->> s: Request session token
    s ->> api: POST /platform/v1/sessions
    api ->> s: { sessionToken: "c3N0XzAwMQ" }
    s ->> fe: Send session token

    activate cf
    fe ->> cf: getConnection()
    cf -->> fe: Dispatch result + credentials
    deactivate cf

    fe ->> fe: Store credentials

    alt active connection
    fe ->> fe: Continue to<br />buy flow
    else requires connect flow
        activate cnf
        fe ->> cnf: connect(clientToken)
        c ->> cnf: Sign in or<br />onboard to MoonPay
        cnf -->> fe: Dispatch result + credentials
        deactivate cnf

        fe ->> fe: Replace stored<br />credentials

        alt active connection?
        fe ->> fe: Continue to<br />buy flow
        end
    end



```

## Create a session

To initiate a session on your server, provide:

1. A unique identifier from your system for the customer (`externalCustomerId`).
2. The IP address of the customer's device. This is used across frames to ensure the integrity of the session.

Once initiated, you receive a [`sessionToken`](/platform/guides/api-and-sdk-credentials#session-token) to send to your frontend.

<CodeGroup>
  ```ts Create session token theme={null}
  // Server-side code example
  const url = "https://api.moonpay.com/platform/v1/sessions";

  const res = await fetch(url, {
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": "sk_test_123",
    },
    method: "POST",
    body: JSON.stringify({
      externalCustomerId: "your_user_id",
      deviceIp: "...ip address from client",
    }),
  });

  console.log(await res.json());
  ```

  ```json Result theme={null}
  {
    "sessionToken": "c3N0XzAwMQ=="
  }
  ```
</CodeGroup>

<Callout icon="book">
  Check the [API reference](/api-reference/platform/endpoints/sessions/create)
  for detailed usage.
</Callout>

## Check connection

Using the `sessionToken`, check if the customer already has an active connection. No UI appears in this step, but it runs in a frame. You can check the session using the SDK or [manually](/platform/frames/check).

The check frame always returns encrypted credentials. Hold them in memory only and do not persist them, regardless of the status returned. For an `active` connection these are authenticated credentials. For `connectionRequired`, these are anonymous credentials whose `clientToken` you pass into the connect flow.

<CodeGroup>
  ```ts Check the connection theme={null}
  import { createClient } from "@moonpay/platform";

  // Create the client with your session token
  const clientResult = createClient({
    sessionToken: "c3N0XzAwMQ==", // The session token from your server
  });

  if (!clientResult.ok) {
    // Handle error creating client
  }

  const client = clientResult.value;

  // Check if the customer has an active connection
  const connectionResult = await client.getConnection();

  if (!connectionResult.ok) {
    // Handle error
  }

  console.log(connectionResult.value);
  ```

  ```ts Result (active) theme={null}
  {
    status: "active",
    customer: {
      id: "Y3VzX2FiYzEyMw=="
    },
    credentials: {
      accessToken: "c2F0XzAwMQ==",
      clientToken: "c2N0XzAwMQ=="
    }
  }
  ```

  ```ts Result (requires connection) theme={null}
  {
    status: "connectionRequired",
    credentials: {
      accessToken: "c2F0XzAwMQ==",
      clientToken: "c2N0XzAwMQ=="
    }
  }
  ```
</CodeGroup>

The SDK injects an invisible frame to check the connection. If you are integrating without the SDK, load the frame directly and listen for the [`postMessage` events](/platform/frames/check#events).

## Low-friction authentication

You can simplify login for returning customers by passing the optional `email` and `phoneNumber` parameters when you [create a session](/api-reference/platform/endpoints/sessions/create).

If these values match an existing MoonPay account, the [connect frame](#connect-flow) skips the full login and prompts the customer to enter an OTP code sent to their phone.

## Connect flow

If you need to create or revalidate a connection, initialize the connect flow with the `clientToken` from the anonymous credentials returned by the check frame. The SDK provides hooks to coordinate rendering the connect UI (for example, to animate a modal or sheet). You can also do this [manually](/platform/frames/connect).

When the connect flow completes, replace the anonymous credentials from the check step with the authenticated credentials from the `complete` event.

The resulting connection has one of the following [statuses](#connection-statuses): `active`, `pending`, `unavailable`, or `failed`.

<Callout icon="book">
  In mobile apps, present the connect flow as a full sheet. See [presentation
  and appearance](/platform/guides/presentation-and-appearance) for UI guidance.
</Callout>

<CodeGroup>
  ```ts Initialize connect with SDK theme={null}
  import { createClient, type ConnectEvent } from "@moonpay/platform";

  // Create the client
  const clientResult = createClient({
    sessionToken: "c3N0XzAwMQ==", // The session token from your server
  });

  if (!clientResult.ok) {
    // Handle error creating client
  }

  const client = clientResult.value;

  // Initialize the connect flow
  const connectResult = await client.connect({
    container: connectContainer, // DOM element to render the connect frame

    theme: { appearance: "dark" }, // Optional: force dark or light mode

    onEvent: (event: ConnectEvent) => {
      switch (event.kind) {
        case "ready":
          // The frame is ready and rendered
          break;

        case "complete":
          // The connection is complete
          console.log(event.connection);
          // { status: "active", customer: { id: "..." }, credentials: { accessToken: "...", clientToken: "..." } }

          // You can unmount the frame using the reference in the payload
          event.payload.frame.dispose();
          break;

        case "error":
          // Handle error
          console.error(event.payload.message);
          break;
      }
    },
  });

  // If there is an error setting up the connect frame, no events will be
  // dispatched via the `onEvent` callback and you will receive an error here.
  if (!connectResult.ok) {
    // Handle error
  }

  // If the frame is successfully mounted, the returned value provides a reference for disposal at any time.
  connectResult.value.dispose();
  ```

  ```ts Result (complete event) theme={null}
  {
    kind: "complete",
    connection: {
      status: "active",
      customer: {
        id: "Y3VzX2FiYzEyMw=="
      },
      credentials: {
        accessToken: "c2F0XzAwMQ==",
        clientToken: "c2N0XzAwMQ=="
      },
      capabilities: {
        ramps: {
          requirements: {}
        }
      }
    },
    payload: {
      frame: {
        dispose: [Function]
      }
    }
  }
  ```
</CodeGroup>

When you receive the `complete` event, the payload includes authenticated client
credentials and a `customer` object identifying the connected MoonPay customer.
Discard any anonymous credentials from the check step and use the new ones instead.
Use them to make scoped API calls from your frontend (for example, listing
payment methods and getting quotes). See [Pay with Apple
Pay](/platform/guides/pay-with-apple-pay) for a complete example flow.

### Capabilities

The `complete` event also includes a `capabilities` object that describes regulatory requirements for the connected customer. You can use this to customize your UI before initiating a transaction; for example, determining whether a payment disclosure is required.

<CodeGroup>
  ```ts US User (NY) highlight={13-20} theme={null}
  {
    kind: "complete",
    connection: {
      status: "active",
      customer: {
        id: "Y3VzX2FiYzEyMw=="
      },
      credentials: {
        accessToken: "c2F0XzAwMQ==",
        clientToken: "c2N0XzAwMQ=="
      },
      capabilities: {
        ramps: {
          requirements: {
            paymentDisclosures: {
              country: "USA",
              administrativeArea: "NY"
            }
          }
        }
      }
    },
    payload: {
      frame: {
        dispose: [Function]
      }
    }
  }
  ```

  ```ts EEA User highlight={13-20} theme={null}
  {
    kind: "complete",
    connection: {
      status: "active",
      customer: {
        id: "Y3VzX2FiYzEyMw=="
      },
      credentials: {
        accessToken: "c2F0XzAwMQ==",
        clientToken: "c2N0XzAwMQ=="
      },
      capabilities: {
        ramps: {
          requirements: {
            paymentDisclosures: {
              country: "FRA",
              area: "EEA"
            }
          }
        }
      }
    },
    payload: {
      frame: {
        dispose: [Function]
      }
    }
  }
  ```

  ```ts RoW User highlight={13-19} theme={null}
  {
    kind: "complete",
    connection: {
      status: "active",
      customer: {
        id: "Y3VzX2FiYzEyMw=="
      },
      credentials: {
        accessToken: "c2F0XzAwMQ==",
        clientToken: "c2N0XzAwMQ=="
      },
      capabilities: {
        ramps: {
          requirements: {
            paymentDisclosures: {
              country: "AUS"
            }
          }
        }
      }
    },
    payload: {
      frame: {
        dispose: [Function]
      }
    }
  }
  ```
</CodeGroup>

If `capabilities.ramps.requirements.paymentDisclosures` is present, use it to determine which disclosure, if any, to show before the customer completes a transaction. `country` is the customer's ISO 3166-1 alpha-3 residential country. `administrativeArea` is present when a US state is available. `area` is present when the customer is in a broader regulatory area, such as the EEA.

<Warning>
  [Client
  credentials](/platform/guides/api-and-sdk-credentials#client-credentials)
  should never be persisted and should only be held in memory as this could pose
  a security risk.
</Warning>

## Connection statuses

### Active

An `active` status means the connection is valid and can be used. Active connections typically remain live for 180 days without revalidation. If the connection expires, refresh it via the connect flow.

### Unavailable

An `unavailable` status means the connection cannot be used at the current time. This typically occurs when a KYC-verified customer is using a device or application from a restricted location.

### Pending

A `pending` status typically occurs for customers whose KYC decisions are delayed. Often these cases are resolved out of band and the customer can connect on a subsequent visit to your app.

### Failed

A `failed` status is a terminal state. This usually happens if the customer fails KYC or cannot be onboarded to MoonPay. It can also happen if the customer rejects the connection. In these cases, direct the customer to an alternate flow in your app.

### Connection required

The `connectionRequired` status is returned from the [check frame](#check-connection) as a signal to guide the customer through the full [connect flow](#connect-flow). This status is returned for new customers who have not connected to your app, or returning customers whose connections have expired. The response also includes anonymous `credentials` — keep them only in memory and use the `clientToken` to initialize the connect flow.


# Handle challenges
Source: https://dev.moonpay.com/platform/guides/handling-challenges

Detect and respond to challenges.

This guide shows you how to detect and handle challenges that require customer authentication or verification before a transaction can continue.

## Prerequisites

* A [connected customer](/platform/guides/connect-a-customer).
* A UI surface where you can render frames (WebView on mobile, iframe on web).

## When challenges appear

Challenges are extra steps a customer must complete before MoonPay can continue an
action. You most commonly see challenges when you:

* Request an executable quote and the customer needs to upgrade authentication or limits.
* Execute a transaction and the customer needs to complete additional authentication
  or verification (for example, Strong Customer Authentication / 3D Secure or
  identity verification).

## Where challenges show up

Challenges are returned as part of API or SDK results. For example, an
executable quote may include a `challenge` field:

```json Example challenge payload theme={null}
{
  "id": "cV8wMDE=",
  "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresAt": "2029-07-21T17:32:28Z",
  "challenge": {
    "kind": "frame",
    "id": "ch_123e4567-e89b-12d3-a456-426614174000"
  }
}
```

## How to handle a challenge

1. **Detect the challenge**: If a result includes a `challenge`, treat the
   current action as blocked until the challenge completes.
2. **Render the challenge UI**:
   * If the challenge is a **frame challenge** (`kind: "frame"`), render a
     dedicated frame (WebView on mobile, iframe on web) and handle events the
     same way you do for other frames.
   * If the challenge is a **first-party challenge**, the SDK/API response
     includes instructions for how to proceed.
3. **Retry the original action**: Once the challenge completes successfully,
   request a new executable quote (if needed) and continue the flow.

## Implementation tips

* **Use a full-screen surface on mobile**: Challenge flows often involve
  authentication or verification, so treat them like a separate screen or full
  sheet.
* **Validate `postMessage` events**: If you integrate frames manually, validate
  origin and message shape. The [frames protocol](/platform/frames/overview) documents
  the shared envelope format.
* **Handle cancellation and timeouts**: If the customer closes the challenge or it
  fails, show a clear next step (retry, choose a different payment method, or
  exit the flow).


# Android
Source: https://dev.moonpay.com/platform/guides/manual-integration/android

Manual frame integration for Android using WebView and Kotlin.

Use `WebView` to embed frames in native Android applications. The WebView communicates with frames via JavaScript interfaces and `evaluateJavascript`.

<Callout icon="book">
  Read the [manual integration
  overview](/platform/guides/manual-integration/overview) for core concepts
  before you continue.
</Callout>

## Setup

### Dependencies

The examples below use [Tink](https://github.com/google/tink) for cryptographic operations, but you can use any library that supports X25519 and AES-GCM.

```kotlin theme={null}
// build.gradle.kts (app level)
dependencies {
    implementation("com.google.crypto.tink:tink-android:1.12.0")
}
```

### Key generation

```kotlin theme={null}
import com.google.crypto.tink.subtle.X25519

data class MoonPayKeyPair(
    val privateKey: ByteArray,
    val publicKeyHex: String
)

object MoonPayCrypto {
    fun generateKeyPair(): MoonPayKeyPair {
        val privateKey = X25519.generatePrivateKey()
        val publicKey = X25519.publicFromPrivate(privateKey)
        val publicKeyHex = publicKey.joinToString("") { "%02x".format(it) }

        return MoonPayKeyPair(privateKey, publicKeyHex)
    }
}
```

### Decryption utility

```kotlin theme={null}
import android.util.Base64
import com.google.crypto.tink.subtle.Hkdf
import com.google.crypto.tink.subtle.X25519
import org.json.JSONObject
import javax.crypto.Cipher
import javax.crypto.spec.GCMParameterSpec
import javax.crypto.spec.SecretKeySpec

object MoonPayDecryptor {
    fun decrypt(encryptedValue: String, privateKey: ByteArray): String {
        // The frame returns the encrypted payload as a base64-encoded
        // JSON string. Decode the base64 first, then parse the JSON.
        val decodedJson = String(Base64.decode(encryptedValue, Base64.DEFAULT), Charsets.UTF_8)
        val encrypted = JSONObject(decodedJson)

        val iv = encrypted.getString("iv").hexToByteArray()
        val ephemeralPublicKey = encrypted.getString("ephemeralPublicKey").hexToByteArray()
        val ciphertext = encrypted.getString("ciphertext").hexToByteArray()

        // Derive shared secret using X25519
        val sharedSecret = X25519.computeSharedSecret(privateKey, ephemeralPublicKey)

        // Derive AES key using HKDF
        val aesKey = Hkdf.computeHkdf(
            "HMACSHA256",
            sharedSecret,
            ByteArray(0),
            ByteArray(0),
            32
        )

        // Decrypt using AES-GCM
        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
        val keySpec = SecretKeySpec(aesKey, "AES")
        val gcmSpec = GCMParameterSpec(128, iv)

        cipher.init(Cipher.DECRYPT_MODE, keySpec, gcmSpec)
        val decrypted = cipher.doFinal(ciphertext)

        return String(decrypted, Charsets.UTF_8)
    }

    private fun String.hexToByteArray(): ByteArray {
        return chunked(2).map { it.toInt(16).toByte() }.toByteArray()
    }
}
```

### Base frame fragment

Create a reusable base fragment for frame communication:

```kotlin theme={null}
import android.annotation.SuppressLint
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import android.view.LayoutInflater
import android.view.View
import android.view.ViewGroup
import android.webkit.JavascriptInterface
import android.webkit.WebView
import android.webkit.WebViewClient
import androidx.fragment.app.Fragment
import org.json.JSONObject
import java.util.UUID

abstract class MoonPayFrameFragment : Fragment() {
    protected lateinit var webView: WebView
    protected val channelId: String = UUID.randomUUID().toString()

    private val handler = Handler(Looper.getMainLooper())

    companion object {
        const val FRAME_ORIGIN = "https://blocks.moonpay.com"
    }

    @SuppressLint("SetJavaScriptEnabled")
    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        webView = WebView(requireContext()).apply {
            settings.javaScriptEnabled = true
            settings.domStorageEnabled = true

            addJavascriptInterface(MoonPayBridge(), "MoonPayBridge")
            // Required for the test-mode Apple Pay flow — see "Handle
            // JavaScript dialogs" below.
            webChromeClient = MoonPayChromeClient(this@MoonPayFrameFragment)
        }

        return webView
    }

    protected fun loadFrame(path: String, params: Map<String, String>) {
        val queryString = params.entries.joinToString("&") { "${it.key}=${it.value}" }
        val url = "$FRAME_ORIGIN$path?$queryString"

        webView.loadUrl(url)
    }

    protected fun sendMessage(kind: String, payload: JSONObject? = null) {
        val message = JSONObject().apply {
            put("version", 2)
            put("meta", JSONObject().put("channelId", channelId))
            put("kind", kind)
            payload?.let { put("payload", it) }
        }

        // Re-encode the JSON as a string literal. The frame's bridge
        // listens for `MessageEvent`s whose `data` is a string and
        // ignores anything else, so we must post a string — not an
        // object literal.
        val stringLiteral = JSONObject.quote(message.toString())

        val script = "window.postMessage($stringLiteral, '*');"
        webView.evaluateJavascript(script, null)
    }

    private fun handleMessage(data: JSONObject) {
        val meta = data.optJSONObject("meta") ?: return
        if (meta.optString("channelId") != channelId) return

        val kind = data.optString("kind")

        if (kind == "handshake") {
            sendMessage("ack")
            onFrameHandshakeComplete()
        }

        onFrameMessage(kind, data.optJSONObject("payload"))
    }

    // Abstract methods for subclasses
    protected abstract fun onFrameMessage(kind: String, payload: JSONObject?)
    protected abstract fun onFrameHandshakeComplete()

    override fun onDestroyView() {
        super.onDestroyView()
        webView.destroy()
    }

    inner class MoonPayBridge {
        @JavascriptInterface
        fun postMessage(data: String) {
            handler.post {
                try {
                    val json = JSONObject(data)
                    handleMessage(json)
                } catch (e: Exception) {
                    // Ignore malformed messages
                }
            }
        }
    }
}
```

### Handle JavaScript dialogs

In [test mode](/overview/test-mode#apple-pay), the Apple Pay frame renders a mock button and uses `window.confirm` to simulate the Apple Pay payment sheet. Android's `WebView` returns `false` for `window.confirm`, `alert`, and `prompt` unless you attach a `WebChromeClient` that handles them — so without this, every test transaction silently comes back with `status: "failed"`.

Surface the simulated payment sheet with an `AlertDialog`:

```kotlin theme={null}
import android.app.AlertDialog
import android.webkit.JsResult
import android.webkit.WebChromeClient
import android.webkit.WebView
import androidx.fragment.app.Fragment

class MoonPayChromeClient(private val fragment: Fragment) : WebChromeClient() {
    override fun onJsConfirm(
        view: WebView?,
        url: String?,
        message: String?,
        result: JsResult
    ): Boolean {
        val context = fragment.context ?: return false
        AlertDialog.Builder(context)
            .setTitle("Test Mode")
            .setMessage(message?.takeIf { it.isNotEmpty() } ?: "Simulate Apple Pay?")
            .setPositiveButton("OK") { _, _ -> result.confirm() }
            .setNegativeButton("Cancel") { _, _ -> result.cancel() }
            .setOnCancelListener { result.cancel() }
            .show()
        return true
    }
}
```

`OK` simulates a successful test transaction (the frame emits `complete` with a non-failed status); `Cancel` simulates a failed transaction (the frame emits `complete` with `status: "failed"`).

<Callout icon="info">
  Attach the `WebChromeClient` even if you only plan to ship live mode. The
  default `WebView` behaviour applies to any `window.confirm`, `alert`, or
  `prompt` the frame might surface, and makes test-mode debugging impossible
  without it.
</Callout>

***

## Check frame

The check frame verifies whether a customer already has an active connection. It's headless — no UI is rendered. Use it to skip the connect flow for returning customers. See [check frame reference](/platform/frames/check) for event details.

### Check fragment

```kotlin theme={null}
import org.json.JSONObject

interface CheckFrameListener {
    fun onCheckActive(accessToken: String, clientToken: String, expiresAt: String)
    fun onCheckConnectionRequired(accessToken: String, clientToken: String)
    fun onCheckFailed(status: String, reason: String?)
    fun onCheckError(code: String, message: String)
}

class MoonPayCheckFragment : MoonPayFrameFragment() {
    private lateinit var keyPair: MoonPayKeyPair
    private var sessionToken: String? = null
    var listener: CheckFrameListener? = null

    companion object {
        private const val ARG_SESSION_TOKEN = "sessionToken"

        fun newInstance(sessionToken: String): MoonPayCheckFragment {
            return MoonPayCheckFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_SESSION_TOKEN, sessionToken)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        sessionToken = arguments?.getString(ARG_SESSION_TOKEN)
        keyPair = MoonPayCrypto.generateKeyPair()
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/check-connection", mapOf(
            "sessionToken" to sessionToken!!,
            "publicKey" to keyPair.publicKeyHex,
            "channelId" to channelId
        ))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> handleComplete(payload)
            "error" -> {
                listener?.onCheckError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete, checking connection status
    }

    private fun handleComplete(payload: JSONObject?) {
        val status = payload?.optString("status") ?: return

        when (status) {
            "active" -> {
                val credentials = payload.optString("credentials")
                val expiresAt = payload.optString("expiresAt")
                // Check payload.capabilities.ramps.requirements.paymentDisclosures
                // to determine if payment disclosures are required before transacting

                try {
                    val decryptedPayload = MoonPayDecryptor.decrypt(credentials, keyPair.privateKey)
                    val credentials = JSONObject(decryptedPayload)
                    val accessToken = credentials.getString("accessToken")
                    val clientToken = credentials.getString("clientToken")
                    listener?.onCheckActive(accessToken, clientToken, expiresAt)
                } catch (e: Exception) {
                    listener?.onCheckError("decryption", "Failed to decrypt credentials")
                }
            }
            "connectionRequired" -> {
                val encryptedCredentials = payload.optString("credentials")

                try {
                    val decryptedPayload = MoonPayDecryptor.decrypt(encryptedCredentials, keyPair.privateKey)
                    val anonymousCredentials = JSONObject(decryptedPayload)
                    val accessToken = anonymousCredentials.getString("accessToken")
                    val clientToken = anonymousCredentials.getString("clientToken")
                    listener?.onCheckConnectionRequired(accessToken, clientToken)
                } catch (e: Exception) {
                    listener?.onCheckError("decryption", "Failed to decrypt anonymous credentials")
                }
            }
            "pending", "unavailable", "failed" -> {
                listener?.onCheckFailed(status, payload.optString("reason"))
            }
        }
    }
}
```

### Usage

```kotlin theme={null}
class SplashActivity : AppCompatActivity(), CheckFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        val fragment = MoonPayCheckFragment.newInstance("your-session-token")
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    override fun onCheckActive(accessToken: String, clientToken: String, expiresAt: String) {
        // Customer is already connected — skip to payment
        CredentialsManager.accessToken = accessToken
        CredentialsManager.clientToken = clientToken

        startActivity(Intent(this, PaymentActivity::class.java))
        finish()
    }

    override fun onCheckConnectionRequired(accessToken: String, clientToken: String) {
        // Store both tokens in memory, then show connect frame with the anonymous clientToken
        CredentialsManager.accessToken = accessToken
        CredentialsManager.clientToken = clientToken

        val intent = Intent(this, ConnectActivity::class.java).apply {
            putExtra("clientToken", clientToken)
        }
        startActivity(intent)
        finish()
    }

    override fun onCheckFailed(status: String, reason: String?) {
        // Handle terminal statuses (pending, unavailable, failed)
    }

    override fun onCheckError(code: String, message: String) {
        // Handle check errors
    }
}
```

***

## Connect frame

The connect frame establishes a customer connection to your application. See [connect frame reference](/platform/frames/connect) for event details.

### Connect fragment

```kotlin theme={null}
import org.json.JSONObject

interface ConnectFrameListener {
    fun onConnectComplete(accessToken: String, clientToken: String, expiresAt: String)
    fun onConnectFailed(status: String, reason: String?)
    fun onConnectError(code: String, message: String)
}

class MoonPayConnectFragment : MoonPayFrameFragment() {
    private lateinit var keyPair: MoonPayKeyPair
    private var clientToken: String? = null
    var listener: ConnectFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"

        fun newInstance(clientToken: String): MoonPayConnectFragment {
            return MoonPayConnectFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
        keyPair = MoonPayCrypto.generateKeyPair()
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/connect", mapOf(
            "clientToken" to clientToken!!,
            "publicKey" to keyPair.publicKeyHex,
            "channelId" to channelId
        ))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> handleComplete(payload)
            "error" -> {
                listener?.onConnectError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete, waiting for customer interaction
    }

    private fun handleComplete(payload: JSONObject?) {
        val status = payload?.optString("status") ?: return

        when (status) {
            "active" -> {
                val credentials = payload.optString("credentials")
                val expiresAt = payload.optString("expiresAt")
                // Check payload.capabilities.ramps.requirements.paymentDisclosures
                // to determine if payment disclosures are required before transacting

                try {
                    val decryptedPayload = MoonPayDecryptor.decrypt(credentials, keyPair.privateKey)
                    val credentials = JSONObject(decryptedPayload)
                    val accessToken = credentials.getString("accessToken")
                    val clientToken = credentials.getString("clientToken")
                    listener?.onConnectComplete(accessToken, clientToken, expiresAt)
                } catch (e: Exception) {
                    listener?.onConnectError("decryption", "Failed to decrypt credentials")
                }
            }
            "pending", "unavailable", "failed" -> {
                listener?.onConnectFailed(status, payload.optString("reason"))
            }
        }
    }
}
```

### Usage with Activity

```kotlin theme={null}
class ConnectActivity : AppCompatActivity(), ConnectFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        // The clientToken is the anonymous token passed from the check frame's
        // `connectionRequired` response.
        val clientToken = intent.getStringExtra("clientToken")!!
        val fragment = MoonPayConnectFragment.newInstance(clientToken)
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    // ConnectFrameListener implementation

    override fun onConnectComplete(accessToken: String, clientToken: String, expiresAt: String) {
        // Store credentials in memory
        CredentialsManager.accessToken = accessToken
        CredentialsManager.clientToken = clientToken

        Toast.makeText(this, "Connected!", Toast.LENGTH_SHORT).show()

        // Navigate to next screen
        startActivity(Intent(this, PaymentActivity::class.java))
        finish()
    }

    override fun onConnectFailed(status: String, reason: String?) {
        AlertDialog.Builder(this)
            .setTitle("Connection $status")
            .setMessage(reason ?: "Please try again later.")
            .setPositiveButton("OK") { _, _ -> finish() }
            .show()
    }

    override fun onConnectError(code: String, message: String) {
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK") { _, _ -> finish() }
            .show()
    }
}
```

***

## Add Card frame

The add card frame lets a customer save a new card to their account. See [add card frame reference](/platform/frames/add-card) for event details.

### What you'll need

Before you initialize the add card frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)

### Add Card fragment

```kotlin theme={null}
import org.json.JSONObject

interface AddCardFrameListener {
    fun onAddCardComplete(cardId: String, brand: String, last4: String)
    fun onAddCardError(code: String, message: String)
}

class MoonPayAddCardFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    var listener: AddCardFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"

        fun newInstance(clientToken: String): MoonPayAddCardFragment {
            return MoonPayAddCardFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/add-card", mapOf(
            "clientToken" to clientToken!!,
            "channelId" to channelId
        ))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> {
                val card = payload?.optJSONObject("card")
                listener?.onAddCardComplete(
                    card?.optString("id") ?: "",
                    card?.optString("brand") ?: "",
                    card?.optString("last4") ?: ""
                )
            }
            "error" -> {
                listener?.onAddCardError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete
    }
}
```

### Usage with Activity

```kotlin theme={null}
class SaveCardActivity : AppCompatActivity(), AddCardFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        val fragment = MoonPayAddCardFragment.newInstance(CredentialsManager.clientToken!!)
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    override fun onAddCardComplete(cardId: String, brand: String, last4: String) {
        Toast.makeText(this, "Card saved: $brand •••• $last4", Toast.LENGTH_SHORT).show()
        // Proceed to payment with the saved card
        finish()
    }

    override fun onAddCardError(code: String, message: String) {
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK") { _, _ -> finish() }
            .show()
    }
}
```

***

## Buy frame

The buy frame processes a card payment for a quote. It is headless — rendered at zero size — while the customer completes payment. If 3-D Secure is required, the frame emits a `challenge` event with a URL you open in a separate challenge frame. See [buy frame reference](/platform/frames/buy) for event details.

### What you'll need

Before you initialize the buy frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Buy fragment

```kotlin theme={null}
import org.json.JSONObject

interface BuyFrameListener {
    fun onBuyComplete(transactionId: String, status: String)
    fun onBuyChallenge(url: String)
    fun onBuyError(code: String, message: String)
}

class MoonPayBuyFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    private var quoteSignature: String? = null
    var listener: BuyFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"
        private const val ARG_QUOTE_SIGNATURE = "quoteSignature"

        fun newInstance(clientToken: String, quoteSignature: String): MoonPayBuyFragment {
            return MoonPayBuyFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                    putString(ARG_QUOTE_SIGNATURE, quoteSignature)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
        quoteSignature = arguments?.getString(ARG_QUOTE_SIGNATURE)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/buy", mapOf(
            "clientToken" to clientToken!!,
            "channelId" to channelId,
            "signature" to quoteSignature!!
        ))
    }

    fun updateQuote(signature: String) {
        quoteSignature = signature
        sendMessage("setQuote", JSONObject().put("quote", JSONObject().put("signature", signature)))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> {
                val transaction = payload?.optJSONObject("transaction")
                listener?.onBuyComplete(
                    transaction?.optString("id") ?: "",
                    transaction?.optString("status") ?: ""
                )
            }
            "challenge" -> {
                val url = payload?.optString("url") ?: ""
                listener?.onBuyChallenge(url)
            }
            "error" -> {
                listener?.onBuyError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete
    }
}
```

### Challenge handling

When the buy fragment receives a challenge URL, add a `MoonPayChallengeFragment` to present the 3-D Secure flow. On completion, cancellation, or error, remove both the challenge and buy fragments:

```kotlin theme={null}
import org.json.JSONObject

interface ChallengeFrameListener {
    fun onChallengeComplete(transactionId: String, status: String)
    fun onChallengeCancelled()
    fun onChallengeError(code: String, message: String)
}

class MoonPayChallengeFragment : MoonPayFrameFragment() {
    private var challengeUrl: String? = null
    var listener: ChallengeFrameListener? = null

    companion object {
        private const val ARG_CHALLENGE_URL = "challengeUrl"

        fun newInstance(challengeUrl: String): MoonPayChallengeFragment {
            return MoonPayChallengeFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CHALLENGE_URL, challengeUrl)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        challengeUrl = arguments?.getString(ARG_CHALLENGE_URL)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        val urlWithChannel = Uri.parse(challengeUrl)
            .buildUpon()
            .appendQueryParameter("channelId", channelId)
            .toString()
        webView.loadUrl(urlWithChannel)
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "complete" -> {
                val transaction = payload?.optJSONObject("transaction")
                listener?.onChallengeComplete(
                    transaction?.optString("id") ?: "",
                    transaction?.optString("status") ?: ""
                )
            }
            "cancelled" -> {
                listener?.onChallengeCancelled()
            }
            "error" -> {
                listener?.onChallengeError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete
    }
}
```

### Usage with Activity

```kotlin theme={null}
class BuyPaymentActivity : AppCompatActivity(), BuyFrameListener, ChallengeFrameListener {
    private var buyFragment: MoonPayBuyFragment? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        val fragment = MoonPayBuyFragment.newInstance(
            clientToken = CredentialsManager.clientToken!!,
            quoteSignature = currentQuote.signature
        )
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .add(R.id.frame_container, fragment, "buy")
            .commit()

        buyFragment = fragment
    }

    // BuyFrameListener implementation

    override fun onBuyComplete(transactionId: String, status: String) {
        Toast.makeText(this, "Transaction $transactionId: $status", Toast.LENGTH_SHORT).show()
        // Navigate to transaction status screen or poll for updates
    }

    override fun onBuyChallenge(url: String) {
        val challengeFragment = MoonPayChallengeFragment.newInstance(url)
        challengeFragment.listener = this

        supportFragmentManager.beginTransaction()
            .add(R.id.frame_container, challengeFragment, "challenge")
            .commit()
    }

    override fun onBuyError(code: String, message: String) {
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK", null)
            .show()
    }

    // ChallengeFrameListener implementation

    override fun onChallengeComplete(transactionId: String, status: String) {
        removeFragments()
        Toast.makeText(this, "Transaction $transactionId: $status", Toast.LENGTH_SHORT).show()
        // Navigate to transaction status screen or poll for updates
    }

    override fun onChallengeCancelled() {
        removeFragments()
    }

    override fun onChallengeError(code: String, message: String) {
        removeFragments()
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK", null)
            .show()
    }

    private fun removeFragments() {
        val transaction = supportFragmentManager.beginTransaction()
        supportFragmentManager.findFragmentByTag("challenge")?.let { transaction.remove(it) }
        supportFragmentManager.findFragmentByTag("buy")?.let { transaction.remove(it) }
        transaction.commit()
    }
}
```

***

## Google Pay frame

The Google Pay frame renders the Google Pay button and handles the payment flow. See [Google Pay frame reference](/platform/frames/google-pay) for event details.

### Enable the Payment Request API

Google Pay relies on the [Payment Request API](https://developer.mozilla.org/en-US/docs/Web/API/Payment_Request_API), which is **disabled by default** in Android WebView. Enable it before loading the frame.

<Callout icon="circle-info">
  Requires Google Play services **25.18.30+** and Android WebView for Chrome
  **137+**. The `isReadyToPay` API returns `false` if these requirements are not
  met. See [Using Android
  WebView](https://developers.google.com/pay/api/android/guides/recipes/using-android-webview)
  for full details.
</Callout>

Add the AndroidX WebKit dependency:

```kotlin theme={null}
// build.gradle.kts (app level)
dependencies {
    implementation("androidx.webkit:webkit:1.14.0")
}
```

Declare the required intent filters in `AndroidManifest.xml`:

```xml theme={null}
<queries>
  <intent>
    <action android:name="org.chromium.intent.action.PAY" />
  </intent>
  <intent>
    <action android:name="org.chromium.intent.action.IS_READY_TO_PAY" />
  </intent>
  <intent>
    <action android:name="org.chromium.intent.action.UPDATE_PAYMENT_DETAILS" />
  </intent>
</queries>
```

Enable the Payment Request API on the WebView in your base fragment's `onCreateView`:

```kotlin theme={null}
import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature

// Inside onCreateView, after settings.javaScriptEnabled = true
if (WebViewFeature.isFeatureSupported(WebViewFeature.PAYMENT_REQUEST)) {
    WebSettingsCompat.setPaymentRequestEnabled(webView.settings, true)
}
```

### What you'll need

Before you initialize the Google Pay frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Google Pay fragment

```kotlin theme={null}
import org.json.JSONObject

interface GooglePayFrameListener {
    fun onGooglePayReady()
    fun onGooglePayComplete(transactionId: String, status: String)
    fun onGooglePayFailed(reason: String)
    fun onGooglePayError(code: String, message: String)
    fun onGooglePayChallenge(url: String)
}

class MoonPayGooglePayFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    private var quoteSignature: String? = null
    var listener: GooglePayFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"
        private const val ARG_QUOTE_SIGNATURE = "quoteSignature"

        fun newInstance(clientToken: String, quoteSignature: String): MoonPayGooglePayFragment {
            return MoonPayGooglePayFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                    putString(ARG_QUOTE_SIGNATURE, quoteSignature)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
        quoteSignature = arguments?.getString(ARG_QUOTE_SIGNATURE)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/google-pay", mapOf(
            "clientToken" to clientToken!!,
            "channelId" to channelId,
            "signature" to quoteSignature!!
        ))
    }

    fun updateQuote(signature: String) {
        quoteSignature = signature
        sendMessage("setQuote", JSONObject().put("quote", JSONObject().put("signature", signature)))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "ready" -> {
                listener?.onGooglePayReady()
            }
            "complete" -> {
                val transaction = payload?.optJSONObject("transaction")
                val status = transaction?.optString("status") ?: ""

                if (status == "failed") {
                    listener?.onGooglePayFailed(
                        transaction?.optString("failureReason") ?: "Transaction failed"
                    )
                } else {
                    listener?.onGooglePayComplete(
                        transaction?.optString("id") ?: "",
                        status
                    )
                }
            }
            "challenge" -> {
                val url = payload?.optString("url") ?: ""
                listener?.onGooglePayChallenge(url)
            }
            "error" -> {
                listener?.onGooglePayError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete
    }
}
```

### Usage with Activity

```kotlin theme={null}
class GooglePayActivity : AppCompatActivity(), GooglePayFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        val fragment = MoonPayGooglePayFragment.newInstance(
            CredentialsManager.clientToken!!,
            currentQuote.signature
        )
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    override fun onGooglePayReady() {
        // Google Pay button is visible and ready
    }

    override fun onGooglePayComplete(transactionId: String, status: String) {
        Toast.makeText(this, "Transaction $transactionId: $status", Toast.LENGTH_SHORT).show()
        // Navigate to transaction status screen
    }

    override fun onGooglePayFailed(reason: String) {
        AlertDialog.Builder(this)
            .setTitle("Payment Failed")
            .setMessage(reason)
            .setPositiveButton("OK", null)
            .show()
    }

    override fun onGooglePayError(code: String, message: String) {
        if (code == "quoteExpired") {
            // Fetch new quote and update the fragment
            return
        }
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK") { _, _ -> finish() }
            .show()
    }

    override fun onGooglePayChallenge(url: String) {
        // Open the challenge frame — see "Challenge handling" section
    }
}
```

***

## Widget frame

Apple Pay is not available on Android. Use the [widget frame](/platform/frames/widget) instead to render the full MoonPay buy experience — including payment-method selection (credit/debit card, Google Pay, bank transfers, and more) and transaction confirmation. See [pay with widget](/platform/guides/pay-with-widget) for a full walkthrough.

### What you'll need

Before you initialize the widget frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Widget fragment

```kotlin theme={null}
import org.json.JSONObject

interface WidgetFrameListener {
    fun onWidgetReady()
    fun onWidgetTransactionCreated(transactionId: String, status: String)
    fun onWidgetComplete(transactionId: String, status: String)
    fun onWidgetFailed(failureReason: String)
    fun onWidgetError(code: String, message: String)
}

class MoonPayWidgetFragment : MoonPayFrameFragment() {
    private var clientToken: String? = null
    private var quoteSignature: String? = null
    var listener: WidgetFrameListener? = null

    companion object {
        private const val ARG_CLIENT_TOKEN = "clientToken"
        private const val ARG_QUOTE_SIGNATURE = "quoteSignature"

        fun newInstance(clientToken: String, quoteSignature: String): MoonPayWidgetFragment {
            return MoonPayWidgetFragment().apply {
                arguments = Bundle().apply {
                    putString(ARG_CLIENT_TOKEN, clientToken)
                    putString(ARG_QUOTE_SIGNATURE, quoteSignature)
                }
            }
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        clientToken = arguments?.getString(ARG_CLIENT_TOKEN)
        quoteSignature = arguments?.getString(ARG_QUOTE_SIGNATURE)
    }

    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)

        loadFrame("/platform/v1/widget", mapOf(
            "flow" to "buy",
            "clientToken" to clientToken!!,
            "quoteSignature" to quoteSignature!!,
            "channelId" to channelId
        ))
    }

    override fun onFrameMessage(kind: String, payload: JSONObject?) {
        when (kind) {
            "ready" -> {
                listener?.onWidgetReady()
            }
            "transactionCreated" -> {
                val transaction = payload?.optJSONObject("transaction")
                listener?.onWidgetTransactionCreated(
                    transaction?.optString("id") ?: "",
                    transaction?.optString("status") ?: ""
                )
            }
            "complete" -> handleComplete(payload)
            "error" -> {
                listener?.onWidgetError(
                    payload?.optString("code") ?: "unknown",
                    payload?.optString("message") ?: "Unknown error"
                )
            }
        }
    }

    override fun onFrameHandshakeComplete() {
        // Handshake complete, widget loading
    }

    private fun handleComplete(payload: JSONObject?) {
        val transaction = payload?.optJSONObject("transaction") ?: return
        val status = transaction.optString("status")

        if (status == "failed") {
            val reason = transaction.optString("failureReason", "Transaction failed")
            listener?.onWidgetFailed(reason)
        } else {
            val transactionId = transaction.optString("id")
            listener?.onWidgetComplete(transactionId, status)
        }
    }
}
```

### Usage with Activity

```kotlin theme={null}
class PaymentActivity : AppCompatActivity(), WidgetFrameListener {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_frame_container)

        val fragment = MoonPayWidgetFragment.newInstance(
            clientToken = CredentialsManager.clientToken!!,
            quoteSignature = currentQuote.signature
        )
        fragment.listener = this

        supportFragmentManager.beginTransaction()
            .replace(R.id.frame_container, fragment)
            .commit()
    }

    // WidgetFrameListener implementation

    override fun onWidgetReady() {
        // Widget is loaded and visible
    }

    override fun onWidgetTransactionCreated(transactionId: String, status: String) {
        // Transaction initiated — customer may need to complete 3-D Secure
        Toast.makeText(this, "Transaction created: $transactionId", Toast.LENGTH_SHORT).show()
    }

    override fun onWidgetComplete(transactionId: String, status: String) {
        Toast.makeText(this, "Transaction $transactionId: $status", Toast.LENGTH_SHORT).show()
        // Navigate to transaction status screen or poll for updates
    }

    override fun onWidgetFailed(failureReason: String) {
        AlertDialog.Builder(this)
            .setTitle("Payment Failed")
            .setMessage(failureReason)
            .setPositiveButton("OK", null)
            .show()
    }

    override fun onWidgetError(code: String, message: String) {
        AlertDialog.Builder(this)
            .setTitle("Error")
            .setMessage(message)
            .setPositiveButton("OK", null)
            .show()
    }
}
```


# Flutter
Source: https://dev.moonpay.com/platform/guides/manual-integration/flutter

Manual frame integration for Flutter using webview_flutter.

Use `webview_flutter` to embed frames in Flutter applications. The WebView communicates with your Dart code through JavaScript channels.

<Callout icon="book">
  Read the [manual integration
  overview](/platform/guides/manual-integration/overview) for core concepts
  before you continue.
</Callout>

## Setup

### Dependencies

The examples below use [cryptography](https://pub.dev/packages/cryptography) for X25519 key exchange, but you can use any library that supports X25519 and AES-GCM. Add the required packages to your `pubspec.yaml`:

```yaml theme={null}
dependencies:
  webview_flutter: ^4.13.0
  cryptography: ^2.7.0
  convert: ^3.1.1
```

For platform-specific setup, add the implementation packages:

```yaml theme={null}
dependencies:
  webview_flutter_android: ^4.3.0 # Android
  webview_flutter_wkwebview: ^3.18.0 # iOS/macOS
```

Run `flutter pub get` to install the packages.

### Platform configuration

<Tabs>
  <Tab title="iOS">
    Add the following to your `ios/Runner/Info.plist`:

    ```xml theme={null}
    <key>io.flutter.embedded_views_preview</key>
    <true/>
    ```
  </Tab>

  <Tab title="Android">
    Set the minimum SDK version in `android/app/build.gradle`:

    ```groovy theme={null}
    android {
        defaultConfig {
            minSdkVersion 21
        }
    }
    ```
  </Tab>
</Tabs>

### Key generation

Create a utility class for X25519 key generation and decryption:

```dart theme={null}
import 'dart:convert';
import 'dart:typed_data';
import 'package:cryptography/cryptography.dart';
import 'package:convert/convert.dart';

class MoonPayCrypto {
  final SimpleKeyPair _keyPair;
  final String publicKeyHex;

  MoonPayCrypto._(this._keyPair, this.publicKeyHex);

  /// Generate a new X25519 keypair for frame communication
  static Future<MoonPayCrypto> generate() async {
    final algorithm = X25519();
    final keyPair = await algorithm.newKeyPair();
    final publicKey = await keyPair.extractPublicKey();
    final publicKeyHex = hex.encode(publicKey.bytes);

    return MoonPayCrypto._(keyPair, publicKeyHex);
  }

  /// Decrypt an encrypted payload from the frame
  Future<String> decryptPayload(String encryptedValue) async {
    // The frame returns the encrypted payload as a base64-encoded JSON
    // string. Decode the base64 first, then parse the JSON.
    final decodedJson = utf8.decode(base64Decode(encryptedValue));
    final encrypted = jsonDecode(decodedJson) as Map<String, dynamic>;

    final ephemeralPublicKeyBytes = hex.decode(encrypted['ephemeralPublicKey'] as String);
    final iv = hex.decode(encrypted['iv'] as String);
    final ciphertext = hex.decode(encrypted['ciphertext'] as String);

    // Create shared secret using X25519
    final algorithm = X25519();
    final ephemeralPublicKey = SimplePublicKey(
      Uint8List.fromList(ephemeralPublicKeyBytes),
      type: KeyPairType.x25519,
    );

    final sharedSecret = await algorithm.sharedSecretKey(
      keyPair: _keyPair,
      remotePublicKey: ephemeralPublicKey,
    );

    // Derive AES key using HKDF
    final hkdf = Hkdf(hmac: Hmac.sha256(), outputLength: 32);
    final derivedKey = await hkdf.deriveKey(
      secretKey: sharedSecret,
      info: Uint8List(0),
      nonce: Uint8List(0),
    );

    // Decrypt using AES-GCM
    final aesGcm = AesGcm.with256bits();
    final secretBox = SecretBox(
      ciphertext,
      nonce: iv,
      mac: Mac.empty, // MAC is appended to ciphertext
    );

    final decrypted = await aesGcm.decrypt(
      secretBox,
      secretKey: derivedKey,
    );

    return utf8.decode(decrypted);
  }
}

/// Generate a unique channel ID for frame communication
String generateChannelId() {
  final timestamp = DateTime.now().millisecondsSinceEpoch;
  final random = (DateTime.now().microsecond * 1000).toRadixString(36);
  return 'ch_${timestamp}_$random';
}
```

### Base WebView widget

Create a reusable widget for frame communication:

```dart theme={null}
import 'dart:async';
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

const String frameOrigin = 'https://blocks.moonpay.com';

class FrameMessage {
  final int version;
  final String channelId;
  final String kind;
  final Map<String, dynamic>? payload;

  FrameMessage({
    required this.version,
    required this.channelId,
    required this.kind,
    this.payload,
  });

  factory FrameMessage.fromJson(Map<String, dynamic> json) {
    return FrameMessage(
      version: json['version'] as int,
      channelId: (json['meta'] as Map<String, dynamic>)['channelId'] as String,
      kind: json['kind'] as String,
      payload: json['payload'] as Map<String, dynamic>?,
    );
  }

  Map<String, dynamic> toJson() => {
    'version': version,
    'meta': {'channelId': channelId},
    'kind': kind,
    if (payload != null) 'payload': payload,
  };
}

class MoonPayWebView extends StatefulWidget {
  final String url;
  final String channelId;
  final void Function(FrameMessage) onMessage;
  final VoidCallback onHandshake;
  final double? height;

  const MoonPayWebView({
    super.key,
    required this.url,
    required this.channelId,
    required this.onMessage,
    required this.onHandshake,
    this.height,
  });

  @override
  State<MoonPayWebView> createState() => _MoonPayWebViewState();
}

class _MoonPayWebViewState extends State<MoonPayWebView> {
  late final WebViewController _controller;

  @override
  void initState() {
    super.initState();
    _controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..addJavaScriptChannel(
        'MoonPayBridge',
        onMessageReceived: _handleMessage,
      )
      ..setNavigationDelegate(
        NavigationDelegate(
          onPageFinished: (_) => _injectMessageBridge(),
        ),
      )
      ..loadRequest(Uri.parse(widget.url));
  }

  void _injectMessageBridge() {
    _controller.runJavaScript('''
      (function() {
        window.addEventListener('message', function(e) {
          if (MoonPayBridge && MoonPayBridge.postMessage) {
            MoonPayBridge.postMessage(typeof e.data === 'string' ? e.data : JSON.stringify(e.data));
          }
        });
      })();
    ''');
  }

  void _handleMessage(JavaScriptMessage jsMessage) {
    try {
      final data = jsonDecode(jsMessage.message) as Map<String, dynamic>;
      final meta = data['meta'] as Map<String, dynamic>?;

      if (meta?['channelId'] != widget.channelId) return;

      final message = FrameMessage.fromJson(data);

      if (message.kind == 'handshake') {
        sendMessage('ack');
        widget.onHandshake();
      }

      widget.onMessage(message);
    } catch (_) {
      // Ignore malformed messages
    }
  }

  void sendMessage(String kind, [Map<String, dynamic>? payload]) {
    final message = FrameMessage(
      version: 2,
      channelId: widget.channelId,
      kind: kind,
      payload: payload,
    );

    final jsonString = jsonEncode(message.toJson());
    // Re-encode the JSON as a string literal. The frame's bridge listens
    // for `MessageEvent`s whose `data` is a string and ignores anything
    // else, so we must post a string — not an object literal.
    final stringLiteral = jsonEncode(jsonString);
    _controller.runJavaScript('''
      window.postMessage($stringLiteral, '*');
    ''');
  }

  @override
  Widget build(BuildContext context) {
    return SizedBox(
      height: widget.height ?? double.infinity,
      child: WebViewWidget(controller: _controller),
    );
  }
}
```

### Handle JavaScript dialogs

In [test mode](/overview/test-mode#apple-pay), the Apple Pay frame renders a mock button and uses `window.confirm` to simulate the Apple Pay payment sheet (`OK` = success, `Cancel` = failed).

`webview_flutter` does not surface `window.confirm` (or `alert` / `prompt`) by default — the underlying `WKWebView` on iOS and `WebView` on Android both require explicit dialog handlers. Without one, the call returns `false` with no UI shown, the frame interprets that as the customer cancelling, and every test transaction comes back with `status: "failed"`.

Wire dialog handling via the platform-specific implementations. On iOS use `WebKitWebViewController`'s UI delegate hooks; on Android use `AndroidWebViewController` to attach a `WebChromeClient` whose `onJsConfirm` returns the customer's choice. Surface the prompt with a Flutter `AlertDialog` so it matches the rest of your UI, and call back into the controller with the result.

<Callout icon="info">
  Wire dialog handling even if you only plan to ship live mode. It applies to
  any `window.confirm`, `alert`, or `prompt` the frame might surface, and makes
  test-mode debugging impossible without it.
</Callout>

***

## Check frame

The check frame verifies whether a customer already has an active connection. It's headless — no UI is rendered. Use it to skip the connect flow for returning customers. See [check frame reference](/platform/frames/check) for event details.

### Check widget

```dart theme={null}
import 'dart:async';
import 'dart:convert';
import 'package:flutter/material.dart';

class MoonPayCheckFrame extends StatefulWidget {
  final String sessionToken;
  final void Function(ConnectCredentials) onActive;
  final void Function(ConnectCredentials) onConnectionRequired;
  final void Function(ConnectError) onError;
  final VoidCallback? onPending;
  final VoidCallback? onUnavailable;

  const MoonPayCheckFrame({
    super.key,
    required this.sessionToken,
    required this.onActive,
    required this.onConnectionRequired,
    required this.onError,
    this.onPending,
    this.onUnavailable,
  });

  @override
  State<MoonPayCheckFrame> createState() => _MoonPayCheckFrameState();
}

class _MoonPayCheckFrameState extends State<MoonPayCheckFrame> {
  late final String _channelId;
  late final Future<MoonPayCrypto> _cryptoFuture;

  @override
  void initState() {
    super.initState();
    _channelId = generateChannelId();
    _cryptoFuture = MoonPayCrypto.generate();
  }

  String _buildFrameUrl(String publicKeyHex) {
    final params = {
      'sessionToken': widget.sessionToken,
      'publicKey': publicKeyHex,
      'channelId': _channelId,
    };

    return '$frameOrigin/platform/v1/check-connection?${Uri(queryParameters: params).query}';
  }

  Future<void> _handleMessage(FrameMessage message, MoonPayCrypto crypto) async {
    switch (message.kind) {
      case 'complete':
        final payload = message.payload!;
        final status = payload['status'] as String;

        switch (status) {
          case 'active':
            final decryptedPayload = await crypto.decryptPayload(payload['credentials'] as String);
            final credentials = jsonDecode(decryptedPayload) as Map<String, dynamic>;
            // Check payload['capabilities']['ramps']['requirements']['paymentDisclosures']
            // to determine if payment disclosures are required before transacting
            widget.onActive(ConnectCredentials(
              accessToken: credentials['accessToken'] as String,
              clientToken: credentials['clientToken'] as String,
            ));
            break;
          case 'connectionRequired':
            final decryptedPayload = await crypto.decryptPayload(payload['credentials'] as String);
            final anonymousCredentials = jsonDecode(decryptedPayload) as Map<String, dynamic>;
            widget.onConnectionRequired(ConnectCredentials(
              accessToken: anonymousCredentials['accessToken'] as String,
              clientToken: anonymousCredentials['clientToken'] as String,
            ));
            break;
          case 'pending':
            widget.onPending?.call();
            break;
          case 'unavailable':
            widget.onUnavailable?.call();
            break;
          case 'failed':
            widget.onError(ConnectError(
              code: 'failed',
              message: payload['reason'] as String? ?? 'Check failed',
            ));
            break;
        }
        break;

      case 'error':
        final payload = message.payload!;
        widget.onError(ConnectError(
          code: payload['code'] as String,
          message: payload['message'] as String,
        ));
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<MoonPayCrypto>(
      future: _cryptoFuture,
      builder: (context, snapshot) {
        if (!snapshot.hasData) {
          return const Center(child: CircularProgressIndicator());
        }

        final crypto = snapshot.data!;

        return MoonPayWebView(
          url: _buildFrameUrl(crypto.publicKeyHex),
          channelId: _channelId,
          onMessage: (msg) => _handleMessage(msg, crypto),
          onHandshake: () {},
        );
      },
    );
  }
}
```

### Usage

```dart theme={null}
class SplashScreen extends StatelessWidget {
  const SplashScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: MoonPayCheckFrame(
        sessionToken: 'your-session-token',
        onActive: (credentials) {
          // Customer is already connected — skip to payment
          debugPrint('Already connected! Access token: ${credentials.accessToken}');
          Navigator.of(context).pushReplacementNamed('/payment');
        },
        onConnectionRequired: (credentials) {
          // Store both tokens in memory, then pass the clientToken to the connect frame
          CredentialsStore.instance.set(
            accessToken: credentials.accessToken,
            clientToken: credentials.clientToken,
          );
          Navigator.of(context).pushReplacementNamed(
            '/connect',
            arguments: credentials.clientToken,
          );
        },
        onError: (error) {
          debugPrint('Check failed: ${error.message}');
        },
      ),
    );
  }
}
```

***

## Connect frame

The connect frame establishes a customer connection to your application. See [connect frame reference](/platform/frames/connect) for event details.

### Connect widget

```dart theme={null}
import 'dart:async';
import 'package:flutter/material.dart';

class ConnectCredentials {
  final String accessToken;
  final String clientToken;

  ConnectCredentials({required this.accessToken, required this.clientToken});
}

class ConnectError {
  final String code;
  final String message;

  ConnectError({required this.code, required this.message});
}

class MoonPayConnectFrame extends StatefulWidget {
  final String clientToken;
  final void Function(ConnectCredentials) onComplete;
  final void Function(ConnectError) onError;
  final VoidCallback? onPending;
  final VoidCallback? onUnavailable;

  const MoonPayConnectFrame({
    super.key,
    required this.clientToken,
    required this.onComplete,
    required this.onError,
    this.onPending,
    this.onUnavailable,
  });

  @override
  State<MoonPayConnectFrame> createState() => _MoonPayConnectFrameState();
}

class _MoonPayConnectFrameState extends State<MoonPayConnectFrame> {
  late final String _channelId;
  late final Future<MoonPayCrypto> _cryptoFuture;
  @override
  void initState() {
    super.initState();
    _channelId = generateChannelId();
    _cryptoFuture = MoonPayCrypto.generate();
  }

  String _buildFrameUrl(String publicKeyHex) {
    final params = {
      'clientToken': widget.clientToken,
      'publicKey': publicKeyHex,
      'channelId': _channelId,
    };

    return '$frameOrigin/platform/v1/connect?${Uri(queryParameters: params).query}';
  }

  Future<void> _handleMessage(FrameMessage message, MoonPayCrypto crypto) async {
    switch (message.kind) {
      case 'complete':
        final payload = message.payload!;
        final status = payload['status'] as String;

        switch (status) {
          case 'active':
            final decryptedPayload = await crypto.decryptPayload(payload['credentials'] as String);
            final credentials = jsonDecode(decryptedPayload) as Map<String, dynamic>;
            // Check payload['capabilities']['ramps']['requirements']['paymentDisclosures']
            // to determine if payment disclosures are required before transacting
            widget.onComplete(ConnectCredentials(
              accessToken: credentials['accessToken'] as String,
              clientToken: credentials['clientToken'] as String,
            ));
            break;
          case 'pending':
            widget.onPending?.call();
            break;
          case 'unavailable':
            widget.onUnavailable?.call();
            break;
          case 'failed':
            widget.onError(ConnectError(
              code: 'failed',
              message: payload['reason'] as String? ?? 'Connection failed',
            ));
            break;
        }
        break;

      case 'error':
        final payload = message.payload!;
        widget.onError(ConnectError(
          code: payload['code'] as String,
          message: payload['message'] as String,
        ));
        break;
    }
  }

  void _handleHandshake() {
    // Handshake complete
  }

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<MoonPayCrypto>(
      future: _cryptoFuture,
      builder: (context, snapshot) {
        if (!snapshot.hasData) {
          return const Center(child: CircularProgressIndicator());
        }

        final crypto = snapshot.data!;

        return MoonPayWebView(
          url: _buildFrameUrl(crypto.publicKeyHex),
          channelId: _channelId,
          onMessage: (msg) => _handleMessage(msg, crypto),
          onHandshake: _handleHandshake,
        );
      },
    );
  }
}
```

### Usage

```dart theme={null}
class ConnectScreen extends StatelessWidget {
  const ConnectScreen({super.key});

  @override
  Widget build(BuildContext context) {
    // The clientToken is the anonymous token passed from the check frame's
    // `connectionRequired` response.
    final clientToken = ModalRoute.of(context)!.settings.arguments as String;

    return Scaffold(
      appBar: AppBar(title: const Text('Connect')),
      body: MoonPayConnectFrame(
        clientToken: clientToken,
        onComplete: (credentials) {
          // Replace the anonymous credentials with the authenticated ones and
          // store them in memory (e.g., Provider or Riverpod).
          debugPrint('Connected! Access token: ${credentials.accessToken}');
          Navigator.of(context).pushReplacementNamed('/home');
        },
        onError: (error) {
          debugPrint('Connection failed: ${error.message}');
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Error: ${error.message}')),
          );
        },
        onPending: () => debugPrint('Connection pending'),
        onUnavailable: () => debugPrint('Connection unavailable'),
      ),
    );
  }
}
```

***

## Apple Pay frame

The Apple Pay frame renders the Apple Pay button and handles the payment flow. See [Apple Pay frame reference](/platform/frames/apple-pay) for event details.

<Callout icon="apple">
  Apple Pay only works on iOS devices with Apple Pay configured.
</Callout>

### Apple Pay widget

```dart theme={null}
import 'dart:async';
import 'package:flutter/material.dart';

class TransactionResult {
  final String id;
  final String status;

  TransactionResult({required this.id, required this.status});
}

class MoonPayApplePayFrame extends StatefulWidget {
  final String clientToken;
  final String quoteSignature;
  final void Function(TransactionResult) onComplete;
  final void Function(String url) onChallenge;
  final void Function(ConnectError) onError;
  final VoidCallback onQuoteExpired;
  final VoidCallback? onReady;

  const MoonPayApplePayFrame({
    super.key,
    required this.clientToken,
    required this.quoteSignature,
    required this.onComplete,
    required this.onChallenge,
    required this.onError,
    required this.onQuoteExpired,
    this.onReady,
  });

  @override
  State<MoonPayApplePayFrame> createState() => _MoonPayApplePayFrameState();
}

class _MoonPayApplePayFrameState extends State<MoonPayApplePayFrame> {
  late final String _channelId;
  late String _currentQuote;
  final GlobalKey<_MoonPayWebViewState> _webViewKey = GlobalKey();

  @override
  void initState() {
    super.initState();
    _channelId = generateChannelId();
    _currentQuote = widget.quoteSignature;
  }

  @override
  void didUpdateWidget(MoonPayApplePayFrame oldWidget) {
    super.didUpdateWidget(oldWidget);

    // Send updated quote to frame
    if (widget.quoteSignature != _currentQuote) {
      _currentQuote = widget.quoteSignature;
      _webViewKey.currentState?.sendMessage('setQuote', {
        'quote': {'signature': _currentQuote},
      });
    }
  }

  String _buildFrameUrl() {
    final params = {
      'clientToken': widget.clientToken,
      'signature': widget.quoteSignature,
      'channelId': _channelId,
    };

    return '$frameOrigin/platform/v1/apple-pay?${Uri(queryParameters: params).query}';
  }

  void _handleMessage(FrameMessage message) {
    switch (message.kind) {
      case 'ready':
        widget.onReady?.call();
        break;

      case 'complete':
        final payload = message.payload!;
        final transaction = payload['transaction'] as Map<String, dynamic>;

        if (transaction['status'] == 'failed') {
          widget.onError(ConnectError(
            code: 'transactionFailed',
            message: transaction['failureReason'] as String,
          ));
        } else {
          widget.onComplete(TransactionResult(
            id: transaction['id'] as String,
            status: transaction['status'] as String,
          ));
        }
        break;

      case 'challenge':
        final payload = message.payload!;
        final url = payload['url'] as String;
        widget.onChallenge(url);
        break;

      case 'error':
        final payload = message.payload!;
        final code = payload['code'] as String;

        if (code == 'quoteExpired') {
          widget.onQuoteExpired();
        } else {
          widget.onError(ConnectError(
            code: code,
            message: payload['message'] as String,
          ));
        }
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    return MoonPayWebView(
      key: _webViewKey,
      url: _buildFrameUrl(),
      channelId: _channelId,
      onMessage: _handleMessage,
      onHandshake: () {}, // Handled in _handleMessage
      height: 56, // Apple Pay button height
    );
  }
}
```

### Usage

```dart theme={null}
class PaymentScreen extends StatefulWidget {
  final String clientToken;
  final String initialQuoteSignature;

  const PaymentScreen({
    super.key,
    required this.clientToken,
    required this.initialQuoteSignature,
  });

  @override
  State<PaymentScreen> createState() => _PaymentScreenState();
}

class _PaymentScreenState extends State<PaymentScreen> {
  late String _quoteSignature;

  @override
  void initState() {
    super.initState();
    _quoteSignature = widget.initialQuoteSignature;
  }

  Future<void> _fetchNewQuote() async {
    // Fetch a new quote from your API
    final newQuote = await yourApi.getQuote();
    setState(() => _quoteSignature = newQuote.signature);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Pay with Apple Pay')),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          children: [
            // Your payment summary UI
            const Spacer(),
            MoonPayApplePayFrame(
              clientToken: widget.clientToken,
              quoteSignature: _quoteSignature,
              onComplete: (transaction) {
                debugPrint('Transaction initiated: ${transaction.id}');
                Navigator.of(context).pushNamed('/transaction-status');
              },
              onChallenge: (url) => debugPrint('Challenge required: $url'),
              onError: (error) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Payment error: ${error.message}')),
                );
              },
              onQuoteExpired: _fetchNewQuote,
              onReady: () => debugPrint('Apple Pay button ready'),
            ),
          ],
        ),
      ),
    );
  }
}
```

***

## Google Pay frame

The Google Pay frame renders the Google Pay button and handles the payment flow. See [Google Pay frame reference](/platform/frames/google-pay) for event details.

### Google Pay widget

```dart theme={null}
import 'dart:async';
import 'package:flutter/material.dart';

class MoonPayGooglePayFrame extends StatefulWidget {
  final String clientToken;
  final String quoteSignature;
  final void Function(TransactionResult) onComplete;
  final void Function(String url) onChallenge;
  final void Function(ConnectError) onError;
  final VoidCallback onQuoteExpired;
  final VoidCallback? onReady;

  const MoonPayGooglePayFrame({
    super.key,
    required this.clientToken,
    required this.quoteSignature,
    required this.onComplete,
    required this.onChallenge,
    required this.onError,
    required this.onQuoteExpired,
    this.onReady,
  });

  @override
  State<MoonPayGooglePayFrame> createState() => _MoonPayGooglePayFrameState();
}

class _MoonPayGooglePayFrameState extends State<MoonPayGooglePayFrame> {
  late final String _channelId;
  late String _currentQuote;
  final GlobalKey<_MoonPayWebViewState> _webViewKey = GlobalKey();

  @override
  void initState() {
    super.initState();
    _channelId = generateChannelId();
    _currentQuote = widget.quoteSignature;
  }

  @override
  void didUpdateWidget(MoonPayGooglePayFrame oldWidget) {
    super.didUpdateWidget(oldWidget);

    // Send updated quote to frame
    if (widget.quoteSignature != _currentQuote) {
      _currentQuote = widget.quoteSignature;
      _webViewKey.currentState?.sendMessage('setQuote', {
        'quote': {'signature': _currentQuote},
      });
    }
  }

  String _buildFrameUrl() {
    final params = {
      'clientToken': widget.clientToken,
      'signature': widget.quoteSignature,
      'channelId': _channelId,
    };

    return '$frameOrigin/platform/v1/google-pay?${Uri(queryParameters: params).query}';
  }

  void _handleMessage(FrameMessage message) {
    switch (message.kind) {
      case 'ready':
        widget.onReady?.call();
        break;

      case 'complete':
        final payload = message.payload!;
        final transaction = payload['transaction'] as Map<String, dynamic>;

        if (transaction['status'] == 'failed') {
          widget.onError(ConnectError(
            code: 'transactionFailed',
            message: transaction['failureReason'] as String,
          ));
        } else {
          widget.onComplete(TransactionResult(
            id: transaction['id'] as String,
            status: transaction['status'] as String,
          ));
        }
        break;

      case 'challenge':
        final payload = message.payload!;
        final url = payload['url'] as String;
        widget.onChallenge(url);
        break;

      case 'error':
        final payload = message.payload!;
        final code = payload['code'] as String;

        if (code == 'quoteExpired') {
          widget.onQuoteExpired();
        } else {
          widget.onError(ConnectError(
            code: code,
            message: payload['message'] as String,
          ));
        }
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    return MoonPayWebView(
      key: _webViewKey,
      url: _buildFrameUrl(),
      channelId: _channelId,
      onMessage: _handleMessage,
      onHandshake: () {}, // Handled in _handleMessage
      height: 56, // Google Pay button height
    );
  }
}
```

### Usage

```dart theme={null}
class GooglePayScreen extends StatefulWidget {
  final String clientToken;
  final String initialQuoteSignature;

  const GooglePayScreen({
    super.key,
    required this.clientToken,
    required this.initialQuoteSignature,
  });

  @override
  State<GooglePayScreen> createState() => _GooglePayScreenState();
}

class _GooglePayScreenState extends State<GooglePayScreen> {
  late String _quoteSignature;

  @override
  void initState() {
    super.initState();
    _quoteSignature = widget.initialQuoteSignature;
  }

  Future<void> _fetchNewQuote() async {
    // Fetch a new quote from your API
    final newQuote = await yourApi.getQuote();
    setState(() => _quoteSignature = newQuote.signature);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Pay with Google Pay')),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          children: [
            // Your payment summary UI
            const Spacer(),
            MoonPayGooglePayFrame(
              clientToken: widget.clientToken,
              quoteSignature: _quoteSignature,
              onComplete: (transaction) {
                debugPrint('Transaction initiated: ${transaction.id}');
                Navigator.of(context).pushNamed('/transaction-status');
              },
              onChallenge: (url) => debugPrint('Challenge required: $url'),
              onError: (error) {
                ScaffoldMessenger.of(context).showSnackBar(
                  SnackBar(content: Text('Payment error: ${error.message}')),
                );
              },
              onQuoteExpired: _fetchNewQuote,
              onReady: () => debugPrint('Google Pay button ready'),
            ),
          ],
        ),
      ),
    );
  }
}
```

***

## Add Card frame

The add card frame lets a customer save a new card to their account. See [add card frame reference](/platform/frames/add-card) for event details.

### What you'll need

Before you initialize the add card frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)

### Add Card widget

```dart theme={null}
import 'dart:async';
import 'package:flutter/material.dart';

class CardResult {
  final String id;
  final String brand;
  final String last4;
  final String cardType;
  final int expirationMonth;
  final int expirationYear;
  final bool active;

  CardResult({
    required this.id,
    required this.brand,
    required this.last4,
    required this.cardType,
    required this.expirationMonth,
    required this.expirationYear,
    required this.active,
  });
}

class MoonPayAddCardFrame extends StatefulWidget {
  final String clientToken;
  final void Function(CardResult) onComplete;
  final void Function(ConnectError) onError;
  final VoidCallback? onReady;

  const MoonPayAddCardFrame({
    super.key,
    required this.clientToken,
    required this.onComplete,
    required this.onError,
    this.onReady,
  });

  @override
  State<MoonPayAddCardFrame> createState() => _MoonPayAddCardFrameState();
}

class _MoonPayAddCardFrameState extends State<MoonPayAddCardFrame> {
  late final String _channelId;

  @override
  void initState() {
    super.initState();
    _channelId = generateChannelId();
  }

  String _buildFrameUrl() {
    final params = {
      'clientToken': widget.clientToken,
      'channelId': _channelId,
    };

    return '$frameOrigin/platform/v1/add-card?${Uri(queryParameters: params).query}';
  }

  void _handleMessage(FrameMessage message) {
    switch (message.kind) {
      case 'ready':
        widget.onReady?.call();
        break;

      case 'complete':
        final payload = message.payload!;
        final card = payload['card'] as Map<String, dynamic>;
        final availability = card['availability'] as Map<String, dynamic>;
        widget.onComplete(CardResult(
          id: card['id'] as String,
          brand: card['brand'] as String,
          last4: card['last4'] as String,
          cardType: card['cardType'] as String,
          expirationMonth: card['expirationMonth'] as int,
          expirationYear: card['expirationYear'] as int,
          active: availability['active'] as bool,
        ));
        break;

      case 'error':
        final payload = message.payload!;
        widget.onError(ConnectError(
          code: payload['code'] as String,
          message: payload['message'] as String,
        ));
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    return MoonPayWebView(
      url: _buildFrameUrl(),
      channelId: _channelId,
      onMessage: _handleMessage,
      onHandshake: () {},
    );
  }
}
```

### Usage

```dart theme={null}
class SaveCardScreen extends StatelessWidget {
  final String clientToken;

  const SaveCardScreen({super.key, required this.clientToken});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Add Card')),
      body: MoonPayAddCardFrame(
        clientToken: clientToken,
        onComplete: (card) {
          debugPrint('Card saved: ${card.brand} •••• ${card.last4}');
          Navigator.of(context).pop();
        },
        onError: (error) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Error: ${error.message}')),
          );
        },
        onReady: () => debugPrint('Add card frame ready'),
      ),
    );
  }
}
```

***

## Buy frame

The buy frame processes a card payment for a quote. It is headless — rendered at zero size — while the customer completes payment. If 3-D Secure is required, the frame emits a `challenge` event with a URL you open in a separate challenge frame. See [buy frame reference](/platform/frames/buy) for event details.

### What you'll need

Before you initialize the buy frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Buy widget

```dart theme={null}
import 'dart:async';
import 'package:flutter/material.dart';

class MoonPayBuyFrame extends StatefulWidget {
  final String clientToken;
  final String quoteSignature;
  final void Function(TransactionResult) onComplete;
  final void Function(String url) onChallenge;
  final void Function(ConnectError) onError;
  final VoidCallback? onQuoteExpired;

  const MoonPayBuyFrame({
    super.key,
    required this.clientToken,
    required this.quoteSignature,
    required this.onComplete,
    required this.onChallenge,
    required this.onError,
    this.onQuoteExpired,
  });

  @override
  State<MoonPayBuyFrame> createState() => _MoonPayBuyFrameState();
}

class _MoonPayBuyFrameState extends State<MoonPayBuyFrame> {
  late final String _channelId;
  late String _currentQuote;
  final GlobalKey<_MoonPayWebViewState> _webViewKey = GlobalKey();

  @override
  void initState() {
    super.initState();
    _channelId = generateChannelId();
    _currentQuote = widget.quoteSignature;
  }

  @override
  void didUpdateWidget(MoonPayBuyFrame oldWidget) {
    super.didUpdateWidget(oldWidget);

    if (widget.quoteSignature != _currentQuote) {
      _currentQuote = widget.quoteSignature;
      _webViewKey.currentState?.sendMessage('setQuote', {
        'quote': {'signature': _currentQuote},
      });
    }
  }

  String _buildFrameUrl() {
    final params = {
      'clientToken': widget.clientToken,
      'channelId': _channelId,
      'signature': widget.quoteSignature,
    };

    return '$frameOrigin/platform/v1/buy?${Uri(queryParameters: params).query}';
  }

  void _handleMessage(FrameMessage message) {
    switch (message.kind) {
      case 'complete':
        final payload = message.payload!;
        final transaction = payload['transaction'] as Map<String, dynamic>;
        widget.onComplete(TransactionResult(
          id: transaction['id'] as String,
          status: transaction['status'] as String,
        ));
        break;

      case 'challenge':
        final payload = message.payload!;
        widget.onChallenge(payload['url'] as String);
        break;

      case 'error':
        final payload = message.payload!;
        final code = payload['code'] as String;

        if (code == 'quoteExpired') {
          widget.onQuoteExpired?.call();
        } else {
          widget.onError(ConnectError(
            code: code,
            message: payload['message'] as String,
          ));
        }
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    return SizedBox.shrink(
      child: MoonPayWebView(
        key: _webViewKey,
        url: _buildFrameUrl(),
        channelId: _channelId,
        onMessage: _handleMessage,
        onHandshake: () {},
        height: 0,
      ),
    );
  }
}
```

### Challenge widget

```dart theme={null}
import 'dart:async';
import 'package:flutter/material.dart';

class MoonPayChallengeFrame extends StatefulWidget {
  final String challengeUrl;
  final void Function(TransactionResult) onComplete;
  final VoidCallback onCancelled;
  final void Function(ConnectError) onError;

  const MoonPayChallengeFrame({
    super.key,
    required this.challengeUrl,
    required this.onComplete,
    required this.onCancelled,
    required this.onError,
  });

  @override
  State<MoonPayChallengeFrame> createState() => _MoonPayChallengeFrameState();
}

class _MoonPayChallengeFrameState extends State<MoonPayChallengeFrame> {
  late final String _channelId;

  @override
  void initState() {
    super.initState();
    _channelId = generateChannelId();
  }

  void _handleMessage(FrameMessage message) {
    switch (message.kind) {
      case 'complete':
        final payload = message.payload!;
        final transaction = payload['transaction'] as Map<String, dynamic>;
        widget.onComplete(TransactionResult(
          id: transaction['id'] as String,
          status: transaction['status'] as String,
        ));
        break;

      case 'cancelled':
        widget.onCancelled();
        break;

      case 'error':
        final payload = message.payload!;
        widget.onError(ConnectError(
          code: payload['code'] as String,
          message: payload['message'] as String,
        ));
        break;
    }
  }

  String get _frameUrl {
    final uri = Uri.parse(widget.challengeUrl);
    return uri
        .replace(queryParameters: {
          ...uri.queryParameters,
          'channelId': _channelId,
        })
        .toString();
  }

  @override
  Widget build(BuildContext context) {
    return MoonPayWebView(
      url: _frameUrl,
      channelId: _channelId,
      onMessage: _handleMessage,
      onHandshake: () {},
    );
  }
}
```

### Usage

```dart theme={null}
class BuyPaymentScreen extends StatefulWidget {
  final String clientToken;
  final String initialQuoteSignature;

  const BuyPaymentScreen({
    super.key,
    required this.clientToken,
    required this.initialQuoteSignature,
  });

  @override
  State<BuyPaymentScreen> createState() => _BuyPaymentScreenState();
}

class _BuyPaymentScreenState extends State<BuyPaymentScreen> {
  late String _quoteSignature;
  String? _challengeUrl;

  @override
  void initState() {
    super.initState();
    _quoteSignature = widget.initialQuoteSignature;
  }

  Future<void> _fetchNewQuote() async {
    final newQuote = await yourApi.getQuote();
    setState(() => _quoteSignature = newQuote.signature);
  }

  void _handleComplete(TransactionResult transaction) {
    setState(() => _challengeUrl = null);
    debugPrint('Transaction initiated: ${transaction.id}');
    Navigator.of(context).pushNamed('/transaction-status');
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Buy Crypto')),
      body: Stack(
        children: [
          // Your payment summary UI
          MoonPayBuyFrame(
            clientToken: widget.clientToken,
            quoteSignature: _quoteSignature,
            onComplete: _handleComplete,
            onChallenge: (url) => setState(() => _challengeUrl = url),
            onError: (error) {
              ScaffoldMessenger.of(context).showSnackBar(
                SnackBar(content: Text('Error: ${error.message}')),
              );
            },
            onQuoteExpired: _fetchNewQuote,
          ),
          if (_challengeUrl != null)
            Positioned.fill(
              child: MoonPayChallengeFrame(
                challengeUrl: _challengeUrl!,
                onComplete: _handleComplete,
                onCancelled: () => setState(() => _challengeUrl = null),
                onError: (error) {
                  setState(() => _challengeUrl = null);
                  ScaffoldMessenger.of(context).showSnackBar(
                    SnackBar(content: Text('Error: ${error.message}')),
                  );
                },
              ),
            ),
        ],
      ),
    );
  }
}
```

***

## Widget frame

For payment methods beyond Apple Pay — including credit/debit cards, Google Pay, bank transfers, and more — use the [widget frame](/platform/frames/widget). It renders the full MoonPay buy experience inside a WebView, including payment-method selection and transaction confirmation. See [pay with widget](/platform/guides/pay-with-widget) for a full walkthrough.

### Widget widget

```dart theme={null}
import 'dart:async';
import 'package:flutter/material.dart';

class MoonPayWidgetFrame extends StatefulWidget {
  final String clientToken;
  final String quoteSignature;
  final void Function(TransactionResult) onComplete;
  final void Function(ConnectError) onError;
  final void Function(String transactionId, String status)? onTransactionCreated;
  final VoidCallback? onReady;

  const MoonPayWidgetFrame({
    super.key,
    required this.clientToken,
    required this.quoteSignature,
    required this.onComplete,
    required this.onError,
    this.onTransactionCreated,
    this.onReady,
  });

  @override
  State<MoonPayWidgetFrame> createState() => _MoonPayWidgetFrameState();
}

class _MoonPayWidgetFrameState extends State<MoonPayWidgetFrame> {
  late final String _channelId;

  @override
  void initState() {
    super.initState();
    _channelId = generateChannelId();
  }

  String _buildFrameUrl() {
    final params = {
      'flow': 'buy',
      'clientToken': widget.clientToken,
      'quoteSignature': widget.quoteSignature,
      'channelId': _channelId,
    };

    return '$frameOrigin/platform/v1/widget?${Uri(queryParameters: params).query}';
  }

  void _handleMessage(FrameMessage message) {
    switch (message.kind) {
      case 'ready':
        widget.onReady?.call();
        break;

      case 'transactionCreated':
        final payload = message.payload!;
        final transaction = payload['transaction'] as Map<String, dynamic>;
        widget.onTransactionCreated?.call(
          transaction['id'] as String,
          transaction['status'] as String,
        );
        break;

      case 'complete':
        final payload = message.payload!;
        final transaction = payload['transaction'] as Map<String, dynamic>;

        if (transaction['status'] == 'failed') {
          widget.onError(ConnectError(
            code: 'transactionFailed',
            message: transaction['failureReason'] as String,
          ));
        } else {
          widget.onComplete(TransactionResult(
            id: transaction['id'] as String,
            status: transaction['status'] as String,
          ));
        }
        break;

      case 'error':
        final payload = message.payload!;
        widget.onError(ConnectError(
          code: payload['code'] as String,
          message: payload['message'] as String,
        ));
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    return MoonPayWebView(
      url: _buildFrameUrl(),
      channelId: _channelId,
      onMessage: _handleMessage,
      onHandshake: () {},
    );
  }
}
```

### Usage

```dart theme={null}
class WidgetPaymentScreen extends StatelessWidget {
  final String clientToken;
  final String quoteSignature;

  const WidgetPaymentScreen({
    super.key,
    required this.clientToken,
    required this.quoteSignature,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Buy Crypto')),
      body: MoonPayWidgetFrame(
        clientToken: clientToken,
        quoteSignature: quoteSignature,
        onReady: () => debugPrint('Widget loaded'),
        onTransactionCreated: (id, status) {
          debugPrint('Transaction created: $id ($status)');
        },
        onComplete: (transaction) {
          debugPrint('Transaction complete: ${transaction.id}');
          Navigator.of(context).pushNamed('/transaction-status');
        },
        onError: (error) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('Widget error: ${error.message}')),
          );
        },
      ),
    );
  }
}
```


# iOS
Source: https://dev.moonpay.com/platform/guides/manual-integration/ios

Manual frame integration for iOS using WKWebView and Swift.

Use `WKWebView` to embed frames in native iOS applications. The WebView communicates with frames via JavaScript message handlers and script injection.

<Callout icon="book">
  Read the [manual integration
  overview](/platform/guides/manual-integration/overview) for core concepts
  before you continue.
</Callout>

## Setup

### Dependencies

The examples below use [swift-crypto](https://github.com/apple/swift-crypto) for X25519 key exchange, but you can use any library that supports X25519 and AES-GCM.

```swift theme={null}
// Package.swift or via Xcode's Package Dependencies
dependencies: [
    .package(url: "https://github.com/apple/swift-crypto.git", from: "3.0.0"),
]
```

### Key generation

```swift theme={null}
import Crypto
import Foundation

struct MoonPayKeyPair {
    let privateKey: Curve25519.KeyAgreement.PrivateKey
    let publicKeyHex: String

    init() {
        self.privateKey = Curve25519.KeyAgreement.PrivateKey()
        self.publicKeyHex = privateKey.publicKey.rawRepresentation
            .map { String(format: "%02x", $0) }
            .joined()
    }
}
```

### Decryption utility

```swift theme={null}
import CryptoKit
import Foundation

struct MoonPayDecryptor {
    struct EncryptedPayload: Codable {
        let iv: String
        let ephemeralPublicKey: String
        let ciphertext: String
    }

    static func decrypt(_ encryptedValue: String, privateKey: Curve25519.KeyAgreement.PrivateKey) -> String? {
        // The frame returns the encrypted payload as a base64-encoded
        // JSON string. Decode the base64 first, then parse the JSON.
        guard let jsonData = Data(base64Encoded: encryptedValue),
              let encrypted = try? JSONDecoder().decode(EncryptedPayload.self, from: jsonData),
              let ephemeralPublicKeyData = Data(hexString: encrypted.ephemeralPublicKey),
              let ivData = Data(hexString: encrypted.iv),
              let ciphertextData = Data(hexString: encrypted.ciphertext),
              let ephemeralPublicKey = try? Curve25519.KeyAgreement.PublicKey(rawRepresentation: ephemeralPublicKeyData),
              let sharedSecret = try? privateKey.sharedSecretFromKeyAgreement(with: ephemeralPublicKey) else {
            return nil
        }

        // Derive AES key using HKDF
        let symmetricKey = sharedSecret.hkdfDerivedSymmetricKey(
            using: SHA256.self,
            salt: Data(),
            sharedInfo: Data(),
            outputByteCount: 32
        )

        // AES-GCM: ciphertext includes the auth tag at the end (last 16 bytes)
        guard ciphertextData.count > 16,
              let sealedBox = try? AES.GCM.SealedBox(
                  nonce: AES.GCM.Nonce(data: ivData),
                  ciphertext: ciphertextData.dropLast(16),
                  tag: ciphertextData.suffix(16)
              ),
              let decryptedData = try? AES.GCM.open(sealedBox, using: symmetricKey) else {
            return nil
        }

        return String(data: decryptedData, encoding: .utf8)
    }
}

extension Data {
    init?(hexString: String) {
        let len = hexString.count / 2
        var data = Data(capacity: len)
        var index = hexString.startIndex

        for _ in 0..<len {
            let nextIndex = hexString.index(index, offsetBy: 2)
            guard let byte = UInt8(hexString[index..<nextIndex], radix: 16) else { return nil }
            data.append(byte)
            index = nextIndex
        }

        self = data
    }
}
```

### Base frame controller

Create a reusable base view controller for frame communication:

```swift theme={null}
import UIKit
import WebKit

protocol MoonPayFrameDelegate: AnyObject {
    func frameDidReceiveMessage(_ message: [String: Any])
    func frameDidCompleteHandshake()
}

class MoonPayFrameViewController: UIViewController {
    private(set) var webView: WKWebView!
    private(set) var channelId: String

    weak var delegate: MoonPayFrameDelegate?

    let frameOrigin = "https://blocks.moonpay.com"

    init(channelId: String = UUID().uuidString) {
        self.channelId = channelId
        super.init(nibName: nil, bundle: nil)
    }

    required init?(coder: NSCoder) {
        self.channelId = UUID().uuidString
        super.init(coder: coder)
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        setupWebView()
    }

    private func setupWebView() {
        let config = WKWebViewConfiguration()
        let contentController = WKUserContentController()

        contentController.add(self, name: "MoonPayBridge")

        // Expose window.MoonPayBridge so the frame can call postMessage directly
        let bridgeScript = WKUserScript(
            source: """
            window.MoonPayBridge = {
                postMessage: function(message) {
                    window.webkit.messageHandlers.MoonPayBridge.postMessage(message);
                }
            };
            """,
            injectionTime: .atDocumentStart,
            forMainFrameOnly: false
        )
        contentController.addUserScript(bridgeScript)

        config.userContentController = contentController

        webView = WKWebView(frame: view.bounds, configuration: config)
        webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        // Required for the test-mode Apple Pay flow — see "Handle JavaScript
        // dialogs" below.
        webView.uiDelegate = self
        view.addSubview(webView)
    }

    func loadFrame(path: String, params: [String: String]) {
        var components = URLComponents(string: "\(frameOrigin)\(path)")!
        components.queryItems = params.map { URLQueryItem(name: $0.key, value: $0.value) }

        guard let url = components.url else { return }
        webView.load(URLRequest(url: url))
    }

    func sendMessage(kind: String, payload: [String: Any]? = nil) {
        var message: [String: Any] = [
            "version": 2,
            "meta": ["channelId": channelId],
            "kind": kind,
        ]
        if let payload = payload {
            message["payload"] = payload
        }

        guard let jsonData = try? JSONSerialization.data(withJSONObject: message),
              let jsonString = String(data: jsonData, encoding: .utf8) else { return }

        // Re-encode the JSON as a string literal. The frame's bridge
        // listens for `MessageEvent`s whose `data` is a string and ignores
        // anything else, so we must post a string — not an object literal.
        guard let stringLiteralData = try? JSONEncoder().encode(jsonString),
              let jsStringLiteral = String(data: stringLiteralData, encoding: .utf8) else { return }

        let script = "window.postMessage(\(jsStringLiteral), '*');"
        webView.evaluateJavaScript(script, completionHandler: nil)
    }

}

// MARK: - WKScriptMessageHandler

extension MoonPayFrameViewController: WKScriptMessageHandler {
    func userContentController(_ userContentController: WKUserContentController,
                               didReceive message: WKScriptMessage) {
        guard message.name == "MoonPayBridge",
              let body = message.body as? String,
              let data = body.data(using: .utf8),
              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
              let meta = json["meta"] as? [String: Any],
              let messageChannelId = meta["channelId"] as? String,
              messageChannelId == channelId else { return }

        if let kind = json["kind"] as? String, kind == "handshake" {
            sendMessage(kind: "ack")
            delegate?.frameDidCompleteHandshake()
        }

        delegate?.frameDidReceiveMessage(json)
    }
}
```

### Handle JavaScript dialogs

In [test mode](/overview/test-mode#apple-pay), the Apple Pay frame renders a mock button and uses `window.confirm` to simulate the Apple Pay payment sheet. By default, `WKWebView` **silently dismisses** `window.confirm`, `alert`, and `prompt` — the JavaScript call returns `false` with no UI shown — and the frame interprets that as the customer cancelling, so every test transaction comes back with `status: "failed"`.

To surface the simulated payment sheet, conform your base view controller to `WKUIDelegate` and present the confirm panel as a `UIAlertController`:

```swift theme={null}
// MARK: - WKUIDelegate

extension MoonPayFrameViewController: WKUIDelegate {
    func webView(_ webView: WKWebView,
                 runJavaScriptConfirmPanelWithMessage message: String,
                 initiatedByFrame frame: WKFrameInfo,
                 completionHandler: @escaping (Bool) -> Void) {
        let alert = UIAlertController(
            title: "Test Mode",
            message: message.isEmpty ? "Simulate Apple Pay?" : message,
            preferredStyle: .alert
        )
        alert.addAction(UIAlertAction(title: "Cancel", style: .cancel) { _ in
            completionHandler(false)
        })
        alert.addAction(UIAlertAction(title: "OK", style: .default) { _ in
            completionHandler(true)
        })
        present(alert, animated: true)
    }
}
```

`OK` simulates a successful test transaction (the frame emits `complete` with a non-failed status); `Cancel` simulates a failed transaction (the frame emits `complete` with `status: "failed"`).

<Callout icon="info">
  Wire the UI delegate even if you only plan to ship live mode. The WKWebView
  default behaviour applies to any `window.confirm`, `alert`, or `prompt` the
  frame might surface, and it makes test-mode debugging impossible without it.
</Callout>

***

## Check frame

The check frame verifies whether a customer already has an active connection. It's headless — no UI is rendered. Use it to skip the connect flow for returning customers. See [check frame reference](/platform/frames/check) for event details.

### Check controller

```swift theme={null}
import UIKit

protocol CheckFrameDelegate: AnyObject {
    func checkDidFindActiveConnection(accessToken: String, clientToken: String, expiresAt: String)
    func checkDidRequireConnection(accessToken: String, clientToken: String)
    func checkDidFail(status: String, reason: String?)
    func checkDidError(code: String, message: String)
}

class MoonPayCheckViewController: MoonPayFrameViewController {
    private var keyPair: MoonPayKeyPair!
    private var sessionToken: String!

    weak var checkDelegate: CheckFrameDelegate?

    func configure(sessionToken: String) {
        self.sessionToken = sessionToken
        self.keyPair = MoonPayKeyPair()
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard sessionToken != nil else {
            fatalError("Call configure(sessionToken:) before presenting")
        }

        loadFrame(path: "/platform/v1/check-connection", params: [
            "sessionToken": sessionToken,
            "publicKey": keyPair.publicKeyHex,
            "channelId": channelId,
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayCheckViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "complete":
            handleComplete(message["payload"] as? [String: Any] ?? [:])

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            checkDelegate?.checkDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete — checking connection status
    }

    private func handleComplete(_ payload: [String: Any]) {
        guard let status = payload["status"] as? String else { return }

        switch status {
        case "active":
            guard let credentials = payload["credentials"] as? String,
                  let expiresAt = payload["expiresAt"] as? String,
                  let decryptedPayload = MoonPayDecryptor.decrypt(credentials, privateKey: keyPair.privateKey),
                  let credentialsData = decryptedPayload.data(using: .utf8),
                  let credentials = try? JSONSerialization.jsonObject(with: credentialsData) as? [String: String],
                  let accessToken = credentials["accessToken"],
                  let clientToken = credentials["clientToken"] else {
                checkDelegate?.checkDidError(code: "decryption", message: "Failed to decrypt credentials")
                return
            }

            // Check payload["capabilities"]["ramps"]["requirements"]["paymentDisclosures"]
            // to determine if payment disclosures are required before transacting
            checkDelegate?.checkDidFindActiveConnection(accessToken: accessToken, clientToken: clientToken, expiresAt: expiresAt)

        case "connectionRequired":
            guard let credentials = payload["credentials"] as? String,
                  let decryptedPayload = MoonPayDecryptor.decrypt(credentials, privateKey: keyPair.privateKey),
                  let credentialsData = decryptedPayload.data(using: .utf8),
                  let anonymousCredentials = try? JSONSerialization.jsonObject(with: credentialsData) as? [String: String],
                  let accessToken = anonymousCredentials["accessToken"],
                  let clientToken = anonymousCredentials["clientToken"] else {
                checkDelegate?.checkDidError(code: "decryption", message: "Failed to decrypt anonymous credentials")
                return
            }
            checkDelegate?.checkDidRequireConnection(accessToken: accessToken, clientToken: clientToken)

        case "pending", "unavailable", "failed":
            checkDelegate?.checkDidFail(status: status, reason: payload["reason"] as? String)

        default:
            break
        }
    }
}
```

### Usage

```swift theme={null}
class SplashViewController: UIViewController, CheckFrameDelegate {
    func checkConnection() {
        let checkVC = MoonPayCheckViewController()
        checkVC.configure(sessionToken: "your-session-token")
        checkVC.checkDelegate = self

        // The check frame is headless — add as a child without visible UI
        addChild(checkVC)
        checkVC.view.frame = .zero
        view.addSubview(checkVC.view)
        checkVC.didMove(toParent: self)
    }

    // MARK: - CheckFrameDelegate

    func checkDidFindActiveConnection(accessToken: String, clientToken: String, expiresAt: String) {
        // Customer is already connected — skip to payment
        CredentialsManager.shared.accessToken = accessToken
        CredentialsManager.shared.clientToken = clientToken

        let paymentVC = PaymentViewController()
        navigationController?.pushViewController(paymentVC, animated: true)
    }

    func checkDidRequireConnection(accessToken: String, clientToken: String) {
        // Store both tokens in memory, then show connect frame with the anonymous clientToken
        CredentialsManager.shared.accessToken = accessToken
        CredentialsManager.shared.clientToken = clientToken

        let connectVC = MoonPayConnectViewController()
        connectVC.configure(clientToken: clientToken)
        navigationController?.pushViewController(connectVC, animated: true)
    }

    func checkDidFail(status: String, reason: String?) {
        print("Check \(status): \(reason ?? "No reason provided")")
    }

    func checkDidError(code: String, message: String) {
        print("Check error: \(code) — \(message)")
    }
}
```

***

## Connect frame

The connect frame establishes a customer connection to your application. See [connect frame reference](/platform/frames/connect) for event details.

### Connect controller

```swift theme={null}
import UIKit

protocol ConnectFrameDelegate: AnyObject {
    func connectDidComplete(accessToken: String, clientToken: String, expiresAt: String)
    func connectDidFail(status: String, reason: String?)
    func connectDidError(code: String, message: String)
}

class MoonPayConnectViewController: MoonPayFrameViewController {
    private var keyPair: MoonPayKeyPair!
    private var clientToken: String!

    weak var connectDelegate: ConnectFrameDelegate?

    func configure(clientToken: String) {
        self.clientToken = clientToken
        self.keyPair = MoonPayKeyPair()
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard clientToken != nil else {
            fatalError("Call configure(clientToken:) before presenting")
        }

        loadFrame(path: "/platform/v1/connect", params: [
            "clientToken": clientToken,
            "publicKey": keyPair.publicKeyHex,
            "channelId": channelId,
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayConnectViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "complete":
            handleComplete(message["payload"] as? [String: Any] ?? [:])

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            connectDelegate?.connectDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete — waiting for customer interaction
    }

    private func handleComplete(_ payload: [String: Any]) {
        guard let status = payload["status"] as? String else { return }

        switch status {
        case "active":
            guard let credentials = payload["credentials"] as? String,
                  let expiresAt = payload["expiresAt"] as? String,
                  let decryptedPayload = MoonPayDecryptor.decrypt(credentials, privateKey: keyPair.privateKey),
                  let credentialsData = decryptedPayload.data(using: .utf8),
                  let credentials = try? JSONSerialization.jsonObject(with: credentialsData) as? [String: String],
                  let accessToken = credentials["accessToken"],
                  let clientToken = credentials["clientToken"] else {
                connectDelegate?.connectDidError(code: "decryption", message: "Failed to decrypt credentials")
                return
            }

            // Check payload["capabilities"]["ramps"]["requirements"]["paymentDisclosures"]
            // to determine if payment disclosures are required before transacting
            connectDelegate?.connectDidComplete(accessToken: accessToken, clientToken: clientToken, expiresAt: expiresAt)

        case "pending", "unavailable", "failed":
            connectDelegate?.connectDidFail(status: status, reason: payload["reason"] as? String)

        default:
            break
        }
    }
}
```

### Usage

```swift theme={null}
class MyViewController: UIViewController, ConnectFrameDelegate {
    // The clientToken is the anonymous token obtained from the check frame's
    // `connectionRequired` response.
    func showConnect(clientToken: String) {
        let connectVC = MoonPayConnectViewController()
        connectVC.configure(clientToken: clientToken)
        connectVC.connectDelegate = self
        connectVC.modalPresentationStyle = .fullScreen

        present(connectVC, animated: true)
    }

    // MARK: - ConnectFrameDelegate

    func connectDidComplete(accessToken: String, clientToken: String, expiresAt: String) {
        dismiss(animated: true)

        // Store credentials in memory
        CredentialsManager.shared.accessToken = accessToken
        CredentialsManager.shared.clientToken = clientToken

        print("Connected! Expires: \(expiresAt)")
    }

    func connectDidFail(status: String, reason: String?) {
        dismiss(animated: true)
        showAlert(title: "Connection \(status)", message: reason ?? "Please try again later.")
    }

    func connectDidError(code: String, message: String) {
        dismiss(animated: true)
        showAlert(title: "Error", message: message)
    }
}
```

***

## Apple Pay frame

The Apple Pay frame renders a native Apple Pay button and handles the payment flow. See [Apple Pay frame reference](/platform/frames/apple-pay) for event details.

### Apple Pay controller

```swift theme={null}
import UIKit

protocol ApplePayFrameDelegate: AnyObject {
    func applePayDidComplete(transactionId: String, status: String)
    func applePayDidFail(reason: String)
    func applePayDidChallenge(url: String)
    func applePayDidError(code: String, message: String)
    func applePayDidBecomeReady()
}

class MoonPayApplePayViewController: MoonPayFrameViewController {
    private var clientToken: String!
    private var quoteSignature: String!

    weak var applePayDelegate: ApplePayFrameDelegate?

    func configure(clientToken: String, quoteSignature: String) {
        self.clientToken = clientToken
        self.quoteSignature = quoteSignature
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard clientToken != nil, quoteSignature != nil else {
            fatalError("Call configure(clientToken:quoteSignature:) before presenting")
        }

        loadFrame(path: "/platform/v1/apple-pay", params: [
            "clientToken": clientToken,
            "channelId": channelId,
            "signature": quoteSignature,
        ])
    }

    func updateQuote(signature: String) {
        quoteSignature = signature
        sendMessage(kind: "setQuote", payload: [
            "quote": ["signature": signature]
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayApplePayViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            applePayDelegate?.applePayDidBecomeReady()

        case "complete":
            handleComplete(message["payload"] as? [String: Any] ?? [:])

        case "challenge":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let url = payload["url"] as? String ?? ""
            applePayDelegate?.applePayDidChallenge(url: url)

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let code = payload["code"] as? String ?? "unknown"
            let message = payload["message"] as? String ?? "Unknown error"
            applePayDelegate?.applePayDidError(code: code, message: message)

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete
    }

    private func handleComplete(_ payload: [String: Any]) {
        guard let transaction = payload["transaction"] as? [String: Any],
              let status = transaction["status"] as? String else { return }

        if status == "failed" {
            let reason = transaction["failureReason"] as? String ?? "Transaction failed"
            applePayDelegate?.applePayDidFail(reason: reason)
        } else if let transactionId = transaction["id"] as? String {
            applePayDelegate?.applePayDidComplete(transactionId: transactionId, status: status)
        }
    }
}
```

### Usage

```swift theme={null}
class PaymentViewController: UIViewController, ApplePayFrameDelegate {
    private var applePayContainer: UIView!
    private var applePayVC: MoonPayApplePayViewController?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupApplePayFrame()
    }

    private func setupApplePayFrame() {
        applePayContainer = UIView(frame: CGRect(x: 20, y: 200, width: view.bounds.width - 40, height: 50))
        view.addSubview(applePayContainer)

        let applePayVC = MoonPayApplePayViewController()
        applePayVC.configure(
            clientToken: CredentialsManager.shared.clientToken!,
            quoteSignature: currentQuote.signature
        )
        applePayVC.applePayDelegate = self

        addChild(applePayVC)
        applePayVC.view.frame = applePayContainer.bounds
        applePayContainer.addSubview(applePayVC.view)
        applePayVC.didMove(toParent: self)

        self.applePayVC = applePayVC
    }

    // MARK: - ApplePayFrameDelegate

    func applePayDidComplete(transactionId: String, status: String) {
        print("Transaction \(transactionId) status: \(status)")
        // Navigate to transaction status screen
    }

    func applePayDidFail(reason: String) {
        showAlert(title: "Payment Failed", message: reason)
    }

    func applePayDidChallenge(url: String) {
        // Render the challenge frame at the provided URL
        // See "Challenge handling" in the Buy frame section
        let challengeVC = MoonPayChallengeViewController()
        challengeVC.configure(challengeUrl: url)
        challengeVC.challengeDelegate = self
        challengeVC.modalPresentationStyle = .fullScreen
        present(challengeVC, animated: true)
    }

    func applePayDidError(code: String, message: String) {
        if code == "quoteExpired" {
            // Fetch new quote and update
            Task {
                let newQuote = await fetchNewQuote()
                applePayVC?.updateQuote(signature: newQuote.signature)
            }
            return
        }
        showAlert(title: "Error", message: message)
    }

    func applePayDidBecomeReady() {
        print("Apple Pay button is ready")
    }
}
```

***

## Add Card frame

The add card frame lets a customer save a new card to their account. See [add card frame reference](/platform/frames/add-card) for event details.

### Add Card controller

```swift theme={null}
import UIKit

protocol AddCardFrameDelegate: AnyObject {
    func addCardDidComplete(card: [String: Any])
    func addCardDidError(code: String, message: String)
}

class MoonPayAddCardViewController: MoonPayFrameViewController {
    private var clientToken: String!

    weak var addCardDelegate: AddCardFrameDelegate?

    func configure(clientToken: String) {
        self.clientToken = clientToken
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard clientToken != nil else {
            fatalError("Call configure(clientToken:) before presenting")
        }

        loadFrame(path: "/platform/v1/add-card", params: [
            "clientToken": clientToken,
            "channelId": channelId,
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayAddCardViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            break

        case "complete":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let card = payload["card"] as? [String: Any] ?? [:]
            addCardDelegate?.addCardDidComplete(card: card)

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            addCardDelegate?.addCardDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete
    }
}
```

### Usage

```swift theme={null}
class SaveCardViewController: UIViewController, AddCardFrameDelegate {
    private var addCardVC: MoonPayAddCardViewController?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupAddCardFrame()
    }

    private func setupAddCardFrame() {
        let addCardVC = MoonPayAddCardViewController()
        addCardVC.configure(clientToken: CredentialsManager.shared.clientToken!)
        addCardVC.addCardDelegate = self

        addChild(addCardVC)
        addCardVC.view.frame = view.bounds
        addCardVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(addCardVC.view)
        addCardVC.didMove(toParent: self)

        self.addCardVC = addCardVC
    }

    // MARK: - AddCardFrameDelegate

    func addCardDidComplete(card: [String: Any]) {
        print("Card saved: \(card["id"] ?? "")")
        // Proceed to payment with the saved card
    }

    func addCardDidError(code: String, message: String) {
        showAlert(title: "Error", message: message)
    }
}
```

***

## Buy frame

The buy frame processes a card payment for a quote. It is headless — rendered at zero size — while the customer completes payment. If 3-D Secure is required, the frame emits a `challenge` event with a URL you open in a separate challenge frame. See [buy frame reference](/platform/frames/buy) for event details.

### What you'll need

Before you initialize the buy frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Buy controller

```swift theme={null}
import UIKit

protocol BuyFrameDelegate: AnyObject {
    func buyDidComplete(transactionId: String, status: String)
    func buyDidChallenge(url: String)
    func buyDidError(code: String, message: String)
}

class MoonPayBuyViewController: MoonPayFrameViewController {
    private var clientToken: String!
    private var quoteSignature: String!

    weak var buyDelegate: BuyFrameDelegate?

    func configure(clientToken: String, quoteSignature: String) {
        self.clientToken = clientToken
        self.quoteSignature = quoteSignature
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard clientToken != nil, quoteSignature != nil else {
            fatalError("Call configure(clientToken:quoteSignature:) before presenting")
        }

        loadFrame(path: "/platform/v1/buy", params: [
            "clientToken": clientToken,
            "channelId": channelId,
            "signature": quoteSignature,
        ])
    }

    func updateQuote(signature: String) {
        quoteSignature = signature
        sendMessage(kind: "setQuote", payload: [
            "quote": ["signature": signature]
        ])
    }

    func dispose() {
        view.removeFromSuperview()
        removeFromParent()
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayBuyViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            break

        case "complete":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let transaction = payload["transaction"] as? [String: Any] ?? [:]
            let transactionId = transaction["id"] as? String ?? ""
            let status = transaction["status"] as? String ?? ""
            buyDelegate?.buyDidComplete(transactionId: transactionId, status: status)

        case "challenge":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let url = payload["url"] as? String ?? ""
            buyDelegate?.buyDidChallenge(url: url)

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            buyDelegate?.buyDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete
    }
}
```

### Challenge handling

When the buy frame emits a `challenge` event, present a `MoonPayChallengeViewController` with the challenge URL. On completion, cancellation, or error, call `dispose()` on the buy view controller:

```swift theme={null}
protocol ChallengeFrameDelegate: AnyObject {
    func challengeDidComplete(transactionId: String, status: String)
    func challengeDidCancel()
    func challengeDidError(code: String, message: String)
}

class MoonPayChallengeViewController: MoonPayFrameViewController {
    private var challengeUrl: String!

    weak var challengeDelegate: ChallengeFrameDelegate?

    func configure(challengeUrl: String) {
        self.challengeUrl = challengeUrl
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard let rawUrl = challengeUrl,
              var components = URLComponents(string: rawUrl) else {
            fatalError("Call configure(challengeUrl:) before presenting")
        }

        var queryItems = components.queryItems ?? []
        queryItems.append(URLQueryItem(name: "channelId", value: channelId))
        components.queryItems = queryItems

        guard let url = components.url else { return }
        webView.load(URLRequest(url: url))
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayChallengeViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            break

        case "complete":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let transaction = payload["transaction"] as? [String: Any] ?? [:]
            let transactionId = transaction["id"] as? String ?? ""
            let status = transaction["status"] as? String ?? ""
            challengeDelegate?.challengeDidComplete(transactionId: transactionId, status: status)

        case "cancelled":
            challengeDelegate?.challengeDidCancel()

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            challengeDelegate?.challengeDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete
    }
}
```

### Usage

```swift theme={null}
class BuyPaymentViewController: UIViewController, BuyFrameDelegate, ChallengeFrameDelegate {
    private var buyVC: MoonPayBuyViewController?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupBuyFrame()
    }

    private func setupBuyFrame() {
        let buyVC = MoonPayBuyViewController()
        buyVC.configure(
            clientToken: CredentialsManager.shared.clientToken!,
            quoteSignature: currentQuote.signature
        )
        buyVC.buyDelegate = self

        // The buy frame is headless — add as a zero-size child
        addChild(buyVC)
        buyVC.view.frame = .zero
        view.addSubview(buyVC.view)
        buyVC.didMove(toParent: self)

        self.buyVC = buyVC
    }

    // MARK: - BuyFrameDelegate

    func buyDidComplete(transactionId: String, status: String) {
        print("Transaction \(transactionId) status: \(status)")
        // Navigate to transaction status screen
    }

    func buyDidChallenge(url: String) {
        let challengeVC = MoonPayChallengeViewController()
        challengeVC.configure(challengeUrl: url)
        challengeVC.challengeDelegate = self
        challengeVC.modalPresentationStyle = .fullScreen
        present(challengeVC, animated: true)
    }

    func buyDidError(code: String, message: String) {
        if code == "quoteExpired" {
            Task {
                let newQuote = await fetchNewQuote()
                buyVC?.updateQuote(signature: newQuote.signature)
            }
            return
        }
        showAlert(title: "Error", message: message)
    }

    // MARK: - ChallengeFrameDelegate

    func challengeDidComplete(transactionId: String, status: String) {
        dismiss(animated: true)
        buyVC?.dispose()
        print("Transaction \(transactionId) status: \(status)")
        // Navigate to transaction status screen
    }

    func challengeDidCancel() {
        dismiss(animated: true)
        buyVC?.dispose()
    }

    func challengeDidError(code: String, message: String) {
        dismiss(animated: true)
        buyVC?.dispose()
        showAlert(title: "Error", message: message)
    }
}
```

***

## Widget frame

For payment methods beyond Apple Pay — including credit/debit cards, Google Pay, bank transfers, and more — use the [widget frame](/platform/frames/widget). It renders the full MoonPay buy experience inside a WKWebView, including payment-method selection and transaction confirmation. See [pay with widget](/platform/guides/pay-with-widget) for a full walkthrough.

### Widget controller

```swift theme={null}
import UIKit

protocol WidgetFrameDelegate: AnyObject {
    func widgetDidBecomeReady()
    func widgetDidCreateTransaction(transactionId: String, status: String)
    func widgetDidComplete(transactionId: String, status: String)
    func widgetDidFail(reason: String)
    func widgetDidError(code: String, message: String)
}

class MoonPayWidgetViewController: MoonPayFrameViewController {
    private var clientToken: String!
    private var quoteSignature: String!

    weak var widgetDelegate: WidgetFrameDelegate?

    func configure(clientToken: String, quoteSignature: String) {
        self.clientToken = clientToken
        self.quoteSignature = quoteSignature
    }

    override func viewDidLoad() {
        super.viewDidLoad()
        delegate = self

        guard clientToken != nil, quoteSignature != nil else {
            fatalError("Call configure(clientToken:quoteSignature:) before presenting")
        }

        loadFrame(path: "/platform/v1/widget", params: [
            "flow": "buy",
            "clientToken": clientToken,
            "quoteSignature": quoteSignature,
            "channelId": channelId,
        ])
    }
}

// MARK: - MoonPayFrameDelegate

extension MoonPayWidgetViewController: MoonPayFrameDelegate {
    func frameDidReceiveMessage(_ message: [String: Any]) {
        guard let kind = message["kind"] as? String else { return }

        switch kind {
        case "ready":
            widgetDelegate?.widgetDidBecomeReady()

        case "transactionCreated":
            let payload = message["payload"] as? [String: Any] ?? [:]
            let transaction = payload["transaction"] as? [String: Any] ?? [:]
            widgetDelegate?.widgetDidCreateTransaction(
                transactionId: transaction["id"] as? String ?? "",
                status: transaction["status"] as? String ?? ""
            )

        case "complete":
            handleComplete(message["payload"] as? [String: Any] ?? [:])

        case "error":
            let payload = message["payload"] as? [String: Any] ?? [:]
            widgetDelegate?.widgetDidError(
                code: payload["code"] as? String ?? "unknown",
                message: payload["message"] as? String ?? "Unknown error"
            )

        default:
            break
        }
    }

    func frameDidCompleteHandshake() {
        // Handshake complete — widget loading
    }

    private func handleComplete(_ payload: [String: Any]) {
        guard let transaction = payload["transaction"] as? [String: Any],
              let status = transaction["status"] as? String else { return }

        if status == "failed" {
            let reason = transaction["failureReason"] as? String ?? "Transaction failed"
            widgetDelegate?.widgetDidFail(reason: reason)
        } else if let transactionId = transaction["id"] as? String {
            widgetDelegate?.widgetDidComplete(transactionId: transactionId, status: status)
        }
    }
}
```

### Usage

```swift theme={null}
class WidgetPaymentViewController: UIViewController, WidgetFrameDelegate {
    private var widgetVC: MoonPayWidgetViewController?

    override func viewDidLoad() {
        super.viewDidLoad()
        setupWidget()
    }

    private func setupWidget() {
        let widgetVC = MoonPayWidgetViewController()
        widgetVC.configure(
            clientToken: CredentialsManager.shared.clientToken!,
            quoteSignature: currentQuote.signature
        )
        widgetVC.widgetDelegate = self

        addChild(widgetVC)
        widgetVC.view.frame = view.bounds
        widgetVC.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
        view.addSubview(widgetVC.view)
        widgetVC.didMove(toParent: self)

        self.widgetVC = widgetVC
    }

    // MARK: - WidgetFrameDelegate

    func widgetDidBecomeReady() {
        print("Widget loaded and visible")
    }

    func widgetDidCreateTransaction(transactionId: String, status: String) {
        print("Transaction created: \(transactionId) (\(status))")
        // Customer may still need to complete 3-D Secure
    }

    func widgetDidComplete(transactionId: String, status: String) {
        print("Transaction \(transactionId) status: \(status)")
        // Navigate to transaction status screen
    }

    func widgetDidFail(reason: String) {
        showAlert(title: "Payment Failed", message: reason)
    }

    func widgetDidError(code: String, message: String) {
        showAlert(title: "Error", message: message)
    }
}
```


# Overview
Source: https://dev.moonpay.com/platform/guides/manual-integration/overview

Integrate MoonPay frames without using the SDK.

The MoonPay SDK handles frame lifecycle, `postMessage` communication, and encryption automatically. If you're building for a platform where the SDK isn't available or you prefer a direct integration, use the guides in this section.

Before you start, familiarize yourself with how [frames](/platform/frames) work in this integration including their lifecycle, messaging patterns, and events.

## When to integrate manually

You should integrate manually when:

* **You prefer not to bundle third-party SDKs.** If your application has strict requirements around third-party dependencies, you can integrate directly using platform-standard protocols and APIs.
* **You're building for a platform without SDK support.** We currently only provide an SDK for [web](/platform/sdk-reference/web/overview). For native iOS (Swift), Android (Kotlin), and React Native, you can integrate directly.

<Callout icon="envelope">
  **Need an SDK for your platform?** SDK support is expanding. Contact us if you
  need an SDK for iOS, Android, React Native, or another platform.
</Callout>

## Platform guides

The guides below are **reference implementations**, not production-ready starter projects. They illustrate the messaging protocol, encryption flow, and frame lifecycle for each platform. Review and adapt the code to fit your app's architecture, error handling, and security requirements before shipping.

For web, the SDK is strongly recommended, but you can follow the guide below for a direct integration.

Check out the platform-specific guides:

<CardGroup>
  <Card title="Web" icon="browser" href="/platform/guides/manual-integration/web">
    Use iframes in desktop and mobile browsers
  </Card>

  <Card title="React Native" icon="react" href="/platform/guides/manual-integration/react-native">
    Use `react-native-webview`
  </Card>

  <Card title="iOS" icon="apple" href="/platform/guides/manual-integration/ios">
    Use `WKWebView` in Swift
  </Card>

  <Card title="Android" icon="android" href="/platform/guides/manual-integration/android">
    Use `WebView` in Kotlin
  </Card>
</CardGroup>


# React Native
Source: https://dev.moonpay.com/platform/guides/manual-integration/react-native

Manual frame integration for React Native using react-native-webview.

Use `react-native-webview` to embed frames in React Native applications. The WebView communicates with your app through the `ReactNativeWebView` JavaScript interface.

<Callout icon="book">
  Read the [manual integration
  overview](/platform/guides/manual-integration/overview) for core concepts
  before you continue.
</Callout>

## Setup

<Info>
  The `react-native-webview` library automatically injects the
  `ReactNativeWebView` JavaScript interface into the WebView. The frame detects
  this interface and uses it for communication between the frame and your app.
  You don't need to inject a custom JavaScript bridge.
</Info>

### Dependencies

Install `react-native-webview` to render frames in your app.

<Tabs>
  <Tab title="React Native CLI">
    <CodeGroup>
      ```bash pnpm theme={null}
      pnpm i react-native-webview
      ```

      ```bash bun theme={null}
      bun add react-native-webview
      ```

      ```bash npm theme={null}
      npm i react-native-webview
      ```
    </CodeGroup>

    If targeting iOS, you may also need to run:

    ```bash theme={null}
    cd ios && pod install
    ```
  </Tab>

  <Tab title="Expo">
    ```bash theme={null}
    npx expo install react-native-webview
    ```

    See the [Expo WebView docs](https://docs.expo.dev/versions/latest/sdk/webview/) for additional platform configuration.
  </Tab>
</Tabs>

The connect and check frames require X25519 key exchange to encrypt client credentials. The examples below use [noble-curves](https://github.com/paulmillr/noble-curves), but you can use any library that supports X25519 and AES-GCM. You also need a [polyfill for `getRandomValues`](https://github.com/LinusU/react-native-get-random-values) ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)) which is only available in browsers.

<CodeGroup>
  ```bash pnpm theme={null}
  pnpm i react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers
  ```

  ```bash bun theme={null}
  bun add react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers
  ```

  ```bash npm theme={null}
  npm i react-native-get-random-values @noble/curves @noble/hashes @noble/ciphers
  ```
</CodeGroup>

### Base WebView component

Create a reusable base component for frame communication:

```tsx twoslash MoonPayWebView.tsx theme={null}
import React, {
  useRef,
  useCallback,
  useImperativeHandle,
  forwardRef,
} from "react";
import { View, ViewStyle, StyleSheet } from "react-native";
import { WebView, WebViewMessageEvent } from "react-native-webview";

type MoonPayWebViewProps = {
  url: string;
  channelId: string;
  onMessage: (data: FrameMessage) => void;
  onHandshake: () => void;
  style?: ViewStyle;
};

export type MoonPayWebViewRef = {
  sendMessage: (kind: string, payload?: object) => void;
};

export type FrameMessage = {
  version: number;
  meta: { channelId: string };
  kind: string;
  payload?: unknown;
};

export const MoonPayWebView = forwardRef<
  MoonPayWebViewRef,
  MoonPayWebViewProps
>(({ url, channelId, onMessage, onHandshake, style }, ref) => {
  const webViewRef = useRef<WebView>(null);

  const sendMessage = useCallback(
    (kind: string, payload?: object) => {
      const message = {
        version: 2,
        meta: { channelId },
        kind,
        ...(payload && { payload }),
      };

      webViewRef.current?.postMessage(JSON.stringify(message));
    },
    [channelId],
  );

  useImperativeHandle(ref, () => ({ sendMessage }), [sendMessage]);

  const handleMessage = useCallback(
    (event: WebViewMessageEvent) => {
      try {
        const data: FrameMessage = JSON.parse(event.nativeEvent.data);
        if (data.meta?.channelId !== channelId) return;

        if (data.kind === "handshake") {
          sendMessage("ack");
          onHandshake();
        }

        onMessage(data);
      } catch {
        // Ignore malformed messages
      }
    },
    [channelId, sendMessage, onMessage, onHandshake],
  );

  return (
    <View style={[styles.container, style]}>
      <WebView
        ref={webViewRef}
        source={{ uri: url }}
        onMessage={handleMessage}
        javaScriptEnabled
        domStorageEnabled
        allowsInlineMediaPlayback
        originWhitelist={["*"]}
        style={styles.webview}
      />
    </View>
  );
});

const styles = StyleSheet.create({
  container: { flex: 1 },
  webview: { flex: 1 },
});
```

### Encryption utility

When using the connect or check frame, you generate an X25519 keypair and provide the public key to the frame. The frame encrypts the returned client credentials with this key.

#### Key generation

Generate an X25519 keypair for secure communication:

```ts crypto.ts theme={null}
import { x25519 } from "@noble/curves/ed25519";
import { bytesToHex } from "@noble/hashes/utils";
import "react-native-get-random-values"; // Polyfill for crypto.getRandomValues

export function generateKeyPair() {
  const { secretKey, publicKey } = x25519.keygen();

  return {
    privateKeyHex: bytesToHex(secretKey),
    publicKeyHex: bytesToHex(publicKey),
  };
}

export function generateChannelId() {
  return `ch_${Date.now()}_${Math.random().toString(36).slice(2)}`;
}
```

#### Decryption utility

Decrypt the encrypted credentials returned from connect/check frames:

```ts decrypt.ts theme={null}
import { x25519 } from "@noble/curves/ed25519";
import { hkdf } from "@noble/hashes/hkdf";
import { sha256 } from "@noble/hashes/sha256";
import { gcm } from "@noble/ciphers/aes";
import { hexToBytes } from "@noble/hashes/utils";

interface ClientCredentials {
  accessToken: string;
  clientToken: string;
}

export function decryptClientCredentials(
  encryptedValue: string,
  privateKeyHex: string,
): ClientCredentials {
  const encrypted = JSON.parse(encryptedValue) as {
    ephemeralPublicKey: string;
    iv: string;
    ciphertext: string;
  };

  const sharedSecret = x25519.getSharedSecret(
    hexToBytes(privateKeyHex),
    hexToBytes(encrypted.ephemeralPublicKey),
  );

  const derivedKey = hkdf(sha256, sharedSecret, undefined, undefined, 32);

  const aes = gcm(derivedKey, hexToBytes(encrypted.iv));
  const decrypted = aes.decrypt(hexToBytes(encrypted.ciphertext));
  const text = new TextDecoder().decode(decrypted);

  return JSON.parse(text) as ClientCredentials;
}
```

***

## Check frame

The check frame verifies whether a customer already has an active connection. It's headless — no UI is rendered. See [check frame reference](/platform/frames/check) for event details.

### Check component

```tsx theme={null}
import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import {
  generateKeyPair,
  generateChannelId,
  decryptClientCredentials,
} from "./crypto";

const FRAME_ORIGIN = "https://blocks.moonpay.com";

interface CheckFrameProps {
  sessionToken: string;
  onActive: (credentials: { accessToken: string; clientToken: string }) => void;
  onConnectionRequired: (credentials: {
    accessToken: string;
    clientToken: string;
  }) => void;
  onError: (error: { code: string; message: string }) => void;
  onPending?: () => void;
  onUnavailable?: () => void;
}

export function MoonPayCheckFrame({
  sessionToken,
  onActive,
  onConnectionRequired,
  onError,
  onPending,
  onUnavailable,
}: CheckFrameProps) {
  const [channelId] = useState(generateChannelId);
  const [keyPair] = useState(generateKeyPair);

  const frameUrl = `${FRAME_ORIGIN}/platform/v1/check-connection?${new URLSearchParams(
    {
      sessionToken,
      publicKey: keyPair.publicKeyHex,
      channelId,
    },
  ).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "complete":
          const payload = data.payload as {
            status: string;
            credentials?: string;
            reason?: string;
          };

          switch (payload.status) {
            case "active":
              const credentials = decryptClientCredentials(
                payload.credentials!,
                keyPair.privateKeyHex,
              );
              // Check payload.capabilities.ramps.requirements.paymentDisclosures
              // to determine if payment disclosures are required before transacting
              onActive(credentials);
              break;
            case "connectionRequired":
              const anonymousCredentials = decryptClientCredentials(
                payload.credentials!,
                keyPair.privateKeyHex,
              );
              onConnectionRequired(anonymousCredentials);
              break;
            case "pending":
              onPending?.();
              break;
            case "unavailable":
              onUnavailable?.();
              break;
            case "failed":
              onError({
                code: "failed",
                message: payload.reason || "Check failed",
              });
              break;
          }
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [
      keyPair,
      onActive,
      onConnectionRequired,
      onError,
      onPending,
      onUnavailable,
    ],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
    />
  );
}
```

### Usage

```tsx theme={null}
import { MoonPayCheckFrame } from "./MoonPayCheckFrame";

function SplashScreen({ navigation }) {
  return (
    <MoonPayCheckFrame
      sessionToken="your-session-token"
      onActive={({ accessToken, clientToken }) => {
        // Customer is already connected — skip to payment
        console.log("Already connected!", { accessToken, clientToken });
        navigation.navigate("Payment");
      }}
      onConnectionRequired={({ accessToken, clientToken }) => {
        // Store both tokens in memory, then pass clientToken to the connect frame
        CredentialsStore.set({ accessToken, clientToken });
        navigation.navigate("Connect", { clientToken });
      }}
      onError={(error) => {
        console.error("Check failed:", error);
      }}
    />
  );
}
```

***

## Connect frame

The connect frame establishes a customer connection to your application. See [connect frame reference](/platform/frames/connect) for event details.

### Connect component

```tsx theme={null}
import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import {
  generateKeyPair,
  generateChannelId,
  decryptClientCredentials,
} from "./crypto";

const FRAME_ORIGIN = "https://blocks.moonpay.com";

interface ConnectFrameProps {
  clientToken: string;
  onComplete: (credentials: {
    accessToken: string;
    clientToken: string;
  }) => void;
  onError: (error: { code: string; message: string }) => void;
  onPending?: () => void;
  onUnavailable?: () => void;
}

export function MoonPayConnectFrame({
  clientToken,
  onComplete,
  onError,
  onPending,
  onUnavailable,
}: ConnectFrameProps) {
  const [channelId] = useState(generateChannelId);
  const [keyPair] = useState(generateKeyPair);

  const frameUrl = `${FRAME_ORIGIN}/platform/v1/connect?${new URLSearchParams({
    clientToken,
    publicKey: keyPair.publicKeyHex,
    channelId,
  }).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "complete":
          const payload = data.payload as {
            status: string;
            credentials?: string;
            reason?: string;
          };

          switch (payload.status) {
            case "active":
              const credentials = decryptClientCredentials(
                payload.credentials!,
                keyPair.privateKeyHex,
              );
              // Check payload.capabilities.ramps.requirements.paymentDisclosures
              // to determine if payment disclosures are required before transacting
              onComplete(credentials);
              break;
            case "pending":
              onPending?.();
              break;
            case "unavailable":
              onUnavailable?.();
              break;
            case "failed":
              onError({
                code: "failed",
                message: payload.reason || "Connection failed",
              });
              break;
          }
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [keyPair, onComplete, onError, onPending, onUnavailable],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
    />
  );
}
```

### Usage

```tsx theme={null}
import { MoonPayConnectFrame } from "./MoonPayConnectFrame";

function ConnectScreen({ route, navigation }) {
  // The clientToken is the anonymous token passed from the check frame's
  // `connectionRequired` response.
  const { clientToken } = route.params;

  const handleComplete = ({ accessToken, clientToken }) => {
    // Replace the anonymous credentials with the authenticated ones and store
    // them in memory (e.g., React Context or state management).
    console.log("Connected!", { accessToken, clientToken });
    navigation.navigate("Home");
  };

  const handleError = (error) => {
    console.error("Connection failed:", error);
    // Show error UI
  };

  return (
    <MoonPayConnectFrame
      clientToken={clientToken}
      onComplete={handleComplete}
      onError={handleError}
      onPending={() => console.log("Connection pending")}
      onUnavailable={() => console.log("Connection unavailable")}
    />
  );
}
```

***

## Apple Pay frame

The Apple Pay frame renders the Apple Pay button and handles the payment flow. See [Apple Pay frame reference](/platform/frames/apple-pay) for event details.

### Apple Pay component

```tsx theme={null}
import React, {
  useState,
  useCallback,
  useRef,
  useImperativeHandle,
  forwardRef,
} from "react";
import {
  MoonPayWebView,
  MoonPayWebViewRef,
  FrameMessage,
} from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://blocks.moonpay.com";

interface ApplePayFrameProps {
  clientToken: string;
  quoteSignature: string;
  onComplete: (transaction: { id: string; status: string }) => void;
  onChallenge: (url: string) => void;
  onError: (error: { code: string; message: string }) => void;
  onQuoteExpired: () => void;
  onReady?: () => void;
}

export type ApplePayFrameRef = {
  updateQuote: (signature: string) => void;
};

export const MoonPayApplePayFrame = forwardRef<
  ApplePayFrameRef,
  ApplePayFrameProps
>(
  (
    {
      clientToken,
      quoteSignature,
      onComplete,
      onChallenge,
      onError,
      onQuoteExpired,
      onReady,
    },
    ref,
  ) => {
    const frameRef = useRef<MoonPayWebViewRef>(null);
    const [channelId] = useState(generateChannelId);

    const frameUrl = `${FRAME_ORIGIN}/platform/v1/apple-pay?${new URLSearchParams(
      {
        clientToken,
        channelId,
        signature: quoteSignature,
      },
    ).toString()}`;

    useImperativeHandle(
      ref,
      () => ({
        updateQuote: (signature: string) => {
          frameRef.current?.sendMessage("setQuote", {
            quote: { signature },
          });
        },
      }),
      [],
    );

    const handleMessage = useCallback(
      (data: FrameMessage) => {
        switch (data.kind) {
          case "ready":
            onReady?.();
            break;

          case "complete":
            const payload = data.payload as {
              transaction:
                | { id: string; status: string }
                | { status: "failed"; failureReason: string };
            };

            if (payload.transaction.status === "failed") {
              onError({
                code: "transactionFailed",
                message: (payload.transaction as { failureReason: string })
                  .failureReason,
              });
            } else {
              onComplete(payload.transaction as { id: string; status: string });
            }
            break;

          case "challenge":
            const challengePayload = data.payload as {
              kind: string;
              url: string;
            };
            onChallenge(challengePayload.url);
            break;

          case "error":
            const error = data.payload as { code: string; message: string };
            if (error.code === "quoteExpired") {
              onQuoteExpired();
            } else {
              onError(error);
            }
            break;
        }
      },
      [onComplete, onChallenge, onError, onQuoteExpired, onReady],
    );

    return (
      <MoonPayWebView
        ref={frameRef}
        url={frameUrl}
        channelId={channelId}
        onMessage={handleMessage}
        onHandshake={() => {}}
        style={{ height: 56 }}
      />
    );
  },
);
```

### Usage

```tsx theme={null}
import { useRef } from "react";
import { MoonPayApplePayFrame, ApplePayFrameRef } from "./MoonPayApplePayFrame";

function PaymentScreen({ clientToken, quoteSignature }) {
  const applePayRef = useRef<ApplePayFrameRef>(null);

  const handleQuoteExpired = async () => {
    // Fetch a new quote and send it to the frame
    const newQuote = await fetchNewQuote();
    applePayRef.current?.updateQuote(newQuote.signature);
  };

  return (
    <MoonPayApplePayFrame
      ref={applePayRef}
      clientToken={clientToken}
      quoteSignature={quoteSignature}
      onComplete={(tx) => console.log("Transaction initiated:", tx.id)}
      onChallenge={(url) => console.log("Challenge required:", url)}
      onError={(error) => console.error("Payment error:", error)}
      onQuoteExpired={handleQuoteExpired}
      onReady={() => console.log("Apple Pay button ready")}
    />
  );
}
```

***

## Google Pay frame

The Google Pay frame renders the Google Pay button and handles the payment flow. See [Google Pay frame reference](/platform/frames/google-pay) for event details.

### Google Pay component

```tsx theme={null}
import React, {
  useState,
  useCallback,
  useRef,
  useImperativeHandle,
  forwardRef,
} from "react";
import {
  MoonPayWebView,
  MoonPayWebViewRef,
  FrameMessage,
} from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://blocks.moonpay.com";

interface GooglePayFrameProps {
  clientToken: string;
  quoteSignature: string;
  onComplete: (transaction: { id: string; status: string }) => void;
  onChallenge: (url: string) => void;
  onError: (error: { code: string; message: string }) => void;
  onQuoteExpired: () => void;
  onReady?: () => void;
}

export type GooglePayFrameRef = {
  updateQuote: (signature: string) => void;
};

export const MoonPayGooglePayFrame = forwardRef<
  GooglePayFrameRef,
  GooglePayFrameProps
>(
  (
    {
      clientToken,
      quoteSignature,
      onComplete,
      onChallenge,
      onError,
      onQuoteExpired,
      onReady,
    },
    ref,
  ) => {
    const frameRef = useRef<MoonPayWebViewRef>(null);
    const [channelId] = useState(generateChannelId);

    const frameUrl = `${FRAME_ORIGIN}/platform/v1/google-pay?${new URLSearchParams(
      {
        clientToken,
        channelId,
        signature: quoteSignature,
      },
    ).toString()}`;

    useImperativeHandle(
      ref,
      () => ({
        updateQuote: (signature: string) => {
          frameRef.current?.sendMessage("setQuote", {
            quote: { signature },
          });
        },
      }),
      [],
    );

    const handleMessage = useCallback(
      (data: FrameMessage) => {
        switch (data.kind) {
          case "ready":
            onReady?.();
            break;

          case "complete":
            const payload = data.payload as {
              transaction:
                | { id: string; status: string }
                | { status: "failed"; failureReason: string };
            };

            if (payload.transaction.status === "failed") {
              onError({
                code: "transactionFailed",
                message: (payload.transaction as { failureReason: string })
                  .failureReason,
              });
            } else {
              onComplete(payload.transaction as { id: string; status: string });
            }
            break;

          case "challenge":
            const challengePayload = data.payload as {
              kind: string;
              url: string;
            };
            onChallenge(challengePayload.url);
            break;

          case "error":
            const error = data.payload as { code: string; message: string };
            if (error.code === "quoteExpired") {
              onQuoteExpired();
            } else {
              onError(error);
            }
            break;
        }
      },
      [onComplete, onChallenge, onError, onQuoteExpired, onReady],
    );

    return (
      <MoonPayWebView
        ref={frameRef}
        url={frameUrl}
        channelId={channelId}
        onMessage={handleMessage}
        onHandshake={() => {}}
        style={{ height: 56 }}
      />
    );
  },
);
```

### Usage

```tsx theme={null}
import { useRef } from "react";
import {
  MoonPayGooglePayFrame,
  GooglePayFrameRef,
} from "./MoonPayGooglePayFrame";

function PaymentScreen({ clientToken, quoteSignature }) {
  const googlePayRef = useRef<GooglePayFrameRef>(null);

  const handleQuoteExpired = async () => {
    // Fetch a new quote and send it to the frame
    const newQuote = await fetchNewQuote();
    googlePayRef.current?.updateQuote(newQuote.signature);
  };

  return (
    <MoonPayGooglePayFrame
      ref={googlePayRef}
      clientToken={clientToken}
      quoteSignature={quoteSignature}
      onComplete={(tx) => console.log("Transaction initiated:", tx.id)}
      onChallenge={(url) => console.log("Challenge required:", url)}
      onError={(error) => console.error("Payment error:", error)}
      onQuoteExpired={handleQuoteExpired}
      onReady={() => console.log("Google Pay button ready")}
    />
  );
}
```

***

## Add Card frame

The add card frame lets a customer save a new card to their account. See [add card frame reference](/platform/frames/add-card) for event details.

### What you'll need

Before you initialize the add card frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)

### Add Card component

```tsx theme={null}
import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://blocks.moonpay.com";

interface CardResult {
  id: string;
  brand: string;
  last4: string;
  cardType: string;
  expirationMonth: number;
  expirationYear: number;
  availability: { active: boolean };
}

interface AddCardFrameProps {
  clientToken: string;
  onComplete: (card: CardResult) => void;
  onError: (error: { code: string; message: string }) => void;
  onReady?: () => void;
}

export function MoonPayAddCardFrame({
  clientToken,
  onComplete,
  onError,
  onReady,
}: AddCardFrameProps) {
  const [channelId] = useState(generateChannelId);

  const frameUrl = `${FRAME_ORIGIN}/platform/v1/add-card?${new URLSearchParams({
    clientToken,
    channelId,
  }).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "ready":
          onReady?.();
          break;

        case "complete":
          const payload = data.payload as { card: CardResult };
          onComplete(payload.card);
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [onComplete, onError, onReady],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
      style={{ flex: 1 }}
    />
  );
}
```

### Usage

```tsx theme={null}
import { MoonPayAddCardFrame } from "./MoonPayAddCardFrame";

function SaveCardScreen({ clientToken, navigation }) {
  return (
    <MoonPayAddCardFrame
      clientToken={clientToken}
      onComplete={(card) => {
        console.log("Card saved:", card.id, card.brand, card.last4);
        navigation.navigate("Payment");
      }}
      onError={(error) => {
        console.error("Add card error:", error);
      }}
      onReady={() => console.log("Add card frame ready")}
    />
  );
}
```

***

## Buy frame

The buy frame processes a card payment for a quote. It is headless — rendered at zero size — while the customer completes payment. If 3-D Secure is required, the frame emits a `challenge` event with a URL you open in a separate challenge frame. See [buy frame reference](/platform/frames/buy) for event details.

### What you'll need

Before you initialize the buy frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Buy component

```tsx theme={null}
import React, {
  useState,
  useCallback,
  useRef,
  useImperativeHandle,
  forwardRef,
} from "react";
import { StyleSheet } from "react-native";
import {
  MoonPayWebView,
  MoonPayWebViewRef,
  FrameMessage,
} from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://blocks.moonpay.com";

interface BuyFrameProps {
  clientToken: string;
  quoteSignature: string;
  onComplete: (transaction: { id: string; status: string }) => void;
  onChallenge: (url: string) => void;
  onError: (error: { code: string; message: string }) => void;
  onQuoteExpired?: () => void;
}

export type BuyFrameRef = {
  updateQuote: (signature: string) => void;
};

export const MoonPayBuyFrame = forwardRef<BuyFrameRef, BuyFrameProps>(
  (
    {
      clientToken,
      quoteSignature,
      onComplete,
      onChallenge,
      onError,
      onQuoteExpired,
    },
    ref,
  ) => {
    const frameRef = useRef<MoonPayWebViewRef>(null);
    const [channelId] = useState(generateChannelId);

    const frameUrl = `${FRAME_ORIGIN}/platform/v1/buy?${new URLSearchParams({
      clientToken,
      channelId,
      signature: quoteSignature,
    }).toString()}`;

    useImperativeHandle(
      ref,
      () => ({
        updateQuote: (signature: string) => {
          frameRef.current?.sendMessage("setQuote", {
            quote: { signature },
          });
        },
      }),
      [],
    );

    const handleMessage = useCallback(
      (data: FrameMessage) => {
        switch (data.kind) {
          case "complete":
            onComplete(
              (data.payload as { transaction: { id: string; status: string } })
                .transaction,
            );
            break;

          case "challenge":
            const challenge = data.payload as { kind: string; url: string };
            onChallenge(challenge.url);
            break;

          case "error":
            const error = data.payload as { code: string; message: string };
            if (error.code === "quoteExpired") {
              onQuoteExpired?.();
            } else {
              onError(error);
            }
            break;
        }
      },
      [onComplete, onChallenge, onError, onQuoteExpired],
    );

    return (
      <MoonPayWebView
        ref={frameRef}
        url={frameUrl}
        channelId={channelId}
        onMessage={handleMessage}
        onHandshake={() => {}}
        style={StyleSheet.absoluteFillObject}
      />
    );
  },
);
```

### Challenge component

```tsx theme={null}
import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://blocks.moonpay.com";

interface ChallengeFrameProps {
  challengeUrl: string;
  onComplete: (transaction: { id: string; status: string }) => void;
  onCancelled: () => void;
  onError: (error: { code: string; message: string }) => void;
}

export function MoonPayChallengeFrame({
  challengeUrl,
  onComplete,
  onCancelled,
  onError,
}: ChallengeFrameProps) {
  const [channelId] = useState(generateChannelId);

  const frameUrl = useMemo(() => {
    const url = new URL(challengeUrl);
    url.searchParams.set("channelId", channelId);
    return url.toString();
  }, [challengeUrl, channelId]);

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "complete":
          const payload = data.payload as {
            flow: "buy";
            transaction: { id: string; status: string };
          };
          onComplete(payload.transaction);
          break;

        case "cancelled":
          onCancelled();
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [onComplete, onCancelled, onError],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
    />
  );
}
```

### Usage

```tsx theme={null}
import { useRef, useState } from "react";
import { View, StyleSheet } from "react-native";
import { MoonPayBuyFrame, BuyFrameRef } from "./MoonPayBuyFrame";
import { MoonPayChallengeFrame } from "./MoonPayChallengeFrame";

function BuyPaymentScreen({ clientToken, quoteSignature, navigation }) {
  const buyRef = useRef<BuyFrameRef>(null);
  const [challengeUrl, setChallengeUrl] = useState<string | null>(null);

  const handleComplete = (transaction: { id: string; status: string }) => {
    setChallengeUrl(null);
    console.log("Transaction initiated:", transaction.id);
    navigation.navigate("TransactionStatus", { transactionId: transaction.id });
  };

  const handleChallengeResult = (transaction: {
    id: string;
    status: string;
  }) => {
    setChallengeUrl(null);
    console.log("Transaction initiated:", transaction.id);
    navigation.navigate("TransactionStatus", { transactionId: transaction.id });
  };

  const handleQuoteExpired = async () => {
    const newQuote = await fetchNewQuote();
    buyRef.current?.updateQuote(newQuote.signature);
  };

  return (
    <View style={StyleSheet.absoluteFill}>
      <MoonPayBuyFrame
        ref={buyRef}
        clientToken={clientToken}
        quoteSignature={quoteSignature}
        onComplete={handleComplete}
        onChallenge={(url) => setChallengeUrl(url)}
        onError={(error) => console.error("Buy error:", error)}
        onQuoteExpired={handleQuoteExpired}
      />
      {challengeUrl && (
        <View style={StyleSheet.absoluteFill}>
          <MoonPayChallengeFrame
            challengeUrl={challengeUrl}
            onComplete={handleChallengeResult}
            onCancelled={() => setChallengeUrl(null)}
            onError={(error) => {
              console.error("Challenge error:", error);
              setChallengeUrl(null);
            }}
          />
        </View>
      )}
    </View>
  );
}
```

***

## Widget frame

For payment methods beyond Apple Pay — including credit/debit cards, Google Pay, bank transfers, and more — use the [widget frame](/platform/frames/widget). It renders the full MoonPay buy experience inside a WebView, including payment-method selection and transaction confirmation. See [pay with widget](/platform/guides/pay-with-widget) for a full walkthrough.

### Widget component

```tsx theme={null}
import React, { useState, useCallback } from "react";
import { MoonPayWebView, FrameMessage } from "./MoonPayWebView";
import { generateChannelId } from "./crypto";

const FRAME_ORIGIN = "https://blocks.moonpay.com";

interface WidgetFrameProps {
  clientToken: string;
  quoteSignature: string;
  onTransactionCreated?: (transaction: { id: string; status: string }) => void;
  onComplete: (transaction: { id: string; status: string }) => void;
  onError: (error: { code: string; message: string }) => void;
  onReady?: () => void;
}

export function MoonPayWidgetFrame({
  clientToken,
  quoteSignature,
  onTransactionCreated,
  onComplete,
  onError,
  onReady,
}: WidgetFrameProps) {
  const [channelId] = useState(generateChannelId);

  const frameUrl = `${FRAME_ORIGIN}/platform/v1/widget?${new URLSearchParams({
    flow: "buy",
    clientToken,
    quoteSignature,
    channelId,
  }).toString()}`;

  const handleMessage = useCallback(
    (data: FrameMessage) => {
      switch (data.kind) {
        case "ready":
          onReady?.();
          break;

        case "transactionCreated":
          const created = data.payload as {
            transaction: { id: string; status: string };
          };
          onTransactionCreated?.(created.transaction);
          break;

        case "complete":
          const payload = data.payload as {
            transaction:
              | { id: string; status: string }
              | { status: "failed"; failureReason: string };
          };

          if (payload.transaction.status === "failed") {
            onError({
              code: "transactionFailed",
              message: (payload.transaction as { failureReason: string })
                .failureReason,
            });
          } else {
            onComplete(payload.transaction as { id: string; status: string });
          }
          break;

        case "error":
          onError(data.payload as { code: string; message: string });
          break;
      }
    },
    [onComplete, onError, onTransactionCreated, onReady],
  );

  return (
    <MoonPayWebView
      url={frameUrl}
      channelId={channelId}
      onMessage={handleMessage}
      onHandshake={() => {}}
    />
  );
}
```

### Usage

```tsx theme={null}
import { MoonPayWidgetFrame } from "./MoonPayWidgetFrame";

function WidgetPaymentScreen({ clientToken, quoteSignature }) {
  return (
    <MoonPayWidgetFrame
      clientToken={clientToken}
      quoteSignature={quoteSignature}
      onReady={() => console.log("Widget loaded")}
      onTransactionCreated={(tx) =>
        console.log("Transaction created:", tx.id, tx.status)
      }
      onComplete={(tx) => console.log("Transaction complete:", tx.id)}
      onError={(error) => console.error("Widget error:", error)}
    />
  );
}
```


# Web
Source: https://dev.moonpay.com/platform/guides/manual-integration/web

Integrate MoonPay iframes directly in your application.

Use iframes and `postMessage` to embed frames directly in web applications without installing any MoonPay packages.

<Callout icon="book">
  Read the [manual integration
  overview](/platform/guides/manual-integration/overview) for core concepts
  before you continue.
</Callout>

## Setup

### Encryption

The connect and check frames require X25519 key exchange to encrypt client credentials. The examples below use [@noble/curves](https://github.com/paulmillr/noble-curves), but you can use any library that supports X25519 and AES-GCM.

<CodeGroup>
  ```sh pnpm theme={null}
  pnpm i @noble/curves @noble/hashes @noble/ciphers
  ```

  ```sh bun theme={null}
  bun add @noble/curves @noble/hashes @noble/ciphers
  ```

  ```sh npm theme={null}
  npm i @noble/curves @noble/hashes @noble/ciphers
  ```
</CodeGroup>

### Message utilities

Create helper functions for sending and receiving frame messages. All messages follow the [frames protocol](/platform/frames/overview#frames-protocol).

```ts messageUtils.ts theme={null}
const FRAME_ORIGIN = "https://blocks.moonpay.com";

interface FrameMessage {
  version: number;
  meta: { channelId: string };
  kind: string;
  payload?: unknown;
}

function parseFrameMessage(
  event: MessageEvent,
  channelId: string,
): FrameMessage | null {
  if (event.origin !== FRAME_ORIGIN) return null;

  try {
    const data: FrameMessage =
      typeof event.data === "string" ? JSON.parse(event.data) : event.data;
    if (data.meta?.channelId !== channelId) return null;
    return data;
  } catch {
    return null;
  }
}

function sendFrameMessage(
  iframe: HTMLIFrameElement,
  channelId: string,
  kind: string,
  payload?: object,
) {
  const message: FrameMessage = {
    version: 2,
    meta: { channelId },
    kind,
    ...(payload && { payload }),
  };

  iframe.contentWindow?.postMessage(JSON.stringify(message), FRAME_ORIGIN);
}
```

***

## Encryption utility

The connect and check frames return encrypted credentials. Generate an X25519 keypair and provide the public key to the frame.

### Key generation

```ts crypto.ts theme={null}
import { x25519 } from "@noble/curves/ed25519";
import { bytesToHex } from "@noble/hashes/utils";

function generateKeyPair() {
  const { secretKey, publicKey } = x25519.keygen();

  return {
    privateKeyHex: bytesToHex(secretKey),
    publicKeyHex: bytesToHex(publicKey),
  };
}
```

### Decryption

```ts decrypt.ts theme={null}
import { x25519 } from "@noble/curves/ed25519";
import { hkdf } from "@noble/hashes/hkdf";
import { sha256 } from "@noble/hashes/sha256";
import { gcm } from "@noble/ciphers/aes";
import { hexToBytes } from "@noble/hashes/utils";

interface ClientCredentials {
  accessToken: string;
  clientToken: string;
}

function decryptClientCredentials(
  encryptedBase64: string,
  privateKeyHex: string,
): ClientCredentials {
  const json = JSON.parse(atob(encryptedBase64)) as {
    ephemeralPublicKey: string;
    iv: string;
    ciphertext: string;
  };

  const sharedSecret = x25519.getSharedSecret(
    hexToBytes(privateKeyHex),
    hexToBytes(json.ephemeralPublicKey),
  );

  const derivedKey = hkdf(sha256, sharedSecret, undefined, undefined, 32);

  const aes = gcm(derivedKey, hexToBytes(json.iv));
  const decrypted = aes.decrypt(hexToBytes(json.ciphertext));
  const text = new TextDecoder().decode(decrypted);

  return JSON.parse(text) as ClientCredentials;
}
```

***

## Check frame

The check frame verifies whether a customer already has an active connection. It's headless — no UI is rendered. Use it to skip the connect flow for returning customers. See [check frame reference](/platform/frames/check) for event details.

### Initialize the frame

```ts theme={null}
const FRAME_ORIGIN = "https://blocks.moonpay.com";

function initializeCheckFrame(sessionToken: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();
  const keyPair = generateKeyPair();

  const params = new URLSearchParams({
    sessionToken,
    publicKey: keyPair.publicKeyHex,
    channelId,
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/check-connection?${params.toString()}`;

  return { iframe, channelId, keyPair };
}
```

### Handle events

```ts theme={null}
interface CheckCompletePayload {
  status:
    | "active"
    | "connectionRequired"
    | "pending"
    | "unavailable"
    | "failed";
  credentials?: string;
  expiresAt?: string;
  capabilities?: {
    ramps: {
      requirements: {
        paymentDisclosures?: {
          country: string;
          administrativeArea?: string;
          area?: string;
        };
      };
    };
  };
  reason?: string;
}

function setupCheckListener(channelId: string, privateKeyHex: string) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    const iframe = document.getElementById(
      "moonpay-frame",
    ) as HTMLIFrameElement;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "complete":
        handleCheckComplete(
          data.payload as CheckCompletePayload,
          privateKeyHex,
        );
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Check error:", error.code, error.message);
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}

function handleCheckComplete(
  payload: CheckCompletePayload,
  privateKeyHex: string,
) {
  switch (payload.status) {
    case "active":
      const credentials = decryptClientCredentials(
        payload.credentials!,
        privateKeyHex,
      );
      // Store credentials in memory for subsequent API calls and frames
      console.log("Already connected!");
      // Check payload.capabilities.ramps.requirements.paymentDisclosures
      // to determine if payment disclosures are required before transacting
      break;

    case "connectionRequired":
      const anonymousCredentials = decryptClientCredentials(
        payload.credentials!,
        privateKeyHex,
      );
      // Store both tokens in memory, then pass clientToken to the connect frame
      console.log("No active connection — show connect frame");
      break;

    case "pending":
      console.log("Connection pending — customer may need to complete KYC");
      break;

    case "unavailable":
      console.log("Connection unavailable — likely geo-restricted");
      break;

    case "failed":
      console.error("Check failed:", payload.reason);
      break;
  }
}
```

### Usage

```ts theme={null}
const { channelId, keyPair } = initializeCheckFrame("your-session-token");
const cleanup = setupCheckListener(channelId, keyPair.privateKeyHex);

// When done, clean up the listener
// cleanup();
```

***

## Connect frame

The connect frame establishes a customer connection to your application. See [connect frame reference](/platform/frames/connect) for event details.

### Initialize the frame

```ts theme={null}
const FRAME_ORIGIN = "https://blocks.moonpay.com";

function initializeConnectFrame(clientToken: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();
  const keyPair = generateKeyPair();

  const params = new URLSearchParams({
    clientToken,
    publicKey: keyPair.publicKeyHex,
    channelId,
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/connect?${params.toString()}`;

  return { iframe, channelId, keyPair };
}
```

### Handle events

```ts theme={null}
interface ConnectCompletePayload {
  status: "active" | "pending" | "unavailable" | "failed";
  credentials?: string;
  expiresAt?: string;
  capabilities?: {
    ramps: {
      requirements: {
        paymentDisclosures?: {
          country: string;
          administrativeArea?: string;
          area?: string;
        };
      };
    };
  };
  reason?: string;
}

function setupConnectListener(channelId: string, privateKeyHex: string) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    const iframe = document.getElementById(
      "moonpay-frame",
    ) as HTMLIFrameElement;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "complete":
        handleConnectComplete(
          data.payload as ConnectCompletePayload,
          privateKeyHex,
        );
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Connect error:", error.code, error.message);
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}

function handleConnectComplete(
  payload: ConnectCompletePayload,
  privateKeyHex: string,
) {
  switch (payload.status) {
    case "active":
      const credentials = decryptClientCredentials(
        payload.credentials!,
        privateKeyHex,
      );
      // Store tokens in memory for subsequent API calls and frames
      console.log("Connected!");
      // Check payload.capabilities.ramps.requirements.paymentDisclosures
      // to determine if payment disclosures are required before transacting
      break;

    case "pending":
      console.log("Connection pending — customer may need to complete KYC");
      break;

    case "unavailable":
      console.log("Connection unavailable — likely geo-restricted");
      break;

    case "failed":
      console.error("Connection failed:", payload.reason);
      break;
  }
}
```

### Usage

```ts theme={null}
// The clientToken is obtained from the check frame's `connectionRequired` response
const { channelId, keyPair } = initializeConnectFrame("your-client-token");
const cleanup = setupConnectListener(channelId, keyPair.privateKeyHex);

// When done, clean up the listener
// cleanup();
```

***

## Apple Pay frame

The Apple Pay frame renders the Apple Pay button and handles the payment flow. See [Apple Pay frame reference](/platform/frames/apple-pay) for event details.

<Callout icon="apple">
  Apple Pay only works on Safari (macOS and iOS). Check availability before
  rendering.
</Callout>

### What you'll need

Before you initialize the Apple Pay frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Initialize the frame

```ts theme={null}
function initializeApplePayFrame(clientToken: string, quoteSignature: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();

  const params = new URLSearchParams({
    clientToken,
    channelId,
    signature: quoteSignature,
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/apple-pay?${params.toString()}`;

  return { iframe, channelId };
}
```

### Handle events

```ts theme={null}
interface ApplePayCompletePayload {
  transaction:
    | { id: string; status: "complete" | "pending" }
    | { status: "failed"; failureReason: string };
}

function setupApplePayListener(channelId: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;

  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "ready":
        console.log("Apple Pay button ready");
        break;

      case "complete":
        const payload = data.payload as ApplePayCompletePayload;
        if (payload.transaction.status === "failed") {
          console.error(
            "Transaction failed:",
            payload.transaction.failureReason,
          );
        } else {
          console.log("Transaction initiated:", payload.transaction.id);
          // Poll for transaction status or wait for webhook
        }
        break;

      case "challenge":
        const challengePayload = data.payload as { kind: string; url: string };
        // Open the challenge URL in a new iframe — see "Challenge handling" below
        console.log("Challenge required:", challengePayload.url);
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        if (error.code === "quoteExpired") {
          // Fetch a new quote and send it to the frame
          console.log("Quote expired, fetching new quote...");
          // updateApplePayQuote(iframe, channelId, newQuoteSignature);
        } else {
          console.error("Apple Pay error:", error.code, error.message);
        }
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}
```

### Update the quote

When the quote expires or changes, send a new quote to the frame:

```ts theme={null}
function updateApplePayQuote(
  iframe: HTMLIFrameElement,
  channelId: string,
  newQuoteSignature: string,
) {
  sendFrameMessage(iframe, channelId, "setQuote", {
    quote: { signature: newQuoteSignature },
  });
}
```

***

## Google Pay frame

The Google Pay frame renders the Google Pay button and handles the payment flow. See [Google Pay frame reference](/platform/frames/google-pay) for event details.

<Callout icon="circle-info">
  The Google Pay frame requires the `payment` [permission
  policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes).
  When using a sandboxed iframe, include `allow-scripts`, `allow-popups`,
  `allow-same-origin`, and `allow-forms`. See [Google Pay inside sandboxed
  iframe](https://developers.googleblog.com/google-pay-inside-sandboxed-iframe-for-pci-dss-v4-compliance/)
  for details.
</Callout>

### What you'll need

Before you initialize the Google Pay frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Initialize the frame

```ts theme={null}
function initializeGooglePayFrame(clientToken: string, quoteSignature: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();

  // Required for Google Pay — enables the Payment Request API inside the iframe
  iframe.allow = "payment";

  const params = new URLSearchParams({
    clientToken,
    channelId,
    signature: quoteSignature,
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/google-pay?${params.toString()}`;

  return { iframe, channelId };
}
```

### Handle events

```ts theme={null}
interface GooglePayCompletePayload {
  transaction:
    | { id: string; status: "complete" | "pending" }
    | { status: "failed"; failureReason: string };
}

function setupGooglePayListener(channelId: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;

  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "ready":
        console.log("Google Pay button ready");
        break;

      case "complete":
        const payload = data.payload as GooglePayCompletePayload;
        if (payload.transaction.status === "failed") {
          console.error(
            "Transaction failed:",
            payload.transaction.failureReason,
          );
        } else {
          console.log("Transaction initiated:", payload.transaction.id);
          // Poll for transaction status or wait for webhook
        }
        break;

      case "challenge":
        const challengePayload = data.payload as { kind: string; url: string };
        // Open the challenge URL in a new iframe — see "Challenge handling" below
        console.log("Challenge required:", challengePayload.url);
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        if (error.code === "quoteExpired") {
          // Fetch a new quote and send it to the frame
          console.log("Quote expired, fetching new quote...");
          // updateGooglePayQuote(iframe, channelId, newQuoteSignature);
        } else {
          console.error("Google Pay error:", error.code, error.message);
        }
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}
```

### Update the quote

When the quote expires or changes, send a new quote to the frame:

```ts theme={null}
function updateGooglePayQuote(
  iframe: HTMLIFrameElement,
  channelId: string,
  newQuoteSignature: string,
) {
  sendFrameMessage(iframe, channelId, "setQuote", {
    quote: { signature: newQuoteSignature },
  });
}
```

***

## Add Card frame

The add card frame lets a customer save a new card to their account. See [add card frame reference](/platform/frames/add-card) for event details.

### What you'll need

Before you initialize the add card frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)

### Initialize the frame

```ts theme={null}
function initializeAddCardFrame(clientToken: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();

  const params = new URLSearchParams({
    clientToken,
    channelId,
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/add-card?${params.toString()}`;

  return { iframe, channelId };
}
```

### Handle events

```ts theme={null}
interface AddCardCompletePayload {
  card: {
    id: string;
    brand: string;
    last4: string;
    cardType: string;
    expirationMonth: number;
    expirationYear: number;
    availability: { active: boolean };
  };
}

function setupAddCardListener(channelId: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;

  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "ready":
        console.log("Add card frame ready");
        break;

      case "complete":
        const payload = data.payload as AddCardCompletePayload;
        console.log("Card saved:", payload.card.id);
        // Poll for card status or proceed to payment
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Add card error:", error.code, error.message);
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}
```

### Usage

```ts theme={null}
const { channelId } = initializeAddCardFrame("your-client-token");
const cleanup = setupAddCardListener(channelId);

// When done, clean up the listener
// cleanup();
```

***

## Buy frame

The buy frame processes a card payment for a quote. It is headless — rendered at zero size — while the customer completes payment. If 3-D Secure is required, the frame emits a `challenge` event with a URL you open in a separate challenge frame. See [buy frame reference](/platform/frames/buy) for event details.

### What you'll need

Before you initialize the buy frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Initialize the frame

```ts theme={null}
function initializeBuyFrame(
  clientToken: string,
  quoteSignature: string,
  externalTransactionId?: string,
) {
  const channelId = crypto.randomUUID();

  const params = new URLSearchParams({
    clientToken,
    channelId,
    signature: quoteSignature,
    ...(externalTransactionId && { externalTransactionId }),
  });

  const iframe = document.createElement("iframe");
  iframe.style.cssText =
    "position: absolute; width: 0; height: 0; border: none; overflow: hidden;";
  iframe.src = `${FRAME_ORIGIN}/platform/v1/buy?${params.toString()}`;
  document.body.appendChild(iframe);

  return { iframe, channelId };
}
```

### Handle events

```ts theme={null}
interface BuyCompletePayload {
  transaction: { id: string; status: string };
}

interface BuyChallengePayload {
  kind: string;
  url: string;
}

function setupBuyListener(
  channelId: string,
  iframe: HTMLIFrameElement,
  onComplete: (transaction: { id: string; status: string }) => void,
  onChallenge: (url: string) => void,
) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "ready":
        console.log("Buy frame ready");
        break;

      case "complete":
        const payload = data.payload as BuyCompletePayload;
        console.log("Transaction complete:", payload.transaction.id);
        onComplete(payload.transaction);
        break;

      case "challenge":
        const challenge = data.payload as BuyChallengePayload;
        onChallenge(challenge.url);
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        if (error.code === "quoteExpired") {
          // Fetch a new quote and send it to the frame
          console.log("Quote expired, fetching new quote...");
          // updateBuyQuote(iframe, channelId, newQuoteSignature);
        } else {
          console.error("Buy error:", error.code, error.message);
        }
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}
```

### Update the quote

When the quote expires or changes, send a new quote to the frame:

```ts theme={null}
function updateBuyQuote(
  iframe: HTMLIFrameElement,
  channelId: string,
  newQuoteSignature: string,
) {
  sendFrameMessage(iframe, channelId, "setQuote", {
    quote: { signature: newQuoteSignature },
  });
}
```

### Challenge handling

When the buy frame emits a `challenge` event, open the challenge URL in a new iframe inside a modal. The challenge frame is self-driving after the handshake:

```ts theme={null}
interface ChallengeCompletePayload {
  flow: "buy";
  transaction: { id: string; status: string };
}

function setupChallengeListener(
  challengeChannelId: string,
  challengeIframe: HTMLIFrameElement,
  buyIframe: HTMLIFrameElement,
  buyCleanup: () => void,
  onResult: (transaction: { id: string; status: string } | null) => void,
) {
  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, challengeChannelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(challengeIframe, challengeChannelId, "ack");
        break;

      case "ready":
        console.log("Challenge frame ready");
        break;

      case "complete":
        const payload = data.payload as ChallengeCompletePayload;
        cleanup();
        onResult(payload.transaction);
        break;

      case "cancelled":
        cleanup();
        onResult(null);
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Challenge error:", error.code, error.message);
        cleanup();
        onResult(null);
        break;
    }
  };

  function cleanup() {
    window.removeEventListener("message", handler);
    buyCleanup();
    challengeIframe.remove();
    buyIframe.remove();
  }

  window.addEventListener("message", handler);

  return cleanup;
}

function openChallengeFrame(
  challengeUrl: string,
  buyIframe: HTMLIFrameElement,
  buyCleanup: () => void,
  onResult: (transaction: { id: string; status: string } | null) => void,
) {
  const modal = document.getElementById("challengeModal") as HTMLElement;
  const challengeChannelId = crypto.randomUUID();

  const urlWithChannel = new URL(challengeUrl);
  urlWithChannel.searchParams.set("channelId", challengeChannelId);

  const challengeIframe = document.createElement("iframe");
  challengeIframe.src = urlWithChannel.toString();
  modal.appendChild(challengeIframe);

  return setupChallengeListener(
    challengeChannelId,
    challengeIframe,
    buyIframe,
    buyCleanup,
    onResult,
  );
}
```

### Usage

```ts theme={null}
const { iframe: buyIframe, channelId } = initializeBuyFrame(
  "your-client-token",
  "your-quote-signature",
);

const buyCleanup = setupBuyListener(
  channelId,
  buyIframe,
  (transaction) => {
    console.log("Transaction initiated:", transaction.id);
    // Navigate to transaction status screen or poll for updates
  },
  (challengeUrl) => {
    openChallengeFrame(challengeUrl, buyIframe, buyCleanup, (transaction) => {
      if (transaction) {
        console.log("Challenge complete:", transaction.id);
      } else {
        console.log("Challenge cancelled or failed");
      }
    });
  },
);

// When done, clean up the listener
// buyCleanup();
```

***

## Widget frame

For payment methods beyond Apple Pay — including credit/debit cards, Google Pay, bank transfers, and more — use the [widget frame](/platform/frames/widget). It renders the full MoonPay buy experience inside an iframe, including payment-method selection and transaction confirmation. See [pay with widget](/platform/guides/pay-with-widget) for a full walkthrough.

### What you'll need

Before you initialize the widget frame, you need:

1. A `clientToken` from a successful [connect flow](#connect-frame)
2. A valid [quote signature](/api-reference/platform/endpoints/quotes/get) for the transaction

### Initialize the frame

<Callout icon="circle-info">
  The widget iframe requires the `payment` [permission
  policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Permissions-Policy#iframes)
  to process payments.
</Callout>

```ts theme={null}
function initializeWidgetFrame(clientToken: string, quoteSignature: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;
  const channelId = crypto.randomUUID();

  // The widget requires the "payment" permission policy
  iframe.allow = "payment";

  const params = new URLSearchParams({
    flow: "buy",
    clientToken,
    quoteSignature,
    channelId,
  });

  iframe.src = `${FRAME_ORIGIN}/platform/v1/widget?${params.toString()}`;

  return { iframe, channelId };
}
```

### Handle events

```ts theme={null}
interface WidgetCompletePayload {
  transaction:
    | { id: string; status: "complete" | "pending" }
    | { status: "failed"; failureReason: string };
}

function setupWidgetListener(channelId: string) {
  const iframe = document.getElementById("moonpay-frame") as HTMLIFrameElement;

  const handler = (event: MessageEvent) => {
    const data = parseFrameMessage(event, channelId);
    if (!data) return;

    switch (data.kind) {
      case "handshake":
        sendFrameMessage(iframe, channelId, "ack");
        break;

      case "ready":
        console.log("Widget loaded and visible");
        break;

      case "transactionCreated":
        const created = data.payload as {
          transaction: { id: string; status: string };
        };
        console.log("Transaction created:", created.transaction.id);
        // Customer may still need to complete 3-D Secure
        break;

      case "complete":
        const payload = data.payload as WidgetCompletePayload;
        if (payload.transaction.status === "failed") {
          console.error(
            "Transaction failed:",
            payload.transaction.failureReason,
          );
        } else {
          console.log("Transaction initiated:", payload.transaction.id);
          // Poll for transaction status or wait for webhook
        }
        break;

      case "error":
        const error = data.payload as { code: string; message: string };
        console.error("Widget error:", error.code, error.message);
        break;
    }
  };

  window.addEventListener("message", handler);

  return () => window.removeEventListener("message", handler);
}
```

### Usage

```ts theme={null}
const { channelId } = initializeWidgetFrame(
  "your-client-token",
  "your-quote-signature",
);
const cleanup = setupWidgetListener(channelId);

// When done, clean up the listener
// cleanup();
```


# Generate API clients
Source: https://dev.moonpay.com/platform/guides/openapi-codegen

Generate type-safe API clients from the OpenAPI specification.

The MoonPay Developer Platform API is defined using an OpenAPI 3.1 specification. You can use this spec to generate typed clients for any language.

## Full specification

The OpenAPI 3.1 specification is served at **[https://api.moonpay.com/platform/openapi.json](https://api.moonpay.com/platform/openapi.json)**. Use this URL in your codegen config or download the file for offline use.

## Usage

### TypeScript / JavaScript

Use `@hey-api/openapi-ts` to generate TypeScript types:

```bash theme={null}
npm install -D @hey-api/openapi-ts
```

```ts openapi-ts.config.ts theme={null}
import { defineConfig } from "@hey-api/openapi-ts";

export default defineConfig({
  input: "https://api.moonpay.com/platform/openapi.json",
  output: {
    path: "./src/gen",
  },
  plugins: [
    {
      name: "@hey-api/typescript",
      enums: false,
    },
  ],
});
```

```bash theme={null}
npx openapi-ts
```

### Dart / Flutter

Use `openapi_generator` with build\_runner:

```yaml theme={null}
# pubspec.yaml
dev_dependencies:
  build_runner: ^2.4.0
  openapi_generator: ^5.0.0

openapi_generator:
  input_spec:
    path: https://api.moonpay.com/platform/openapi.json
  generator_name: dart
  output_directory: lib/gen
```

```bash theme={null}
flutter pub run build_runner build
```

### Other Languages

Use the [OpenAPI Generator](https://openapi-generator.tech/) CLI to generate clients for 50+ languages:

```bash theme={null}
# Install
npm install @openapitools/openapi-generator-cli -g

# Generate (examples)
openapi-generator-cli generate -i https://api.moonpay.com/platform/openapi.json -g kotlin -o ./gen
openapi-generator-cli generate -i https://api.moonpay.com/platform/openapi.json -g swift5 -o ./gen
openapi-generator-cli generate -i https://api.moonpay.com/platform/openapi.json -g python -o ./gen
openapi-generator-cli generate -i https://api.moonpay.com/platform/openapi.json -g go -o ./gen
```

See the [full list of generators](https://openapi-generator.tech/docs/generators).


# Pay with Apple Pay
Source: https://dev.moonpay.com/platform/guides/pay-with-apple-pay

Allow customers to buy crypto headlessly with Apple Pay.

Use this guide to execute a transaction with Apple Pay after you have a [connected customer](/platform/guides/connect-a-customer).

See the [Going Live](/platform/overview/going-live) section for details on the requirements you must meet before you can take this integration to production.

## Prerequisites

* A connected customer (via `client.getConnection()` or `client.connect()`).
* A UI surface where you can render the [Apple Pay frame](/platform/frames/apple-pay).

<Tip>
  You can test the full Apple Pay flow without a real Apple Pay account by using
  [test mode](/platform/overview/test-mode#apple-pay). The frame renders a mock
  Apple Pay button that simulates successful and failed transactions.
</Tip>

## Display payment methods

Use the SDK or API to fetch and display the payment methods that are available for the customer right now.

<CodeGroup>
  ```ts List payment methods theme={null}
  // After connecting, list available payment methods
  const paymentMethodsResult = await client.getPaymentMethods();

  if (!paymentMethodsResult.ok) {
    // Handle error
  }

  console.log(paymentMethodsResult.value);
  ```

  ```ts Result theme={null}
  [
    {
      type: "apple_pay",
      capabilities: {
        supportedCurrencies: ["USD", "EUR", "GBP"],
        supportedTransactionTypes: ["buy"],
      },
      availability: {
        active: true,
      },
    },
  ];
  ```
</CodeGroup>

## Get quotes

Quotes provide real-time prices and fees for transactions. Present detailed quotes in your UI using data from the SDK or API.

Only executable quotes can be used for transactions. In some cases, quotes require a challenge before you can execute a transaction. See [handling challenges](/platform/guides/handling-challenges) for details.

<CodeGroup>
  ```ts Get quote theme={null}
  const quoteResult = await client.getQuote({
    source: "USD", // The fiat currency for payment
    destination: "ETH", // The crypto the customer will receive
    sourceAmount: "100.00", // The amount to purchase
    walletAddress: "0x1234...", // The destination wallet address
    paymentMethod: "apple_pay", // The payment method type
  });

  if (!quoteResult.ok) {
    // Handle error
  }

  console.log(quoteResult.value);
  ```

  ```ts Result theme={null}
  {
    source: {
      amount: "100.00",
      asset: {
        code: "USD",
        name: "US Dollar",
        precision: 2
      }
    },
    destination: {
      amount: "0.025",
      asset: {
        code: "ETH",
        name: "Ethereum",
        precision: 18
      }
    },
    fees: {
      network: {
        amount: "2.50",
        currencyCode: "USD"
      },
      moonpay: {
        amount: "3.99",
        currencyCode: "USD"
      }
    },
    wallet: {
      address: "0x1234..."
    },
    paymentMethod: {
      type: "apple_pay"
    },
    expiresAt: "2026-01-12T14:45:00Z",
    executable: true,
    signature: "eyJhbGciOiJFUzI1NiIs..."
  }
  ```
</CodeGroup>

## Execute the transaction

To execute a transaction, set up the payment flow based on the quote. Different payment methods have different requirements—you can configure each as needed to control your experience. For the frame URL, size, permissions, and events, see the [Apple Pay frame](/platform/frames/apple-pay) reference.

<Tip>
  In some cases, transactions require a challenge. See [handling
  challenges](/platform/guides/handling-challenges) for details.
</Tip>

```ts Apple Pay theme={null}
import type { ApplePayEvent } from "@moonpay/platform";

// Render the Apple Pay frame into your UI and handle callbacks
const applePayResult = await client.setupApplePay({
  quote: quoteResult.value.signature, // The quote signature from getQuote

  container: document.querySelector("#applePayContainer"), // DOM element to render the button

  onEvent: (event: ApplePayEvent) => {
    switch (event.kind) {
      case "ready":
        // The frame is ready. Use this event to reveal the button if needed.
        break;

      case "complete":
        // The transaction is executing. Track the final status via polling and/or webhooks.
        console.log(event.payload.transaction);
        // { id: "txn_01", status: "pending" }
        break;

      case "challenge":
        // Verification required. Render the challenge frame at the provided URL.
        // See: /platform/guides/handling-challenges
        console.log(event.payload.url);
        break;

      case "quoteExpired":
        // Fetch a new quote, then pass its signature into the frame
        // const newQuote = await client.getQuote({...});
        // event.payload.setQuote(newQuote.value.signature);
        break;

      case "error":
        // Depending on the error, you can have the customer pick a different payment method or retry.
        console.error(event.payload.message);
        break;

      case "unsupported":
        // Apple Pay isn't supported in the current environment.
        break;
    }
  },
});

if (!applePayResult.ok) {
  // Handle error setting up Apple Pay
}

// You can update the quote or dispose the frame later
// applePayResult.value.setQuote(newQuoteSignature);
// applePayResult.value.dispose();
```

## Transaction statuses

Transactions have the following statuses:

* **Pending:** The transaction has been initiated and the payment accepted. The assets are being transferred.
* **Complete:** The transaction is finalized. The payment is complete and the assets have been delivered to their destination.
* **Failed:** The transaction has failed. The payment was not executed and funds were not transferred.


# Pay with card
Source: https://dev.moonpay.com/platform/guides/pay-with-card

Allow customers to buy crypto using stored credit and debit cards.

Use this guide to execute a card transaction after you have a [connected
customer](/platform/guides/connect-a-customer). You will list stored cards, add
new ones through a MoonPay-hosted frame, get a quote, and execute the
transaction — with MoonPay handling PCI-compliant card collection, payment
orchestration, and all verification challenges inside hosted frames.

See the [Going Live](/platform/overview/going-live) section for requirements you
must meet before taking this integration to production.

## Prerequisites

* A MoonPay account with card payments enabled. Contact your MoonPay account
  team to enable it.
* A connected customer (via `client.getConnection()` or `client.connect()`).
* A UI surface where you can render MoonPay frames (iframe on web, or
  [WebView](/platform/overview/requirements#webviews) on mobile).
* A destination wallet address for the purchased crypto.

## Flow overview

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor C as Customer
    participant FE as Your frontend
    participant API as MoonPay API
    participant ACF as Add Card frame
    participant BF as Buy frame
    participant CF as Challenge frame

    Note over C,CF: Prerequisite: customer is connected

    FE->>API: GET /platform/v1/payment-methods
    API-->>FE: { paymentMethodConfigs, paymentMethods }

    alt No stored cards
        FE->>ACF: Render Add Card frame
        ACF-->>FE: complete({ card: { id, brand, last4, ... } })
    end

    C->>FE: Selects card, enters amount
    FE->>API: POST /platform/v1/quotes/buy
    API-->>FE: { quote with signature }

    C->>FE: Confirms purchase
    FE->>BF: Render buy frame (signature, clientToken)

    alt Happy path
        BF-->>FE: complete({ transaction: { id, status } })
    else Verification required
        BF-->>FE: challenge({ url })
        FE->>CF: Render challenge frame at URL
        CF-->>FE: complete({ transaction: { id, status } })
    end

    FE->>API: GET /platform/v1/transactions/{id}
    Note over FE: Poll for final status
```

<Steps>
  <Step title="List payment methods">
    Fetch the customer's available payment method types and stored cards.

    <CodeGroup>
      ```ts List payment methods theme={null}
      const paymentMethodsResult = await client.getPaymentMethods();

      if (!paymentMethodsResult.ok) {
        // Handle error
      }

      console.log(paymentMethodsResult.value);
      ```

      ```ts Result theme={null}
      {
        paymentMethodConfigs: [
          {
            type: "card",
            capabilities: {
              supportedCurrencies: ["USD", "EUR", "GBP"],
              supportedTransactionTypes: ["buy"],
              allowsDeletion: true,
            },
            availability: { active: true },
          },
        ],
        paymentMethods: [
          {
            id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            type: "card",
            brand: "visa",
            last4: "4242",
            expirationMonth: "12",
            expirationYear: "2027",
            cardType: "credit",
            availability: { active: true },
          },
        ],
      }
      ```
    </CodeGroup>

    The result contains two collections:

    * **`paymentMethodConfigs`** — available payment method types. Check for
      `type: "card"` to confirm card payments are available for this customer.
    * **`paymentMethods`** — the customer's stored cards. Each entry includes
      `brand`, `last4`, `expirationMonth`, `expirationYear`, `cardType`, and
      `availability`.

    Display active cards in your payment method picker. For inactive cards
    (`availability.active: false`), show the `reasons` value and prompt the user to
    add a new card.

    | `reasons` value | Suggested UX                                     |
    | --------------- | ------------------------------------------------ |
    | `card_expired`  | "This card has expired. Add a new card."         |
    | `card_blocked`  | "This card is no longer available."              |
    | `card_declined` | "This card can't be used. Try a different card." |

    <Tip>
      If `paymentMethods` is empty and `paymentMethodConfigs` includes `type:
              "card"`, guide the customer to add one using the Add Card frame (Step 2).
    </Tip>
  </Step>

  <Step title="Add a card">
    When the customer needs to add a new card, set up the Add Card frame. The frame
    collects card details and billing address inside a PCI-compliant MoonPay-hosted
    UI — card data never touches your domain. For the frame URL, size, and events,
    see the [Add Card frame](/platform/frames/add-card) reference.

    ```ts Add a card theme={null}
    import type { AddCardEvent } from "@moonpay/platform";

    const addCardResult = await client.setupAddCard({
      container: document.querySelector("#addCardContainer"),

      onEvent: (event: AddCardEvent) => {
        switch (event.kind) {
          case "ready":
            // Frame rendered — reveal the modal if it was hidden
            break;

          case "complete":
            // Card added. Use event.payload.card.id to get a quote in Step 3.
            console.log(event.payload.card);
            // { id, brand, last4, cardType, expirationMonth, expirationYear }
            break;

          case "error":
            console.error(event.payload.message);
            break;
        }
      },
    });

    if (!addCardResult.ok) {
      // Handle error setting up the Add Card frame
    }
    ```

    The `complete` event returns the new card's full details including its `id`. Use
    this `id` directly to get a quote in Step 3 — no need to re-fetch payment
    methods.
  </Step>

  <Step title="Get a quote">
    With a stored card selected, request a quote. Pass the card's `id` in
    `paymentMethod` so MoonPay can evaluate card-specific requirements.

    <CodeGroup>
      ```ts Get quote theme={null}
      const quoteResult = await client.getQuote({
        source: "USD",
        destination: "ETH",
        sourceAmount: "100.00",
        walletAddress: "0x1234567890abcdef1234567890abcdef12345678",
        paymentMethod: { type: "card", id: cardId },
      });

      if (!quoteResult.ok) {
        // Handle error
      }

      console.log(quoteResult.value);
      ```

      ```ts Result theme={null}
      {
        source: {
          amount: "100.00",
          asset: { code: "USD" }
        },
        destination: {
          amount: "0.025",
          asset: { code: "ETH" }
        },
        fees: {
          network: { amount: "2.50", currencyCode: "USD" },
          moonpay: { amount: "3.99", currencyCode: "USD" }
        },
        wallet: { address: "0x1234..." },
        paymentMethod: { type: "card", id: "a1b2c3d4-..." },
        expiresAt: "2026-04-29T15:45:00Z",
        executable: true,
        signature: "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
      ```
    </CodeGroup>

    Display the quote in your buy confirmation screen: source amount, destination
    amount, fees, and exchange rate. Monitor `expiresAt` and refresh the quote
    before it expires. If the buy frame is already loaded, call
    `buyResult.value.setQuote(newSignature)` instead of re-creating the frame.
  </Step>

  <Step title="Execute the transaction">
    ### Headless buy frame

    Use `client.setupBuy()` when you want full control over your purchase UI. The
    frame is headless — no visible UI — and emits events for you to handle. For the
    frame URL, parameters, and events, see the [Buy frame](/platform/frames/buy)
    reference.

    ```ts setupBuy theme={null}
    import type { BuyEvent } from "@moonpay/platform";

    const buyResult = await client.setupBuy({
      quote: quoteResult.value.signature,

      onEvent: (event: BuyEvent) => {
        switch (event.kind) {
          case "ready":
            // Pipeline starting — show a loading indicator
            break;

          case "complete":
            // Transaction complete. Track status via polling.
            console.log(event.payload.transaction);
            // { id: "txn_01", status: "pending" }
            break;

          case "challenge":
            // Verification required — render the challenge frame
            openChallengeFrame(event.payload.url, buyResult);
            break;

          case "quoteExpired":
            // Fetch a new quote, then update the frame:
            // const newQuote = await client.getQuote({...});
            // event.payload.setQuote(newQuote.value.signature);
            break;

          case "error":
            console.error(event.payload.message);
            break;
        }
      },
    });

    if (!buyResult.ok) {
      // Handle error
    }
    ```
  </Step>

  <Step title="Handle challenges">
    When the buy frame emits a `challenge` event, the customer must complete one or
    more verification steps before the transaction can proceed. Set up the challenge
    frame with the URL from the event payload — do not construct the URL yourself.
    For the frame URL, parameters, and events, see the [Challenge
    frame](/platform/frames/challenge) reference.

    The frame is self-driving: after initialization, it sequences through all
    required verification steps, creates the transaction, and emits `complete` when
    the pipeline finishes.

    ```ts Handle challenges theme={null}
    import type { ChallengeEvent } from "@moonpay/platform";

    async function openChallengeFrame(
      challengeUrl: string,
      buyResult: SetupBuyResult,
    ) {
      // The challenge URL does not include a channelId — append one before rendering.
      const url = new URL(challengeUrl);
      url.searchParams.set("channelId", crypto.randomUUID());

      const challengeResult = await client.setupChallenge({
        challengeUrl: url.toString(),
        container: document.querySelector("#challengeModal"),

        onEvent: (event: ChallengeEvent) => {
          switch (event.kind) {
            case "ready":
              // Challenge UI is rendered and visible
              break;

            case "complete":
              // All verification resolved, transaction complete.
              buyResult.value.dispose();
              navigateToConfirmation(event.payload.transaction);
              break;

            case "cancelled":
              // Customer dismissed the challenge — allow retry.
              buyResult.value.dispose();
              showRetryOption();
              break;

            case "error":
              buyResult.value.dispose();
              console.error(event.payload.message);
              break;
          }
        },
      });
    }
    ```

    <Warning>
      When you receive `complete`, `cancelled`, or `error` from the challenge frame,
      call `buyResult.value.dispose()` to also tear down the buy frame.
    </Warning>

    The frame handles all verification types automatically — KYC, Strong Customer
    Authentication (SCA), CVC re-entry, wallet ownership, micro-authorization, and
    3D Secure (3DS). You never need to distinguish between them.
  </Step>

  <Step title="Track the transaction">
    When the buy frame or challenge frame emits `complete`, the payload includes
    `{ transaction: { id, status } }`. The transaction is created and payment is
    processing.

    ```ts Track the transaction theme={null}
    async function pollTransaction(transactionId: string) {
      const terminal = new Set(["completed", "failed"]);

      while (true) {
        const res = await client.getTransaction(transactionId);

        if (!res.ok) throw new Error(res.error.message);
        if (terminal.has(res.value.status)) return res.value.status;

        await new Promise((r) => setTimeout(r, 3000));
      }
    }
    ```

    ## Transaction statuses

    Transactions have the following statuses:

    * **Pending:** The transaction has been initiated and the payment accepted. The
      assets are being transferred.
    * **Complete:** The transaction is finalized. The payment is complete and the
      assets have been delivered to their destination.
    * **Failed:** The transaction has failed. The payment was not executed and funds
      were not transferred.

    <Note>
      Webhook support is coming soon. Until then, use polling to track transaction
      status.
    </Note>
  </Step>

  <Step title="Delete a stored card (optional)">
    Let customers remove stored cards at any time.

    ```ts Delete a stored card theme={null}
    const deleteResult = await client.deletePaymentMethod(paymentMethodId);

    if (!deleteResult.ok) {
      // Handle error
    }
    ```

    * Deleting an already-deleted card returns success (idempotent).
    * Deleting a card with a pending transaction is rejected.
    * Only payment methods with `allowsDeletion: true` can be deleted.
  </Step>
</Steps>


# Pay with Google Pay
Source: https://dev.moonpay.com/platform/guides/pay-with-google-pay

Allow customers to buy crypto headlessly with Google Pay.

Use this guide to execute a transaction with Google Pay after you have a [connected customer](/platform/guides/connect-a-customer).

See the [Going Live](/platform/overview/going-live) section for details on the requirements you must meet before you can take this integration to production.

## Prerequisites

* A connected customer (via `client.getConnection()` or `client.connect()`).
* A UI surface where you can render the [Google Pay frame](/platform/frames/google-pay).

<Tip>
  You can test the Google Pay flow using [test
  mode](/platform/overview/test-mode). Test mode uses simulated payments and
  testnet blockchains so no real assets are transferred.
</Tip>

## Display payment methods

Use the SDK or API to fetch and display the payment methods that are available for the customer right now.

<CodeGroup>
  ```ts List payment methods theme={null}
  // After connecting, list available payment methods
  const paymentMethodsResult = await client.getPaymentMethods();

  if (!paymentMethodsResult.ok) {
    // Handle error
  }

  console.log(paymentMethodsResult.value);
  ```

  ```ts Result theme={null}
  [
    {
      type: "google_pay",
      capabilities: {
        supportedCurrencies: ["USD", "EUR", "GBP"],
        supportedTransactionTypes: ["buy"],
      },
      availability: {
        active: true,
      },
    },
  ];
  ```
</CodeGroup>

## Get quotes

Quotes provide real-time prices and fees for transactions. Present detailed quotes in your UI using data from the SDK or API.

Only executable quotes can be used for transactions. In some cases, quotes require a challenge before you can execute a transaction. See [handling challenges](/platform/guides/handling-challenges) for details.

<CodeGroup>
  ```ts Get quote theme={null}
  const quoteResult = await client.getQuote({
    source: "USD", // The fiat currency for payment
    destination: "ETH", // The crypto the customer will receive
    sourceAmount: "100.00", // The amount to purchase
    walletAddress: "0x1234...", // The destination wallet address
    paymentMethod: "google_pay", // The payment method type
  });

  if (!quoteResult.ok) {
    // Handle error
  }

  console.log(quoteResult.value);
  ```

  ```ts Result theme={null}
  {
    source: {
      amount: "100.00",
      asset: {
        code: "USD",
        name: "US Dollar",
        precision: 2
      }
    },
    destination: {
      amount: "0.025",
      asset: {
        code: "ETH",
        name: "Ethereum",
        precision: 18
      }
    },
    fees: {
      network: {
        amount: "2.50",
        currencyCode: "USD"
      },
      moonpay: {
        amount: "3.99",
        currencyCode: "USD"
      }
    },
    wallet: {
      address: "0x1234..."
    },
    paymentMethod: {
      type: "google_pay"
    },
    expiresAt: "2026-01-12T14:45:00Z",
    executable: true,
    signature: "eyJhbGciOiJFUzI1NiIs..."
  }
  ```
</CodeGroup>

## Execute the transaction

To execute a transaction, set up the payment flow based on the quote. Different payment methods have different requirements—you can configure each as needed to control your experience. For the frame URL, size, permissions, and events, see the [Google Pay frame](/platform/frames/google-pay) reference.

<Tip>
  In some cases, transactions require a challenge. See [handling
  challenges](/platform/guides/handling-challenges) for details.
</Tip>

```ts Google Pay theme={null}
import type { GooglePayEvent } from "@moonpay/platform";

// Render the Google Pay frame into your UI and handle callbacks
const googlePayResult = await client.setupGooglePay({
  quote: quoteResult.value.signature, // The quote signature from getQuote

  container: document.querySelector("#googlePayContainer"), // DOM element to render the button

  onEvent: (event: GooglePayEvent) => {
    switch (event.kind) {
      case "ready":
        // The frame is ready. Use this event to reveal the button if needed.
        break;

      case "complete":
        // The transaction is executing. Track the final status via polling and/or webhooks.
        console.log(event.payload.transaction);
        // { id: "txn_01", status: "pending" }
        break;

      case "challenge":
        // Verification required. Render the challenge frame at the provided URL.
        // See: /platform/guides/handling-challenges
        console.log(event.payload.url);
        break;

      case "quoteExpired":
        // Fetch a new quote, then pass its signature into the frame
        // const newQuote = await client.getQuote({...});
        // event.payload.setQuote(newQuote.value.signature);
        break;

      case "error":
        // Depending on the error, you can have the customer pick a different payment method or retry.
        console.error(event.payload.message);
        break;

      case "unsupported":
        // Google Pay isn't supported in the current environment.
        break;
    }
  },
});

if (!googlePayResult.ok) {
  // Handle error setting up Google Pay
}

// You can update the quote or dispose the frame later
// googlePayResult.value.setQuote(newQuoteSignature);
// googlePayResult.value.dispose();
```

## Transaction statuses

Transactions have the following statuses:

* **Pending:** The transaction has been initiated and the payment accepted. The assets are being transferred.
* **Complete:** The transaction is finalized. The payment is complete and the assets have been delivered to their destination.
* **Failed:** The transaction has failed. The payment was not executed and funds were not transferred.


# Pay with widget
Source: https://dev.moonpay.com/platform/guides/pay-with-widget

Render the MoonPay buy widget to support all payment methods and regions.

Use this guide to render the MoonPay buy widget after you have a
[connected customer](/platform/guides/connect-a-customer). The widget renders
the full MoonPay buy experience — including payment-method selection
and transaction confirmation — inside an iframe in your application.
It supports all payment methods and regions available in the standard
MoonPay integration.

## Prerequisites

* A connected customer (via `client.getConnection()` or `client.connect()`).
* A UI surface where you can render the widget frame (for example, a
  modal or full-screen container).

## Get a quote

Request a quote for the transaction. The widget requires an executable
quote with a wallet address.

If you include a `paymentMethod` in the quote, the widget pre-selects
that method. If you omit it, the customer picks one inside the widget.

<CodeGroup>
  ```ts Get quote (pre-select payment method) theme={null}
  const quoteResult = await client.getQuote({
    source: "USD",
    destination: "ETH",
    sourceAmount: "100.00",
    walletAddress: "0x1234...",
    paymentMethod: "credit_debit_card", // Pre-selects credit/debit card
  });

  if (!quoteResult.ok) {
    // Handle error
  }
  ```

  ```ts Get quote (customer chooses) theme={null}
  const quoteResult = await client.getQuote({
    source: "USD",
    destination: "ETH",
    sourceAmount: "100.00",
    walletAddress: "0x1234...",
    // No paymentMethod — customer selects inside the widget
  });

  if (!quoteResult.ok) {
    // Handle error
  }
  ```
</CodeGroup>

<Callout icon="circle-info">
  Supported `paymentMethod` values include `credit_debit_card`, `google_pay`,
  `sepa_bank_transfer`, `gbp_bank_transfer`, `gbp_open_banking_payment`,
  `pix_instant_payment`, `interac`, `paypal`, `revolut_pay`, `venmo`, and
  `moonpay_balance`. If the pre-selected method is unavailable for the customer,
  the widget falls back to the payment selection screen. Passing `apple_pay`
  pre-selects the card form instead — use the [headless Apple Pay
  flow](/platform/guides/pay-with-apple-pay) for native Apple Pay.
</Callout>

## Render the widget

Pass the quote signature to `setupWidget`. The widget handles the
entire purchase flow inside the iframe.

```ts Widget theme={null}
import type { WidgetEvent } from "@moonpay/platform";

const widgetResult = await client.setupWidget({
  quote: quoteResult.value.signature,

  container: document.querySelector("#widgetContainer"),

  onEvent: (event: WidgetEvent) => {
    switch (event.kind) {
      case "ready":
        // The widget is loaded and visible.
        break;

      case "transactionCreated":
        // A transaction has been initiated. The customer may still
        // need to complete additional steps (for example, 3-D Secure).
        console.log(event.payload.transaction);
        // { id: "txn_01", status: "waitingAuthorization" }
        break;

      case "complete":
        // The transaction has reached a terminal state.
        console.log(event.payload.transaction);
        // { id: "txn_01", status: "pending" }
        break;

      case "error":
        console.error(event.payload.message);
        break;
    }
  },
});

if (!widgetResult.ok) {
  // Handle error setting up the widget
}

// Clean up when done
// widgetResult.value.dispose();
```

## Transaction statuses

* **waitingAuthorization:** The transaction has been created but the
  customer needs to complete an authorization step (for example,
  3-D Secure).
* **Pending:** The payment has been accepted and the assets are being
  transferred.
* **Complete:** The transaction is finalized and the assets have been
  delivered.
* **Failed:** The transaction has failed. No payment was applied.

## Choosing between Apple Pay and the widget

| Criteria        | Apple Pay                       | Widget                 |
| --------------- | ------------------------------- | ---------------------- |
| Payment methods | Apple Pay only                  | All supported methods  |
| UI control      | Headless — you own the UI       | MoonPay-hosted UI      |
| Regions         | Where Apple Pay is available    | All supported regions  |
| Best for        | Streamlined single-tap checkout | Broad payment coverage |

Both flows start from a connected customer and a quote. Use
`getPaymentMethods()` to determine which methods are available and
choose the flow that fits your experience.


# Configure frame appearance
Source: https://dev.moonpay.com/platform/guides/presentation-and-appearance

Control how co-branded frames look and behave in your app.

Use this guide to keep co-branded frames consistent with the rest of your UI.
Frames render MoonPay-hosted UI inside your app, so presentation choices affect
how the flow feels to customers.

## Prerequisites

* A [connected customer](/platform/guides/connect-a-customer).
* A container element in your UI where you render frames.

## Choose the right UI surface

* **Web**: Render co-branded frames in a modal or sheet and keep the rest of your UI visible behind it.
* **Mobile**: Present co-branded frames in a full-screen route or full sheet. This reduces layout issues when the frame navigates between steps.

## Control light and dark appearance

The [connect frame](/platform/frames/connect) supports a `theme` parameter. Use it to force `dark` or `light` instead of relying on the user's system appearance.

If you use the SDK, pass `theme` when you initialize the connect flow:

```ts Set appearance example highlight={6-8} theme={null}
import { createClient } from "@moonpay/platform";

const clientResult = createClient({ sessionToken: "..." });
const client = clientResult.value;

const connectResult = await client.connect({
  container: connectContainer,

  theme: {
    appearance: "dark", // Force dark mode
  },

  onEvent: (event) => {
    // Handle events
  },
});
```

If you build the connect frame URL manually, include `theme` in the query string:

```html Example URL theme={null}
https://blocks.moonpay.com/platform/v1/connect?sessionToken=c3N0XzAwMQ==&publicKey=...&channelId=ch_1&theme=dark
```

<Info>If you omit `theme`, the frame uses the user's system preference.</Info>

## Practical customization tips

* **Avoid resizing containers mid-flow**: Use a stable container size while the frame is mounted to prevent content jumps.
* **Show clear loading states**: If you wait for a frame’s `ready` event, keep your UI responsive and show a spinner/skeleton.
* **Plan for errors**: If a frame dispatches an `error` event, show a developer-friendly fallback (retry, exit, or contact support).

## Next steps

<Columns>
  <Card title="Frames overview" icon="book" href="/platform/frames/overview">
    Learn the shared messaging protocol for integrating without the SDK.
  </Card>

  <Card title="Connect frame reference" icon="file-code" href="/platform/frames/connect">
    See all initialization parameters including `theme`.
  </Card>
</Columns>


# Core concepts
Source: https://dev.moonpay.com/platform/overview/core-concepts

Key terms and concepts for integrating with the MoonPay Platform

## Connections

An active **connection** represents a customer's permission to associate the MoonPay account to your application so you can:

* List and manage payment methods in your UI
* Get quotes that include detailed fees and customer limits
* Execute payments (for example, Apple Pay or debit cards) without redirecting the customer
* View and track transaction history

<Callout icon="book">
  Read the [connect a customer guide](/platform/guides/connect-a-customer) for
  implementation details.
</Callout>

## Frames

The integration uses a combination of API calls and frames. For steps that have compliance or regulatory requirements, you render an embedded frame (a WebView in mobile apps and an iframe on the web). This keeps sensitive data out of your application while MoonPay manages compliance.

There are two types of frames: **co-branded** and **headless**. Both communicate with your app using `postMessage` (on web and mobile). Each frame has its own lifecycle events and message patterns, documented in the [frames overview](/platform/frames/overview). You can manage frames yourself, or use the SDK for drop-in frame setup and event handling.

### Co-branded frames

Co-branded frames render MoonPay-hosted UI that you can theme to match your application. They are designed for contextual rendering in modals or sheets. A typical example is the MoonPay login flow used when a customer connects their account.

<Frame>
  <img alt="MoonPay headless integration co-branded frame" />
</Frame>

### Headless frames

Headless frames are either invisible or display minimal, non-customizable elements such as an Apple Pay button. You can inline these frames wherever needed in your UI.

<Frame>
  <img alt="MoonPay headless integration frame" />
</Frame>

## Challenges

Challenges complete specific tasks that require upgraded authentication, identity verification, or connection updates. Common cases include:

* Authentication upgrades (required for sensitive or destructive actions)
* Identity verification (Know Your Customer, KYC)
* Strong Customer Authentication (SCA), such as [3D Secure](https://www.checkout.com/products/authentication-3ds), where the customer’s bank requires additional verification

Challenges are typically rendered in frames. When an API or SDK response requires a challenge, it includes instructions for rendering and completing it.

## Customer

A customer is a person using your app who can have a connected MoonPay account.

### KYC

When opening an account, MoonPay performs Know Your Customer (KYC) checks to meet financial compliance requirements and help prevent fraud and money laundering. By default, this happens in a themeable co-branded frame.

<Callout icon="arrow-left-arrow-right">
  <h4>
    KYC Sharing

    <Badge>
      Coming soon!
    </Badge>
  </h4>

  If you already capture KYC information using a provider like SumSub or Persona,
  you can use their sharing capabilities to simplify onboarding. You can
  also share MoonPay-verified KYC data with other services in your app, like
  setting up a debit card.
</Callout>

## Quotes

Quotes provide real-time prices and fees for fiat-to-crypto purchases. There are two types: **price quotes** and **executable quotes**.

<Callout icon="book">
  Check the [quotes API reference](/api-reference/platform/endpoints/quotes/get)
  for detailed usage.
</Callout>

### Price quotes

Price quotes help you estimate transaction costs before you show a confirmation step. They include general limits, and you can request them through the API without a connected customer.

### Executable quotes

Executable quotes provide detailed fees and limits for transactions. Getting an executable quote requires an active [connection](#connections).


# Going Live
Source: https://dev.moonpay.com/platform/overview/going-live

Acceptance criteria for going live with your integration.

<Warning>
  All requirements on this page are verified by MoonPay before going live.
</Warning>

## Overview

This page defines the acceptance criteria that apply to all MoonPay Platform
integrations. Meeting these requirements is a condition of going live. They
address usability, legal accuracy, and regulatory compliance.

MoonPay may update these criteria at any time. When changes are required,
MoonPay will provide reasonable written notice to allow time for
implementation.

### How to read this page

Each requirement is annotated with a **geo tag** identifying where the
customer must be located for the rule to apply:

<Tags />

Customer location is returned on the
[capabilities](/platform/guides/connect-a-customer#capabilities) object of an
active connection.

***

## Universal requirements

<Tags />

All information you present to the customer must be true, accurate, and not
misleading.

***

## Apple Pay

Applies when rendering the
[Apple Pay frame](/platform/guides/pay-with-apple-pay).

### Disclosures - US (New York and Washington)

<Tags />

Display the following exact text directly above the Apple Pay frame for
customers located in **NY or WA**:

<Frame>
  <img alt="Apple Pay with MoonPay Rails" />

  <img alt="Apple Pay with MoonPay Rails" />
</Frame>

<Accordion title="Raw text">
  I agree to MoonPay's <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and understand that, once executed, this transaction cannot be cancelled, recalled, refunded, or otherwise undone. Fraudulent transactions may result in the loss of funds with no recourse.
</Accordion>

<Accordion title="HTML">
  ```html wrap theme={null}
  I agree to MoonPay's
  <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and understand
  that, once executed, this transaction cannot be cancelled, recalled, refunded,
  or otherwise undone. Fraudulent transactions may result in the loss of funds
  with no recourse.
  ```
</Accordion>

### Disclosures - EEA

<Tags />

Display the following exact text directly above or below the payment frame for
customers located in the **EEA**. The verbiage depends on the crypto-asset
being transacted.

#### Standard crypto-assets

<Accordion title="Raw text">
  By continuing, you agree to transact with MoonPay Europe, subject to its <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>. Crypto-assets can be risky and values may decrease quickly. Transfers are irreversible once broadcast to the blockchain. The quoted exchange rate may include a spread. <a href="https://www.moonpay.com/legal">Learn more</a> and <a href="https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies">review the whitepaper</a> (if available).
</Accordion>

<Accordion title="HTML">
  ```html wrap theme={null}
  By continuing, you agree to transact with MoonPay Europe, subject to its
  <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and
  <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>.
  Crypto-assets can be risky and values may decrease quickly. Transfers are
  irreversible once broadcast to the blockchain. The quoted exchange rate may
  include a spread. <a href="https://www.moonpay.com/legal">Learn more</a> and
  <a href="https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies"
    >review the whitepaper</a
  >
  (if available).
  ```
</Accordion>

#### Non-MiCA-compliant stablecoins

Applies when the customer is transacting in a stablecoin that is not
MiCA-compliant (for example USDT, cUSD, DAI, PYUSD).

<Accordion title="Raw text">
  Important: You are about to transact in a stablecoin that is not MiCA-compliant, carries fewer safeguards, and may be difficult to sell. By continuing, you agree to transact with MoonPay Europe subject to its <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>. Transfers are irreversible once broadcast to the blockchain. The quoted exchange rate may include a spread. <a href="https://www.moonpay.com/legal">Learn more</a> and <a href="https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies">review the whitepaper</a> (if available).
</Accordion>

<Accordion title="HTML">
  ```html wrap theme={null}
  Important: You are about to transact in a stablecoin that is not MiCA-compliant,
  carries fewer safeguards, and may be difficult to sell. By continuing, you agree
  to transact with MoonPay Europe subject to its
  <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and
  <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>.
  Transfers are irreversible once broadcast to the blockchain. The quoted exchange
  rate may include a spread.
  <a href="https://www.moonpay.com/legal">Learn more</a> and
  <a href="https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies"
    >review the whitepaper</a
  >
  (if available).
  ```
</Accordion>

### Disclosure rendering rules

<Tags />

The disclosure must be visible without any interaction. It must not be hidden
behind expandable menus, tooltips, or secondary screens. The Terms of Use must
be a tappable link. The full text must be rendered without truncation.

### Fees

<Tags />

When using Apple Pay you don't need to display fees before a transaction - the
Apple Pay sheet shows them on the customer's device. The total amount displayed
to the customer must exactly match the amount charged via Apple Pay.

***

## Cards

Applies to card payment methods.

### Attribution

<Tags />

**"Powered by MoonPay"** must be displayed on the Buy screen.

### Required line items

<Tags />

You must display all fees and quoted amounts to the customer before the
transaction is completed. Every transaction quote must surface the following
line items in your UI:

| Line item                       | Description                                             |
| ------------------------------- | ------------------------------------------------------- |
| **You pay**                     | The total fiat amount charged to the customer           |
| **Network fee**                 | The on-chain gas fee                                    |
| **Ecosystem fee**               | Any fee applied by your platform                        |
| **MoonPay fee**                 | MoonPay's transaction fee                               |
| **Amount used to buy \[token]** | The fiat amount used for the crypto purchase after fees |
| **At the exchange rate**        | The fiat-to-crypto rate applied to the transaction      |
| **Total crypto you'll get**     | The crypto amount the customer will receive             |

### Waived fees

<Tags />

If any fee is waived, it must still appear in the UI with a displayed value of
**\$0.00**. Do not omit a line item because the fee is zero.

### Amount consistency

<Tags />

The total shown to the customer must exactly match the amount charged. Any
discrepancy between the quoted total and the final payment will block go-live
approval.

### Disclosures - EEA

<Tags />

Display the following exact text directly above or below the payment frame for
customers located in the **EEA**. The verbiage depends on the crypto-asset
being transacted.

#### Standard crypto-assets

<Accordion title="Raw text">
  By continuing, you agree to transact with MoonPay Europe, subject to its <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>. Crypto-assets can be risky and values may decrease quickly. Transfers are irreversible once broadcast to the blockchain. The quoted exchange rate may include a spread. <a href="https://www.moonpay.com/legal">Learn more</a> and <a href="https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies">review the whitepaper</a> (if available).
</Accordion>

<Accordion title="HTML">
  ```html wrap theme={null}
  By continuing, you agree to transact with MoonPay Europe, subject to its
  <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and
  <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>.
  Crypto-assets can be risky and values may decrease quickly. Transfers are
  irreversible once broadcast to the blockchain. The quoted exchange rate may
  include a spread. <a href="https://www.moonpay.com/legal">Learn more</a> and
  <a href="https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies"
    >review the whitepaper</a
  >
  (if available).
  ```
</Accordion>

#### Non-MiCA-compliant stablecoins

Applies when the customer is transacting in a stablecoin that is not
MiCA-compliant (for example USDT, cUSD, DAI, PYUSD).

<Accordion title="Raw text">
  Important: You are about to transact in a stablecoin that is not MiCA-compliant, carries fewer safeguards, and may be difficult to sell. By continuing, you agree to transact with MoonPay Europe subject to its <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>. Transfers are irreversible once broadcast to the blockchain. The quoted exchange rate may include a spread. <a href="https://www.moonpay.com/legal">Learn more</a> and <a href="https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies">review the whitepaper</a> (if available).
</Accordion>

<Accordion title="HTML">
  ```html wrap theme={null}
  Important: You are about to transact in a stablecoin that is not MiCA-compliant,
  carries fewer safeguards, and may be difficult to sell. By continuing, you agree
  to transact with MoonPay Europe subject to its
  <a href="https://www.moonpay.com/legal/terms">Terms of Use</a> and
  <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>.
  Transfers are irreversible once broadcast to the blockchain. The quoted exchange
  rate may include a spread.
  <a href="https://www.moonpay.com/legal">Learn more</a> and
  <a href="https://dev.moonpay.com/docs/list-of-supported-cryptocurrencies"
    >review the whitepaper</a
  >
  (if available).
  ```
</Accordion>

***

## Identity API

Applies when integrating the
[Identity API](/platform/guides/connect-a-customer) for KYC.

### Phone verification freshness

<Tags />

You must have verified the user's phone number within 30 days of the user
initiating the KYC flow. If verification falls outside the 30-day window, you
must re-verify the phone number before KYC can proceed.

Verification must use the **SMS** method.

### Persona consent

<Tags />

Before collecting identity information from the user, you must request explicit
consent by rendering the following exact verbiage:

<Accordion title="Raw text">
  By clicking \[Continue], you consent to Persona and its service providers collecting and processing your biometric data for identity verification and fraud prevention, per its Privacy Policy. Your biometric information will be stored up to 3 years.
</Accordion>

You must maintain a record evidencing each explicit acceptance, including a
timestamp, and provide this record to MoonPay in a timely manner upon request.

### Terms acceptance

<Tags />

This requirement only applies if you're integrating the Identity API. You
must satisfy the End User terms-acceptance requirement using **one** of the
two methods below, at your election.

#### Option A - Incorporation by reference

<Tags />

A consolidated acceptance flow in which the End User agrees to your terms of
service, which expressly incorporate the MoonPay Terms of Use by reference with
a conspicuous link to the full text and a list of key terms.

The following language must be included in your terms of service:

<Accordion title="Raw text">
  **MoonPay Services and Legal Framework**

  All regulated services, including but not limited to digital asset purchase and sale transactions, fiat currency payments, and related services, are provided exclusively by our partner, MoonPay. By using our platform for such services, you are engaging directly with MoonPay which will conduct such services under its applicable licenses and regulatory approvals. Accordingly, your use of these specific services is governed by MoonPay's Terms of Use.

  **Applicable Terms & Policies**

  By accessing these services, you agree to be bound by MoonPay's <a href="https://www.moonpay.com/legal/terms">Terms of Use</a>, <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>, and other applicable terms. We strongly encourage you to review these documents in full.
</Accordion>

<Accordion title="HTML">
  ```html wrap theme={null}
  <p><strong>MoonPay Services and Legal Framework</strong></p>
  <p>
    All regulated services, including but not limited to digital asset purchase
    and sale transactions, fiat currency payments, and related services, are
    provided exclusively by our partner, MoonPay. By using our platform for such
    services, you are engaging directly with MoonPay which will conduct such
    services under its applicable licenses and regulatory approvals. Accordingly,
    your use of these specific services is governed by MoonPay's Terms of Use.
  </p>
  <p><strong>Applicable Terms & Policies</strong></p>
  <p>
    By accessing these services, you agree to be bound by MoonPay's
    <a href="https://www.moonpay.com/legal/terms">Terms of Use</a>,
    <a href="https://www.moonpay.com/legal/privacy_policy">Privacy Policy</a>, and
    other applicable terms. We strongly encourage you to review these documents in
    full.
  </p>
  ```
</Accordion>

#### Option B - Simultaneous acceptance

<Tags />

A single-step acceptance in which the End User is presented with both your
terms and the MoonPay Terms of Use for simultaneous acceptance.

MoonPay's then-current
[Terms of Use](https://www.moonpay.com/legal/terms) must be embedded alongside
your own terms (or equivalent agreement). They may be presented on the same
page, modal, or interface, before or after your terms, provided it is clearly
distinguishable where your terms end and MoonPay's begin (and vice versa).

MoonPay's terms must be displayed in full, without modification or omission.

#### Presentation and record-keeping

<Tags />

* The terms must be presented to the End User prior to their first transaction,
  and again whenever either MoonPay's terms or your terms are materially
  updated.
* You must maintain a record evidencing each explicit acceptance of the terms
  by the End User, including a timestamp, and provide this record to MoonPay
  upon request.


# Introduction
Source: https://dev.moonpay.com/platform/overview/introduction

Build fiat->crypto experiences with headless payments. You control the user experience while MoonPay handles compliance, risk, and fraud.

<Frame>
  <img alt="MoonPay" />

  <img alt="MoonPay" />
</Frame>

## Welcome to the MoonPay Platform

Use the MoonPay Platform APIs, SDKs, and frames to build crypto ramps directly in your app. Before you start, review the [requirements](/platform/overview/requirements) and [core concepts](/platform/overview/core-concepts).

## Getting started

<Columns>
  <Card title="Connect a customer" icon="arrow-down-left-and-arrow-up-right-to-center" href="/platform/guides/connect-a-customer">
    Connect a customer’s MoonPay account so you can list payment methods, get
    quotes, and execute transactions.
  </Card>

  <Card title="Execute a transaction" icon="money-bill-transfer" href="/platform/guides/pay-with-apple-pay">
    Set up a payment method (like Apple Pay) and execute a transaction in your
    UI.
  </Card>

  <Card title="Frames" icon="file-code" href="/platform/frames/overview">
    Embed headless and co-branded UI in your app.
  </Card>

  <Card title="API reference" icon="book" href="/api-reference/platform">
    Explore the Platform API endpoints and parameters.
  </Card>
</Columns>

## Quickstart

<Steps>
  <Step title={<><Icon icon="server" /> Get a session token</>}>
    Create a [session token](/api-reference/platform/endpoints/sessions/create) on your server and send the token to your frontend.

    <CodeGroup>
      ```ts Create session token theme={null}
      // Server-side code example
      const url = "https://api.moonpay.com/platform/v1/sessions";

      const res = await fetch(url, {
        headers: {
          "Content-Type": "application/json",
          "X-Api-Key": "sk_test_123",
        },
        method: "POST",
        body: JSON.stringify({
          externalCustomerId: "your_user_id",
          deviceIp: "...ip address from client",
        }),
      });

      console.log(await res.json());
      ```

      ```json Result theme={null}
      {
        "sessionToken": "c3N0XzAwMQ=="
      }
      ```
    </CodeGroup>
  </Step>

  <Step title={<><Icon icon="mobile-notch" /> Connect a customer</>}>
    On your frontend, check whether the customer has an active connection. If they do, you receive credentials for the next steps.

    <CodeGroup>
      ```ts Check the connection theme={null}
      import { createClient } from "@moonpay/platform";

      // Create the client with your session token
      const clientResult = createClient({
        sessionToken: "c3N0XzAwMQ==", // The session token from your server
      });

      if (!clientResult.ok) {
        // Handle error creating client
      }

      const client = clientResult.value;

      // Check if the customer has an active connection
      const connectionResult = await client.getConnection();

      if (!connectionResult.ok) {
        // Handle error
      }

      console.log(connectionResult.value);
      ```

      ```ts Result (active) theme={null}
      {
        status: "active",
        customer: {
          id: "Y3VzX2FiYzEyMw=="
        },
        credentials: {
          accessToken: "c2F0XzAwMQ==",
          clientToken: "c2N0XzAwMQ=="
        }
      }
      ```

      ```ts Result (requires connection) theme={null}
      {
        status: "connectionRequired",
        credentials: {
          accessToken: "c2F0XzAwMQ==",
          clientToken: "c2N0XzAwMQ=="
        }
      }
      ```
    </CodeGroup>
  </Step>

  <Step title={<><Icon icon="mobile-notch" /> List payment methods</>}>
    List the payment methods available to the customer at the current time.

    ```ts List payment methods theme={null}
    // After connecting, list available payment methods
    const paymentMethodsResult = await client.getPaymentMethods();

    if (!paymentMethodsResult.ok) {
      // Handle error
    }

    console.log(paymentMethodsResult.value);
    // [{ type: "apple_pay", capabilities: {...}, availability: {...} }, ...]
    ```
  </Step>

  <Step title={<><Icon icon="mobile-notch" /> Get quotes</>}>
    Get [quotes](/platform/overview/core-concepts#executable-quotes) with detailed fees and limits for transactions.

    ```ts Get quotes theme={null}
    const quoteResult = await client.getQuote({
      source: "USD",           // The fiat currency for payment
      destination: "ETH",      // The crypto the customer will receive
      sourceAmount: "100.00",  // The amount to purchase
      walletAddress: "0x...",  // The destination wallet address
      paymentMethod: "apple_pay",
    });

    if (!quoteResult.ok) {
      // Handle error
    }

    console.log(quoteResult.value);
    // { signature: "...", expiresAt: "2026-01-12T14:45:00Z", ... }
    ```
  </Step>

  <Step title={<><Icon icon="mobile-notch" /> Execute headless payments</>}>
    Once you have a quote, [execute the transaction](/platform/guides/pay-with-apple-pay).

    ```ts Pay with Apple Pay theme={null}
    import type { ApplePayEvent } from "@moonpay/platform";

    const paymentButtonContainer = document.querySelector("#payment");

    const setupApplePayResult = await client.setupApplePay({
      quote: quoteResult.value.signature, // The quote signature
      container: paymentButtonContainer,

      onEvent: (event: ApplePayEvent) => {
        switch (event.kind) {
          case "ready":
            // Reveal the button
            paymentButtonContainer.style.opacity = "1";
            break;

          case "complete":
            // The transaction is executing. Use polling and/or webhooks to track final status.
            console.log(event.payload.transaction);
            // { id: "txn_01", status: "pending" }
            break;

          case "quoteExpired":
            // Fetch a new quote and update the frame
            // event.payload.setQuote(newQuote.signature);
            break;
        }
      },
    });

    if (!setupApplePayResult.ok) {
      // Handle error
    }
    ```
  </Step>
</Steps>


# Requirements
Source: https://dev.moonpay.com/platform/overview/requirements

Requirements for the headless ramp integration.

To integrate the headless ramp, you will need:

* A partner account and API credentials
* A frontend (web or mobile) app
* If you're using the SDK, ensure it's installed
* A server for sending requests to MoonPay and receiving webhooks

<Callout icon="key">
  During the preview, we will work with you directly to set up your account and
  credentials.
</Callout>

## Integrating on the web

### Content Security Policy

If you embed MoonPay frames on the web, your Content Security Policy (CSP) must allow MoonPay’s iframes and network calls.

Your [CSP](https://developer.mozilla.org/en-US/docs/Glossary/CSP) should include at least the following rules:

* [frame-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/frame-src)
* [connect-src](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/connect-src)

```sh theme={null}
Content-Security-Policy: frame-src https://*.moonpay.com/; connect-src https://*.moonpay.com/;
```

## Configuration

### Domain settings

When integrating MoonPay on the web, provide your app’s [origin](https://developer.mozilla.org/en-US/docs/Web/API/URL/origin) per environment. This allows MoonPay to embed frames securely.

### Apple Pay

To use Apple Pay on the web, you must complete Apple’s domain verification to prove ownership of your site. This is currently a manual process.

## Integrating in mobile apps

### WebViews

This integration supports using [WKWebView](https://developer.apple.com/documentation/webkit/wkwebview) on iOS and [WebView](https://developer.android.com/reference/android/webkit/WebView) on Android.

When using `WKWebview` on iOS you will need to set [`allowsInlineMediaPlayback`](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/allowsinlinemediaplayback) to `true` for the [Connect frame](/platform/frames/connect).


# Test mode
Source: https://dev.moonpay.com/platform/overview/test-mode

Use test mode to develop and test your integration without transferring real assets.

MoonPay provides a test mode for integration development and testing. Test mode uses testnet blockchains and simulated payments. No real assets are transferred.

## Enabling test mode

Test mode is determined by the API key you use when [creating a session](/api-reference/platform/endpoints/sessions/create). Use your **test API key** (`sk_test_...`) to enable test mode. Use your **live API key** (`sk_live_...`) for production.

You can find your API keys on the [Developers page](https://dashboard.moonpay.com/developers) in your MoonPay dashboard.

<Info>
  All frames and SDK methods automatically operate in test mode when initialized
  with a session token created using test API keys.
</Info>

## Test accounts

When creating test accounts:

* **KYC verification is simulated** - documents are not verified
* **We recommend using a US or UK address** for test accounts, as these work best with test payment cards
* You can skip document submission by clicking "Skip document submission" if prompted

## Test data

### Email addresses

You must use a real email address that you can access. MoonPay sends OTP codes for login verification, and there are no test bypass values.

<Note>You cannot reuse the same email address for different customers.</Note>

**Tip:** Use the `+` suffix pattern to create multiple unique addresses from a single inbox: `you+test1@example.com`, `you+test2@example.com`, etc.

### Phone numbers

You must use a real phone number that you can access. MoonPay sends OTP codes for verification, and there are no test bypass values.

<Note>
  A phone number can only be associated with one customer at a time. If you
  verify with the same phone number on a different customer, it will be removed
  from the previous customer.
</Note>

### SSN (US residents)

SSN values are not verified in test mode. You can enter any 9-digit value.

<Warning>
  Do not use your real Social Security number. Use a fake value like
  `123456789`.
</Warning>

## Test payment cards

Use the following test cards to simulate payments. **Do not enter real payment card information.** Use any valid 3-digit CVV (or 4-digit for Amex) and any future expiration date.

### US customers

| Card type         | Card number           | Expiration | CVV    |
| :---------------- | :-------------------- | :--------- | :----- |
| Visa Credit       | `4000 0200 0000 0000` | `12/2030`  | `100`  |
| Mastercard Credit | `5436 0310 3060 6378` | `12/2030`  | `100`  |
| Amex Credit       | `3456 7890 1234 564`  | `12/2030`  | `1000` |

### UK customers

| Card type        | Card number           | Expiration | CVV   |
| :--------------- | :-------------------- | :--------- | :---- |
| Visa Credit      | `4242 4242 4242 4242` | `12/2030`  | `100` |
| Visa Debit       | `4659 1055 6905 1157` | `12/2030`  | `100` |
| Mastercard Debit | `5305 4847 4880 0098` | `12/2030`  | `100` |

### EU customers

| Card type             | Card number           | Expiration | CVV    |
| :-------------------- | :-------------------- | :--------- | :----- |
| Visa Debit (FR)       | `4010 0617 0000 0021` | `12/2030`  | `100`  |
| Mastercard Debit (DE) | `5305 4847 4880 0098` | `12/2030`  | `100`  |
| Amex Credit (ES)      | `3456 7890 1234 564`  | `12/2030`  | `1000` |

### Declined transactions

Use these cards to test error handling for different failure scenarios.

| Card number           | Expiration | CVV   | Decline reason           |
| :-------------------- | :--------- | :---- | :----------------------- |
| `4544 2491 6767 3670` | `12/2030`  | `100` | Insufficient funds       |
| `4897 4535 6848 5113` | `12/2030`  | `100` | Suspected fraud          |
| `4818 9242 5013 1070` | `12/2030`  | `100` | Restricted card          |
| `4556 2537 5271 2245` | `12/2030`  | `100` | Security violation       |
| `4095 2548 0264 2505` | `12/2030`  | `100` | Timeout / Internal error |
| `5437 8211 3539 9682` | `12/2030`  | `100` | Insufficient funds       |
| `5279 9884 0539 8834` | `12/2030`  | `100` | Restricted card          |
| `5265 1622 7058 7964` | `12/2030`  | `100` | Timeout / Internal error |
| `5363 4501 8040 2239` | `12/2030`  | `100` | Lost card                |

## Apple Pay

In test mode, the Apple Pay frame renders a mock Apple Pay button instead of the native Apple Pay UI. When a customer taps the mock button, a browser confirmation dialog (`window.confirm`) appears in place of the Apple Pay payment sheet:

* **Ok** simulates a successful transaction.
* **Cancel** simulates a failed transaction.

This lets you test the full Apple Pay flow without a real Apple Pay account or Safari-specific setup.

<Note>
  If you embed the Apple Pay frame in an iframe with a `sandbox` attribute,
  include `allow-modals` in the sandbox value. This allows `window.confirm` to
  work cross-origin inside the frame. See the [Apple Pay frame
  reference](/platform/frames/apple-pay#permissions) for details.
</Note>

## Supported testnets

Test mode supports the following tokens and testnets:

| Token         | Testnet  |
| :------------ | :------- |
| Bitcoin       | Testnet3 |
| Ethereum      | Sepolia  |
| ERC-20 tokens | Sepolia  |
| Solana        | Testnet  |
| Binance Coin  | Testnet  |
| TON           | Testnet  |
| Stellar       | Testnet  |
| Litecoin      | Testnet  |

<Note>
  ERC-20 token transfers in test mode use MoonPay's test token contract.
</Note>

## Troubleshooting

### Common errors

| Error                                                                 | Cause                                               | Solution                                                                                            |
| :-------------------------------------------------------------------- | :-------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |
| `Framing 'https://blocks.moonpay.com' violates "frame-ancestors" CSP` | Your app or website domain has not been allowlisted | Add domains at [https://dashboard.moonpay.com/developers](https://dashboard.moonpay.com/developers) |


# Using agents
Source: https://dev.moonpay.com/platform/overview/using-agents

Connect AI coding agents to the MoonPay Platform documentation using MCP, llms.txt, and contextual code actions.

AI coding agents can search and reference the MoonPay Platform documentation
directly from your development environment. The docs provide four integration
points: an MCP server for real-time search, agent skills for structured
capabilities, `llms.txt` files for bulk context, and contextual code actions on
every code block.

## MCP server

The documentation includes a
[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that
gives AI agents direct access to search and retrieve content. Instead of relying
on web search, your agent queries the documentation index for accurate,
up-to-date results.

The server URL is:

```bash MCP server URL theme={null}
https://dev.moonpay.com/mcp
```

### Connect your client

<Tabs>
  <Tab title="Claude Code">
    Run the following command to add the MCP server to Claude Code:

    ```bash Add MCP server theme={null}
    claude mcp add --transport http moonpay-docs https://dev.moonpay.com/mcp
    ```

    By default this adds the server to your local scope. Use `--scope project`
    to share the configuration with your team via `.mcp.json`, or
    `--scope user` to make it available across all your projects.
  </Tab>

  <Tab title="Cursor">
    Add the MCP server to your project's `.cursor/mcp.json` file, or open
    **Settings → Cursor Settings → MCP** and add a new server:

    ```json .cursor/mcp.json theme={null}
    {
      "mcpServers": {
        "moonpay-docs": {
          "url": "https://dev.moonpay.com/mcp"
        }
      }
    }
    ```

    Restart Cursor after adding the server.
  </Tab>

  <Tab title="Claude Desktop">
    Add the following to your Claude Desktop configuration file
    (`claude_desktop_config.json`). On macOS, this file is at
    `~/Library/Application Support/Claude/claude_desktop_config.json`. On
    Windows, it is at `%APPDATA%\Claude\claude_desktop_config.json`.

    ```json claude_desktop_config.json theme={null}
    {
      "mcpServers": {
        "moonpay-docs": {
          "url": "https://dev.moonpay.com/mcp"
        }
      }
    }
    ```

    Restart Claude Desktop after saving the file.
  </Tab>

  <Tab title="Codex">
    Add the following to your Codex configuration file at
    `~/.codex/config.toml`, or to a project-scoped `.codex/config.toml`:

    ```toml config.toml theme={null}
    [mcp_servers.moonpay-docs]
    url = "https://dev.moonpay.com/mcp"
    ```

    You can also add it with the CLI:

    ```bash Add MCP server theme={null}
    codex mcp add moonpay-docs https://dev.moonpay.com/mcp
    ```
  </Tab>

  <Tab title="Other clients">
    Any MCP-compatible client can connect using the server URL above. Refer to
    your client's documentation for setup instructions.
  </Tab>
</Tabs>

## Skills

The documentation publishes a
[`SKILL.md`](https://agentskills.io/) file that describes MoonPay Platform
capabilities in a structured, machine-readable format. Unlike the MCP server,
which responds to individual queries, `SKILL.md` gives an agent a complete
picture of available workflows, required inputs, and constraints up front.

View the generated file at
[`dev.moonpay.com/SKILL.md`](https://dev.moonpay.com/SKILL.md).

### Install skills

Run the following command to add MoonPay Platform skills to your agent's
context:

<CodeGroup>
  ```bash npx theme={null}
  npx skills add https://dev.moonpay.com
  ```

  ```bash bunx theme={null}
  bunx skills add https://dev.moonpay.com
  ```

  ```bash pnpm dlx theme={null}
  pnpm dlx skills add https://dev.moonpay.com
  ```
</CodeGroup>

The skills CLI discovers and installs the `skill.md` file automatically. Once
installed, your agent can reference MoonPay Platform capabilities without
additional configuration.

## Contextual code actions

Code blocks throughout these docs include contextual actions for sending code
directly to an AI tool. Hover over any code block to see options for Cursor,
Claude, and ChatGPT. Each option copies the code along with surrounding
documentation context so the AI tool understands how to use it.

## llms.txt

The documentation provides
[`llms.txt`](https://llmstxt.org/) files for direct content
ingestion by large language models:

| File                                                     | Description                                                    |
| :------------------------------------------------------- | :------------------------------------------------------------- |
| [`llms.txt`](https://dev.moonpay.com/llms.txt)           | A concise summary of the documentation structure and key pages |
| [`llms-full.txt`](https://dev.moonpay.com/llms-full.txt) | The complete documentation content for full-context indexing   |

Use these files to give an AI tool broad context about the MoonPay Platform
without connecting to the MCP server. You can paste the contents into a chat
session or point a tool at the URL directly.


# Overview
Source: https://dev.moonpay.com/widget/advantages-of-our-products

MoonPay is the top payment infrastructure solution for cryptocurrencies that provides a seamless bridge between traditional financial systems and the new world of cryptocurrencies. Developers who are building on Web3 (a vision for a decentralized internet where users control their data and interactions) can greatly benefit from integrating with the MoonPay API and SDKs for a few key reasons:

**Web3 leader**: MoonPay is the leading ramps provider in the space and continues to be the most popular choice for crypto and NFT applications across the world.

**Highest conversion**: Millions of users have brought crypto using MoonPay before and so have their payment information and kyc details pre-saved, resulting in the highest possible conversions.

**Easy access to cryptocurrencies**: MoonPay makes it easy for users to buy cryptocurrencies using traditional payment methods like credit cards, bank transfers, and mobile money. This can help increase the accessibility and usability of Web3 applications.

**Broad range of supported cryptocurrencies**: MoonPay supports a wide range of cryptocurrencies, which means that users of your Web3 app will have more choices and flexibility.

**Broad range of supported payment methods**: MoonPay supports a wide range of payment methods on `Buy` and `Sell` : credit and debit cards, EUR, GBP, USD bank transfers, PayPal, Venmo, Revolut as well as Apple & Google Pay so your users can complete their transactions in any way they want.

**Global coverage**: MoonPay operates in many countries worldwide, making it a good choice for applications with a global user base.

**Security and compliance**: MoonPay adheres to high standards of security and regulatory compliance. This can give users of your Web3 application peace of mind when it comes to financial transactions.

**Easy integration**: MoonPay provides a well-documented [API](/api-reference/widget) and various SDKs, making it straightforward for developers to integrate their services into Web3 applications.

**Support for NFTs**: MoonPay has been expanding its services to support NFT marketplaces. This opens up even more possibilities for developers building in the Web3 space.

***

[Integration examples](/widget/integration-examples)


# Widget theming
Source: https://dev.moonpay.com/widget/customize-the-widgets-appearance

Enhance your website or applications user experience by tailoring the MoonPay widget's appearance to align with your brand. These personalization options are referred to as a .

## Building your theme

Your website or application can feature a unique theme that includes a dedicated theme.

You can build your theme using [MoonPay dashboard theme builder](https://dashboard.moonpay.com/theme). Themes built on the MoonPay dashboard are tied to your API key and will show up wherever you use your API key (e.g. widget, transaction tracker).

<Frame>
  <img alt="Theming" />
</Frame>

## Implementing your theme

To apply your custom theme, simply set your newly created theme to the default and save the changes.

This will ensure that the widget or transaction tracker is initialized with the corresponding theme whenever you use your MoonPay API key.

## Examples

<Frame>
  <img alt="Mobile" />
</Frame>

<Frame>
  <img alt="Desktop" />
</Frame>

## Available personalizations

* **Brand logos**. Please contact your MoonPay team and include:
  * 1 rectangular logo for transactional emails

* **Color choices** accommodating both light and dark preferences.
  * Widget Background Color
  * Primary Button Color

* **Custom Loader** - for a simple approach to customizing the loader that your MoonPay widget displays, you can use the dashboard:
  1. Go to the B2B dashboard
  2. Navigate to "Theme" → "Loader"
  3. Choose your preferred loader type (MoonPay default or generic spinner)
  4. Select custom colors to match your brand
  5. Save changes

## Usage of `theme`

You can manually choose light or dark modes using the`theme` widget parameter. e.g. `theme=dark` or `theme=light`


# Integration design guide
Source: https://dev.moonpay.com/widget/design-your-integration

Build your integration with the MoonPay Standard—proven insights from top-performing partner integrations that drive revenue and usability.

## Go-live requirements

<Info>
  To receive your production API keys, the following integration requirements
  must be met.
</Info>

* **Multiple entry points** — Buy buttons in home screen, main app navigation, and individual cryptocurrency screens. See [Buy button placement](#buy-button-placement).
* **Amount input** — Pre-fill fiat/crypto amount using `currencyCode` with `baseCurrencyAmount` or `quoteCurrencyAmount`; show minimum and maximum buy limits. See [Amount input screen](#amount-input-screen) and [Minimum and maximum buy limits](#minimum-and-maximum-buy-limits).
* **Payment method selection screen** — Show all supported payment methods, payment method logos, estimated transaction completion times, and default to Apple Pay on iOS. See [Payment method selection](#payment-method-selection) and [Supported payment methods](/api-reference/widget).
* **Provider selection screen** — Show [`ID verified` badges](#id-verified-and-previously-used-badges) for returning users, quotes from `/buy_quote` using `paymentMethod`, and estimated completion times. See [Provider selection](#provider-selection).
* **Pre-fill the customer's email address** — Pre-fill via the `email` parameter to skip the widget login screen. See [Pre-fill the customer's email address](#pre-fill-the-customers-email-address).
* **Pre-fill the customer's wallet address(es)** — Pass `walletAddress` or `walletAddresses` (with `currencyCode` or `defaultCurrencyCode` when using the singular form), and [sign URLs with your secret key](/widget/on-ramp-enhance-security-using-signed-urls). See [Pre-fill the customer's wallet addresses in the widget](#pre-fill-the-customers-wallet-address).
* **Transaction tracking** — Display a toast after the user completes their transaction with a link to the MoonPay transaction tracker, or to your own history page. See [Track the order status](#track-the-order-status).
* **Mobile app configuration** — Use a fullscreen in-app browser without a nav bar, allow KYC, and allow pop-ups at the browser level. See [Mobile integrations](#mobile-integrations).

## User journey demo

Explore the demo below for an end-to-end showcase of a well-designed on-ramp integration with a wallet partner.

<iframe title="Figma" />

## Implementation details

### Buy button placement

All partner apps must show buy buttons in the following:

* [ ] Home screen
* [ ] Main app navigation
* [ ] Cryptocurrency-specific screens

Highly visible Buy buttons in these areas reduces the number of clicks for users to transact and improves the user experience. You should also Buy buttons wherever users expect to be able to transact, like their wallet, NFT purchase sections, trading screens, and other screens specific to your app.

<Check>
  **Impact**: A minimum 2x increase in transaction volume based on data from a basket of partners including Uniswap.
</Check>

<Frame>
  <img alt="Buy button" />
</Frame>

#### Currency selector

When a user clicks on the Buy button, it should be easy to find crypto to purchase:

* List all cryptocurrencies available for purchase through your MoonPay integration
* Include a search bar and filters for ease of use
* Show the currency icon, abbreviation, full name, and network of each token so users can easily browse the list. Cryptocurrency and Fiat asset images can be found by accessing our [v3/currencies API](/api-reference/widget/getcurrencies).

<Frame>
  <img alt="Currency selection" />
</Frame>

### Amount input screen

A dedicated screen in your app for the user to select the amount, crypto, and fiat for their transaction provides a more seamless experience with the MoonPay widget.

For partner apps that have an amount input screen, use the following design elements for ease of use:

* When opening the MoonPay widget, pass the widget parameters`currencyCode` with`baseCurrencyAmount` or `quoteCurrencyAmount`to pre-fill the fiat or crypto amount.
* Allow users to change which crypto they're purchasing on this screen without leaving the flow
* [Validate minimum and maximum buy amounts](/widget/design-your-integration#minimum-and-maximum-buy-limits) against our Limits endpoint

<Frame>
  <img alt="Inputs" />
</Frame>

### Minimum and maximum buy limits

For partner apps that have an amount input screen, ensure a seamless user experience between your app and the MoonPay widget by checking entered amounts against our [GET v3/currencies/:currencyCode/limits](/api-reference/widget/getcurrencylimits) endpoint. Please note that the quote provided in this endpoint represents a platform-wide floor value, not a user-specific value. Widget errors caused by invalid amounts will require the user to re-enter the amount to buy, which adds another step and impacts the user experience.

<Check>
  **Impact**

  * Partners that offer transactions over \$10K see a 45% higher median for completed transaction volume.
  * Partners also see 3% of their total completed volume from transactions over \$10K.
</Check>

<Frame>
  <img alt="Amount screen" />
</Frame>

### Payment method selection

For partner apps with a payment method selection screen:

* Show [all payment methods supported by MoonPay](https://support.moonpay.com/customers/docs/all-supported-payment-methods), depending on the user's region and currency
  * All available payment methods per transaction type, region, and fiat currency can be surfaced using the [`/payment_method_config` endpoint](/api-reference/widget)

* Show payment method details that are returned in the `/payment_method_config` response
  * Use payment method logos
  * Show estimated transaction completion times

* Default to Apple Pay on iOS, as Apple Pay typically has higher transaction success rates

* Pre-fill the `?paymentMethod` widget param with the selected payment method

A payment method selection screen in your app lets your customers easily choose how they want to transact while also getting more accurate quotes. If your app has a payment method selector, it's highly recommended to use the [`/payment_method_config` endpoint](/api-reference/widget) to surface all available payment methods. Otherwise, you'll need to periodically update your app as we release new payment methods:

* Update `?paymentMethod` when calling the `/buy_quote` endpoint and showing the widget
* Add the new payment method as an option in your app, including the logo, estimated transaction completion times
* Any other payment method-specific requirements

### Provider selection

For partner apps that offer ramps providers other than MoonPay, display key context on a provider selection screen, including:

* `ID verified` [badge for users who have completed KYC](/widget/moonpay-conversion-badges)
* Quotes from our[`/buy_quote` endpoint](/api-reference/widget) using `paymentMethod`
* Supported payment methods and their logos

### ID verified and previously used badges

`ID verified` and `Previously used` badges ensure a frictionless experience for returning users by indicating that their KYC has been completed. Our data show that returning users can be less price-sensitive than new users, preferring a more convenient checkout experience with fewer steps. This is crucial even if MoonPay is your exclusive provider, as displaying a previously used badge helps remind and reassure users.

Call our [GET /v3/customers/badges endpoint](/widget/moonpay-conversion-badges) with the customer's wallet address and we will return the customer's KYC status which you can use to show the `ID verified` badge.

<Check>
  **Impact**

  * User retention rates are 70% higher when they know they've transacted before.
  * 30% of wallet address that get passed to our Badges endpoint are already KYC'd.
</Check>

<Frame>
  <img alt="Previously used" />
</Frame>

### Payment method logos

Build customer trust by displaying the supported payment and payout method logos for your integration. For customers new to crypto, these familiar payment methods indicate a safe checkout process.

[Download these logos as a ZIP file](https://drive.google.com/uc?export=download\&id=1Z26OICqzkzDusYpNUyQNcJm__HOWsGNZ) and review the supported payment / payout methods below:

* [On-ramp payment methods](https://support.moonpay.com/hc/en-gb/articles/360017624078-What-are-your-supported-payment-methods-)
* [Off-ramp payout methods](https://support.moonpay.com/hc/en-gb/articles/360013743077-Which-bank-accounts-are-supported-for-withdrawals-)
* [Checkout payment methods](https://support.moonpay.com/hc/en-gb/articles/4412759522705)

<Frame>
  <img alt="Provider selection screen" />
</Frame>

### Loading screen

Use logos to guide the user when redirecting the user to MoonPay. Before opening the MoonPay widget, show a loading screen with both your logo and MoonPay’s logo to build user trust and set expectations about the user journey.

Additionally, you can use the MoonPay dashboard to create a **custom loader** for your widget:

* Go to the B2B dashboard
* Navigate to "Theme" → "Loader"
* Choose your preferred loader type (MoonPay default or generic spinner)
* Select custom colors to match your brand
* Save changes

<Frame>
  <img alt="Provider selection screen" />
</Frame>

### Skip the amount screen

By default, the first screen in the MoonPay widget asks the user to confirm the amount of crypto to purchase. If your app has an amount input screen, you can skip the amount screen in the MoonPay widget for a more seamless end-to-end customer journey and increase conversions by 6%.

Pass the following [widget parameters](/widget/ramps-sdk-buy-params):

* `currencyCode`
* `baseCurrencyCode`
* `baseCurrencyAmount`
* `walletAddress`
* `signature`

<Check>
  **Impact**: Skipping the initial amount screen increases conversions by 6%.
</Check>

### Login options

#### Pre-fill the customer's email address

Partner apps that know the user's email address must pre-fill the customer's email address by passing the [`email` widget parameter](/widget/ramps-sdk-buy-params), so the customer won't be prompted to enter one. The widget will skip to the MFA code screen.

Returning customers that are logged in are 5% more likely to complete a transaction than returning customers that are not logged in. By pre-filling the customer's email address, you can capture some of this shortfall and increase transaction volume.

<Check>
  **Impact**

  * Returning customers that are logged in are 5% more likely to complete a transaction.
  * For new users who haven't transacted before, this is even higher at 25% more likely to complete their first transaction.
</Check>

#### Pre-fill the customer's wallet address

Partner apps that know the user's wallet address(es) must use the walletAddress or walletAddresses parameters to skip the wallet address screen in the buy flow.

<Check>
  **Impact**

  * Pre-selecting the currency, transaction amounts and wallet address to skip the initial screen of the widget increases conversions by 6%.
  * Users who have to manually enter the wallet address results in 5% reduction in overall transactions created.
</Check>

When using the walletAddress parameter, you must also:

* Pass currencyCode or baseCurrencyCode and
* [Sign URLs server-side](/widget/on-ramp-enhance-security-using-signed-urls)

You can alternatively use the walletAddresses parameter to pass multiple wallet addresses with their corresponding chains. The user will be able to choose from a filtered list of cryptocurrencies limited to those you pass in the parameter, and the wallet address screen will also be skipped.

#### Pre-select the payment method

Use the `paymentMethod` parameter to pre-select the user's payment method and match what they chose in the partner app.

### Track the order status

All partner apps must provide some kind of transaction tracking, whether a toast message that links to the MoonPay transaction tracker or your app's own transaction history screen.

After a user completes the buy flow in the MoonPay widget, it's crucial for them to be able to monitor their order's progress and understand its status. Increased transparency results in greater user trust and returning users who are 13% more likely to return and complete another transaction.

<Check>
  **Impact:** Increased transparency results in greater user trust and returning users who are 13% more likely to complete another transaction.
</Check>

MoonPay facilitates this through the use of webhooks and APIs. Webhooks provide real-time order updates to a specified endpoint of your choice, while the API allows for on-demand retrieval of the latest order status.

Both our [webhooks](/api-reference/widget/webhooks/buy) and [API](/api-reference/widget/getbuytransactions) offer consistent data, giving you the flexibility to employ either or both methods as per your requirements.

1. **Transaction tracking toast message**: After a user completes a transaction, show a toast message that persists until the crypto has been received in the user's wallet. When clicked, either the MoonPay transaction tracker or your app's transaction history page should open.

   * Partners not able to use webhooks for this toast message should implement a transaction history screen and use API calls to retrieve transaction data on-demand.

   <Frame>
     <img placeholder="Transaction tracking" />
   </Frame>

2. **Use the MoonPay transaction tracker**: We return the transaction tracker URL in our webhooks and API in the `data.returnURL` object. **Example tracker URL**: `https://buy.moonpay.com/transaction_receipt?transactionId=45751523-c3e2-47a5-ad0f-e5cb89e94037`. You can optionally pass the `apiKey` parameter to enable your custom theme on the tracker.

   <Frame>
     <img alt="Transaction tracking" />
   </Frame>

3. **Use your own transaction tracker**: You can optionally create your own transaction tracking screen that shows transaction data from our API and webhooks. We recommend that partners use the `redirectURL` parameter to route users to your destination URL (HTTPS or Universal/App Link) instead of the default MoonPay order status screen. Custom-scheme links (e.g., myapp\://…) are not supported. To enable automatic redirection for users, please contact your MoonPay representative.

   <Frame>
     <img alt="Transaction tracking" />
   </Frame>

   <Frame>
     <img alt="Transaction tracking" />
   </Frame>

#### API and webhook objects for transaction tracking

Additional examples and details for all parameters can be found in our transaction [API documentation](/api-reference/widget/getbuytransaction) under the *200 Responses* section.

| Object                              | Description                                                                                                                                                               | Notes                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `cryptoTransactionId`               | On-chain transaction hash that can be searched on the corresponding blockchain explorer                                                                                   |                                          |
| `status` and `failureReason`        | Order status and failure reason. Failure reason will be set only if the transaction status is `failed`.                                                                   | [Possible values](/api-reference/widget) |
| `stages` and `stages.failureReason` | Order stage and failure reason. Failure reason will be set only if the stage is `failed`.                                                                                 | [Possible values](/api-reference/widget) |
| `id`                                | Unique MoonPay transaction ID that can be added to the MoonPay transaction receipt URL                                                                                    |                                          |
| `externalTransactionId`             | Your transaction identifier that was passed in the `externalTransactionId` widget parameter. This identifier will be present whenever MoonPay sends you transaction data. |                                          |
| `createdAt`                         | Timestamp of when the transaction was created                                                                                                                             |                                          |
| `currency.name` and `currency.code` | Cryptocurrency name and code, e.g. Ethereum and ETH                                                                                                                       |                                          |

## Mobile integrations

All partner mobile apps must follow these guidelines for setting up in-app browsers.

### iOS in-app browser setup

Use a full screen in-app browser and remove the navigation bar to provide a more native user experience.

<Frame>
  <img alt="Full-screen in-app webview in iOS" />
</Frame>

<Steps>
  <Step title="Screen implementation">
    ```typescript React Native Example wrap theme={null}
    import { WebView } from "react-native-webview";

    const YourMoonpayWidgetScreen = ({
      route: {
        params: { moonpayWidgetUrl },
      },
    }) => <WebView source={{ uri: moonpayWidgetUrl }} enableApplePay />;
    ```
  </Step>

  <Step title="Register screen as a modal in the navigator">
    This enables the widget to slide up from the bottom of the screen.

    ```typescript React Native example wrap theme={null}
    import { createNativeStackNavigator } from "@react-navigation/native-stack";

    const Stack = createNativeStackNavigator();

    <Stack.Navigator
      component="widgetScreenName" // Your widget screen name
      options={{ presentation: "modal" }}
    />;

    ```
  </Step>

  <Step title="Configure the screen so that all payment methods and KYC steps work correctly">
    * Allow pop-ups at the in-app browser level so the customer can use PayPal, Venmo and Revolut without seeing an error
    * Follow the [*App Requirements for KYC*](/widget/design-your-integration#app-requirements-for-kyc) section below so the customer can upload their KYC documents and complete a selfie check.
  </Step>
</Steps>

### Android in-app browser setup

On Android we recommend loading the MoonPay widget within the `react-native-inappbrowser-reborn` as it supports Google Pay out of the box.

```typescript React Native example theme={null}
import InAppBrowser from "react-native-inappbrowser-reborn";

export const openBrowser = async ({ link }) => {
  try {
    InAppBrowser.close();
    const browserResult = await InAppBrowser.open(link, {
      forceCloseOnRedirection: false,
      showInRecents: true,
      animated: true,
    });

    // Automatically closes the browser if there is an issue with loading the widget.
    if (browserResult?.type === "dismiss") {
      InAppBrowser.close();
    }

    return browserResult;
  } catch (e) {
    // handle error
  }
};
```

### App requirements for KYC

<Warning>
  When not using a MoonPay SDK, make sure that the following requirements are
  met so that users can successfully complete KYC (Know Your Customer) steps.
</Warning>

These requirements make sure that customers can complete each KYC step, including uploading documents and doing a selfie check. Failing to follow these steps will cause new customers to drop off, as they won't be able to finish KYC or make a purchase.

#### General app requirements for all implementations

All partner apps should ensure the following:

* `Feature-Policy` header for your webpage / frame or any other container has no restrictions for initializing camera like value `camera 'none'`.
* `Permissions-Policy` header doesn't restrict access to a camera and microphone (for some cases) and if allow is set check for `"camera; microphone"` values.
* When using [iOS WKWebview](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/1614793-allowsinlinemediaplayback) you may need to set `allowsInlineMediaPlayback` to `true` in the `WKWebViewConfiguration` used in your app. This adjustment ensures that media content, like a camera feed, can be displayed properly within the web view, rather than forcing full-screen playback.
* Your website is being run on a secure `https` connection.

#### WebView requirements

Partner apps that use `WebView` should ensure the following:

* The web view is able to access device local storage and initialize camera (for older iOS versions, the camera can be accessed only from Safari browser or WebView with `SFSafariViewController`)
* HTML5 video playback is allowed (`<video>` tags are being used to send instructions): if video-instructions are not played, try using `WebChromeClient` to enable video playback
* Autoplay in fullscreen mode is disabled and `allowsInlineMediaPlayback` is set as `true` for WebView
* The selector file is implemented on your side (required for KYC document uploads)

#### Iframe requirements

Partner apps that use `iframe` should ensure the following:

* Parent page header has no restrictions for initializing the camera, e.g. `camera=()`
* Parent page can alternatively include `camera=*` in the Permissions-Policy header
* The iframe allow property has `allow="accelerometer; autoplay; camera; encrypted-media; gyroscope; payment"`

### Feature comparison

When choosing what type of in-app browser to use, review the features that are compatible with each.

Note that certain mobile payment and social sign-in configurations are not compatible with certain in-app browsers, for example `WebView` is not compatible with Google Pay and Google sign-in.

| Feature        | Chrome Custom Tabs | SFSafariViewController | WebView | Iframe |
| -------------- | ------------------ | ---------------------- | ------- | ------ |
| Apple Pay      | ❌                  | ✅                      | ✅       | ❌      |
| Google Pay     | ✅                  | ❌                      | ❌       | ❌      |
| Apple sign-in  | ✅                  | ✅                      | ✅       | ✅      |
| Google sign-in | ✅                  | ✅                      | ❌       | ✅      |
| SDK events     | ❌                  | ❌                      | ✅       | ✅      |

<Frame>
  <img />
</Frame>

### Customize logos and themes

#### Custom logos

Contact your MoonPay team to customize the logos in the transaction emails.

* 1 rectangular logo for transactional emails (jpg or png formats)

#### Custom themes

Customize your widget's theme in [your MoonPay dashboard](https://dashboard.moonpay.com/theme). Themes are tied to API keys and will be applied whenever you pass your API key to the MoonPay widget and transaction tracker.

<Check>
  **Impact**: Users are 20% more likely to get past the code (OTP) verification
  screen when the MoonPay widget has custom theming.
</Check>

### Adding Domains to the whitelist

Be sure to add your HTTPS domain in the [MoonPay dashboard](https://dashboard.moonpay.com/developers/general). This ensures the MoonPay widget loads correctly, as only approved domains are permitted for security reasons.


# Integration design guide
Source: https://dev.moonpay.com/widget/design-your-off-ramp-integration

Build your integration with the MoonPay Standard—proven insights from top-performing partner integrations that drive revenue and usability.

## Go-live requirements

<Info>
  To receive your production API keys, the following integration requirements
  must be met.
</Info>

* **Multiple entry points** — Sell buttons in home screen, main app navigation, and individual cryptocurrency screens. See [Sell button placement](#sell-button-placement).
* **Amount input** — Add a `max` button, estimate network fees, pre-fill fiat/crypto amount using `baseCurrencyCode` with `baseCurrencyAmount`, and show minimum/maximum sell limits. See [Amount input screen](#amount-input-screen) and [Minimum and maximum sell limits](#minimum-and-maximum-sell-limits).
* **Payout method selection screen** — Show all supported payout methods, payment method logos, and estimated completion times. See [Payout method selection](#payout-method-selection) and [Supported payout methods](/api-reference/widget).
* **Provider selection screen** — Show [`ID verified` badges](#id-verified-and-previously-used-badges) for returning users, quotes from `/sell_quote` using `payoutMethod`, and estimated completion times. See [Provider selection](#provider-selection).
* **Pre-fill the customer's email address** — Pre-fill via the `email` parameter to skip the widget login screen. See [Pre-fill the customer's email address](#pre-fill-the-customers-email-address).
* **Pre-fill the customer's refund wallet address(es)** — Pass `refundWalletAddress` or `refundWalletAddresses` (with `currencyCode` or `defaultCurrencyCode` when using the singular form), and [sign URLs with your secret key](/widget/off-ramp-enhance-security-using-signed-urls). See [Pre-fill the customer's refund wallet address(es)](#pre-fill-the-customers-refund-wallet-address).
* **Handle crypto deposits** — Use the SDK's `onInitiateDeposit` handler or `redirectURL` parameter to get deposit instructions; show the deposit details so the user can confirm. See [Handle crypto deposits](#handle-crypto-deposits).
* **Transaction tracking** — Display a toast after the user completes their transaction with a link to the MoonPay transaction tracker, or to your own history page. See [Track the order status](#track-the-order-status).
* **Mobile app configuration** — Use a fullscreen in-app browser without a nav bar, allow KYC, and allow pop-ups at the browser level. See [Mobile integrations](#mobile-integrations).

## User journey demo

Explore the demo below for an end-to-end showcase of a well-designed off-ramp integration with a wallet partner.

<iframe title="Figma" />

## Implementation details

### Sell button placement

All partner apps must show sell buttons in the following areas:

* Home screen
* Main app navigation
* Cryptocurrency-specific screens

Highly visible Sell buttons in these areas reduces the number of clicks for users to transact and improves the user experience. You should also Sell buttons wherever users expect to be able to transact, like their wallet, trading screens, and other screens specific to your app.

<Check>
  **Impact:** A minimum 2x increase in transaction volume based on data from a
  basket of partners including Uniswap.
</Check>

<Frame>
  <img alt="Prominent sell button on the home screen" />
</Frame>

<Frame>
  <img alt="Sell button in the cryptocurrency screen" />
</Frame>

## Currency selector

When a user clicks on the Sell button, it should be easy to find crypto to sell:

* List all cryptocurrencies available to sell through your MoonPay integration
* Show balances for each cryptocurrency
* Include a search bar and filters for ease of use
* Show the currency icon, abbreviation, full name, and network of each token so users can easily browse the list

<Frame>
  <img alt="Currency selection screen with search and balances" />
</Frame>

## Amount input screen

A dedicated screen in your app for the user to select the amount, crypto, and fiat for their transaction provides a more seamless experience with the MoonPay widget.

For partner apps that have an amount input screen, use the following design elements for ease of use:

* When opening the MoonPay widget, pass the widget parameters`baseCurrencyCode` with`baseCurrencyAmount` and `quoteCurrencyCode`to pre-fill how much crypto the user wants to sell and which fiat they want to be paid in
* Allow users to change which crypto they're selling on this screen without leaving the flow
* [Validate minimum and maximum sell amounts](#minimum-and-maximum-sell-limits) against our Limits endpoint
  * Please note that the quote provided in this endpoint represents a platform-wide floor value, not a user-specific value

<Frame>
  <img alt="Amount screen with balance, min / max buttons and currency switcher" />
</Frame>

### Max button

Show a max button to let users quickly sell the maximum amount available in their wallet. This max amount needs to account for any network fees required to send the crypto deposit. In other words, your app should estimate the network fee using [one of the methods](/widget/design-your-off-ramp-integration#optimize-network-fees-for-successful-sell-orders) below, then deduct that amount from the user's balance and show this as the maximum amount available to sell.

<Check>
  **Impact:** Our data shows that a large percentage of users choose to sell their max balance. You can reduce friction for these users by adding a max button and optimizing network fees for sending crypto deposits.
</Check>

### Optimize network fees for successful sell orders

Insufficient funds to cover network fees commonly result in failed sell orders. To ensure a high transaction success rate, your app should estimate the network fee and adjust the maximum amount of crypto the user is able to sell on the initial `Sell crypto`screen within your app. You can choose to show the network fee estimate or a tooltip in your app, or simply abstract this away depending on your user base.

This approach allows users to create sell transactions without needing to restart the flow if they don't have enough crypto to cover the network fee, ultimately enhancing the user experience and improving conversion rates.

#### Example scenario

A user wishes to sell their full wallet balance of 1 ETH to fiat. To account for network fees, it is crucial that the partner obtains an up-to-date fee estimate using a reliable third-party API, such as the [Fireblocks Network Fee API](https://developers.fireblocks.com/reference/estimatenetworkfee).

If the estimated network fee is 0.001 ETH, the partner should pass 0.999 (1 ETH - 0.001) of ETH via the MoonPay widget to initiate the sell transaction. The partner should also ensure that the user is presented with a price quote for the adjusted amount of 0.999 ETH, optionally with a clear explanation of the network fees and the reason for the difference from their wallet balance.

When the send transaction is created by the partner, the network fee specified in the transaction is fixed and separate from the amount being sent. This design ensures that miners can only take the fee set by the wallet provider, and cannot exceed this amount. Therefore, MoonPay will still receive the exact 0.999 ETH, regardless of any fluctuations in network fees after the transaction is initiated.

#### Best practices for fee estimations

**Automate network fee estimates**: Always automate gas fee estimates for users. Prioritizing faster transaction speeds will significantly enhance the user experience compared to choosing slower, less costly network fees. **Update network estimates at execution**: Always update the network fee estimation at the moment of transaction execution. This practice helps to account for any potential spikes in network fees that might occur since the transaction was initiated. **Consider transaction speed**: While opting for a faster transaction speed generally prevents delays, there may be situations where network fees are exceptionally high. In such cases, selecting a slower option may be more cost-effective. If you choose this route, ensure that users are informed that their transaction will take longer to complete.

### Minimum and maximum sell limits

For partner apps that have an amount input screen, ensure a seamless user experience between your app and the MoonPay widget by checking entered amounts against our [GET /v3/currencies](/api-reference/widget) endpoint. Widget errors caused by invalid amounts will require the user to re-enter the amount to sell, which adds another step and impacts the user experience.

<Check>
  **Impact:**

  * Partners that offer transactions over \$10K see a 45% higher median for completed transaction volume.
  * Partners also see 3% of their total completed volume from transactions over \$10K.
</Check>

## Payout method selection

For partner apps with a payment method selection screen:

* Show [all payment methods supported by MoonPay](https://support.moonpay.com/customers/docs/all-supported-payment-methods), depending on the user's region and currency
  * All available payment methods per transaction type, region, and fiat currency can be surfaced using the [`/payment_method_config` endpoint](/api-reference/widget)

* Show payment method details that are returned in the `/payment_method_config` response
  * Use payment method logos
  * Show estimated transaction completion times

* Pre-fill the `?paymentMethod` widget param with the selected payment method

A payment method selection screen in your app lets your customers easily choose how they want to transact while also getting more accurate quotes. If your app has a payment method selector, it's highly recommended to use the [`/payment_method_config` endpoint](/api-reference/widget) to surface all available payment methods. Otherwise, you'll need to periodically update your app as we release new payment methods:

* Update `?paymentMethod` when calling the `/buy_quote` endpoint and showing the widget
* Add the new payment method as an option in your app, including the logo, estimated transaction completion times
* Any other payment method-specific requirements

## Provider selection

For partner apps that offer ramps providers other than MoonPay, display key context on a provider selection screen, including:

* `ID verified` [badge for users who have completed KYC](/widget/moonpay-conversion-badges)
* Quotes from our[`/sell_quote` endpoint](/api-reference/widget) using `paymentMethod`
* Supported payment methods and their logos

<Frame>
  <img alt="selection" />
</Frame>

### ID verified and previously used badges

`ID verified` and `Previously used` badges ensure a frictionless experience for returning users by indicating that their KYC has been completed. Our data show that returning users can be less price-sensitive than new users, preferring a more convenient checkout experience with fewer steps.

Call our [GET /v3/customers/badges endpoint](/widget/moonpay-conversion-badges) with the customer's wallet address and we will return the customer's KYC status which you can use to show the `ID verified` badge.

<Check>
  **Impact**

  * User retention rates are 70% higher when they know they've transacted before.
  * 30% of wallet address that get passed to our Badges endpoint are already KYC'd.
</Check>

<Frame>
  <img />
</Frame>

### Payout method logos

Build customer trust by displaying the supported payment and payout method logos for your integration. For customers new to crypto, these familiar payment methods indicate a safe checkout process.

[Download these logos as a ZIP file](https://drive.google.com/uc?export=download\&id=1Z26OICqzkzDusYpNUyQNcJm__HOWsGNZ) and review the supported payment / payout methods below:

* [On-ramp payment methods](https://support.moonpay.com/hc/en-gb/articles/360017624078-What-are-your-supported-payment-methods-)
* [Off-ramp payout methods](https://support.moonpay.com/hc/en-gb/articles/360013743077-Which-bank-accounts-are-supported-for-withdrawals-)

## Loading screen

Use logos to guide the user when redirecting the user to MoonPay. Before opening the MoonPay widget, show a loading screen with both your logo and MoonPay’s logo to build user trust and set expectations about the user journey.

<Frame>
  <img alt="Loading" />
</Frame>

## Skip the amount

By default, the first screen in the MoonPay widget asks the user to confirm the amount of crypto to sell. If your app has an amount input screen, you can skip the amount screen in the MoonPay widget for a more seamless end-to-end customer journey and increase conversions by 6%.

Pass the following [widget parameters](/widget/ramps-sdk-sell-params):

`baseCurrencyCode` + `baseCurrencyAmount`

<Check>
  **Impact**

  * Skipping the initial amount screen increases conversions by 6%.
</Check>

## Login options

### Pre-fill the customer's email address

Partner apps that know the user's email address must pre-fill the customer's email address by passing the [`email` widget parameter](/widget/ramps-sdk-sell-params), so the customer won't be prompted to enter one. The widget will skip to the MFA code screen.

Returning customers that are logged in are 5% more likely to complete a transaction than returning customers that are not logged in. By pre-filling the customer's email address, you can capture some of this shortfall and increase transaction volume.

<Check>
  ### Impact

  * Returning customers that are logged in are 5% more likely to complete a transaction.
  * For new users who haven't transacted before, this is even higher at 25% more likely to complete their first transaction.
</Check>

### Social sign-in

If your app doesn't use email addresses to identify users, and uses `SFSafariViewController` or `Chrome Custom Tabs`, contact your MoonPay team to enable social sign-in. [Compare in-app browser features](/widget/design-your-off-ramp-integration#feature-comparison).

<Frame>
  <img alt="Social" />
</Frame>

## Pre-fill the customer's refund wallet address

Partner apps that know the user's wallet address(es) must use the refundWalletAddress or walletAddresses parameters to ensure that any refunded crypto gets sent back to the user.

When using the refundWalletAddress parameter, you must also:

* Pass baseCurrencyCode or defaultBaseCurrencyCode and
* [Sign URLs server-side](/widget/off-ramp-enhance-security-using-signed-urls)

You can alternatively use the walletAddresses parameter to pass multiple wallet addresses with their corresponding chains. The user will be able to choose from a filtered list of cryptocurrencies limited to those you pass in the parameter, and the wallet address screen will also be skipped.

## Pre-select the payout method

Use the paymentMethod parameter to pre-select the user's payout method and match what they chose in the partner app.

## Handle crypto deposits

To complete a sell transaction, the customer deposits their cryptocurrency to a MoonPay-owned wallet as the last step of their journey. In the default sell journey, users will see a QR code and instructions in the widget to manually deposit their crypto. For the transaction to be completed successfully, they must ensure that the amount, cryptocurrency, network, and wallet address are all correct in their deposit, which is error-prone and routinely causes users to drop off.

For this reason, we recommend removing this point of friction by handling the crypto deposit using `onInitiateDeposit()` or `?redirectURL`. This is highly recommended, as it provides a better user experience and improves conversion.

| Method                           | How to implement                                                                                        |
| -------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `onInitiateDeposit()`Recommended | Get deposit instructions via SDK event handler, then send deposit using your app's native send function |
| `?redirectURL`Recommended        | Get deposit instructions via URL parameters, then send deposit using your app's native send function    |
| Manual deposit with QR code      | Default flow; no additional implementation steps                                                        |

### Example journey using `onInitiateDeposit()` or `?redirectURL`

When you get the deposit instructions using `onInitiateDeposit()` or `?redirectURL`, the user journey will be as follows:

1. Go through the sell order flow in the widget
2. Return to your app by clicking the `Send with <partner name>` button
3. Confirm the sell transaction in your app
4. Confirmation screen links to a transaction history page

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

### **Method 1**: Use the SDK’s `onInitiateDeposit` event handler

When you register for the SDK event handler `onInitiateDeposit`, the MoonPay widget will instruct your application to initiate the deposit.

At the end of the sell flow, the user will use the `Initiate deposit` button to continue making the deposit in your app. The deposit instructions, including the transaction ID, base currency code, base currency amount, deposit wallet address and, if applicable, the respective tag will be sent from the widget to your app. Your app will make the deposit and return the corresponding deposit ID from your side.

```typescript theme={null}
type OnInitiateDepositProps = {
  transactionId: string;
  cryptoCurrency: {
    id: string;
    name: string;
    code: string;
    contractAddress: string | null;
    chainId: string | null;
    coinType: string | null;
    networkCode: string | null;
  };
  fiatCurrency: {
    id: string;
    name: string;
    code: string;
  };
  /** Crypto amount in its base unit (0.123 ETH === "0.123") */
  cryptoCurrencyAmount: string;
  /** Crypto amount in its smallest unit (1 ETH === 1x10^18) */
  cryptoCurrencyAmountSmallestDenomination: string;
  /** Fiat amount in its base unit ($1.23 === "1.23"). Only set for fixed quotes. */
  fiatCurrencyAmount: string | null;
  depositWalletAddress: string;
};

const moonpaySdk = window.MoonPayWebSdk.init({
  flow: "sell",
  environment: "sandbox",
  variant: "overlay",
  params: {
    apiKey: "pk_test_key",
  },
  handlers: {
    async onInitiateDeposit(properties: OnInitiateDepositProps) {
      // Your own crypto deposit code
      const { cryptoCurrency, cryptoCurrencyAmount, depositWalletAddress } =
        properties;
      const depositId = await deposit(
        cryptoCurrency.code,
        cryptoCurrencyAmount,
        depositWalletAddress,
      );
      return { depositId };
    },
  },
});
```

### **Method 2**: Pass the `redirectURL` widget parameter

Passing`redirectURL`will show a button at the end of the sell flow that says`Send with <partner name>`, which the user clicks to be redirected back to your app. The deposit instructions, including the `transactionId`, `baseCurrencyCode`, `baseCurrencyAmount`, `depositWalletAddress` and, if applicable, `depositWalletAddressTag`, will be appended as URL parameters. [List of off-ramp parameters](/widget/ramps-sdk-sell-params)

`redirectURL` supports HTTPS or Universal/App Link URLs. Custom-scheme links (e.g., myapp\://…) are not supported.

<Warning>
  When `depositWalletAddressTag` is included in the URL parameters, you must
  include this with the deposit, otherwise the transaction will fail.
</Warning>

<Info>
  When using redirectURL with the off-ramp, you must set up webhooks or API
  calls to verify the deposit instructions. [Webhooks
  overview](/api-reference/widget/webhooks/overview).
</Info>

### Manual deposits

If you don't use `onInitiateDeposit` or `redirectURL`, the widget will display a QR code and deposit instructions for the user to manually deposit their crypto to a MoonPay-owned wallet. However, it’s highly recommended to use these options over manual deposits, as this significantly improves the user experience and sell transaction success rates.

<Frame>
  <img alt="Manual crypto deposit instructions" />
</Frame>

## Track the order status

All partner apps must provide some kind of transaction tracking, whether a toast message that links to the MoonPay transaction tracker or your app's own transaction history screen.

After a user completes the sell flow in the MoonPay widget, it's crucial for them to be able to monitor their order's progress and understand its status. Increased transparency results in greater user trust and returning users who are 13% more likely to return and complete another transaction.

<Check>
  ### Impact

  Increased transparency results in greater user trust and returning users who are 13% more likely to complete another transaction.
</Check>

MoonPay facilitates this through the use of webhooks and APIs. Webhooks provide real-time order updates to a specified endpoint of your choice, while the API allows for on-demand retrieval of the latest order status.

Both our [webhooks](/api-reference/widget/webhooks/buy) and [API](/api-reference/widget/getbuytransactions) offer consistent data, giving you the flexibility to employ either or both methods as per your requirements.

1. **Transaction tracking toast message**: After a user completes a transaction, show a toast message that persists until the crypto has been received in the user's wallet. When clicked, either the MoonPay transaction tracker or your app's transaction history page should open.

* Partners not able to use webhooks for this toast message should implement a transaction history screen and use API calls to retrieve transaction data on-demand.

<Frame>
  <img />
</Frame>

1. **Use the MoonPay transaction tracker**: We return the transaction tracker URL in our webhooks and API in the `data.returnURL` object. **Example tracker URL**: `https://sell.moonpay.com/transaction_receipt?transactionId=cd08a180-6efe-4eb4-b51a-075d945e732c`. You can optionally pass the `apiKey` parameter to enable your custom theme on the tracker.

<Frame>
  <img />
</Frame>

2. **Use your own transaction tracker**: You can optionally create your own
   transaction tracking screen that shows transaction data from our API and
   webhooks.

<Frame>
  <img />
</Frame>

<Frame>
  <img />
</Frame>

### API and webhook objects for transaction tracking

Additional examples and details for all parameters can be found in our transaction [API documentation](/api-reference/widget) under the *200 Responses* section.

| Object                                      | Description                                                                                                                                                               | Notes                                    |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `cryptoTransactionId`                       | On-chain transaction hash that can be searched on the corresponding blockchain explorer                                                                                   |                                          |
| `stages` and `stages.failureReason`         | Order stage and failure reason. Failure reason will be set only if the stage is `failed`.                                                                                 | [Possible values](/api-reference/widget) |
| `id`                                        | Unique MoonPay transaction ID that can be added to the MoonPay transaction receipt URL                                                                                    |                                          |
| `externalTransactionId`                     | Your transaction identifier that was passed in the `externalTransactionId` widget parameter. This identifier will be present whenever MoonPay sends you transaction data. |                                          |
| `createdAt`                                 | Timestamp of when the transaction was created                                                                                                                             |                                          |
| `baseCurrency.name` and `baseCurrency.code` | Cryptocurrency name and code, e.g. Ethereum and ETH                                                                                                                       |                                          |

***

## Mobile integrations

All partner mobile apps must follow these guidelines for setting up in-app browsers.

### In-app browser setup

Use a full screen in-app browser and remove the navigation bar to provide a more native user experience.

<Frame>
  <img />
</Frame>

#### Step 1: Screen implementation

```typescript React Native example theme={null}
import { WebView } from "react-native-webview";

const YourMoonpayWidgetScreen = ({
  route: {
    params: { moonpayWidgetUrl },
  },
}) => <WebView source={{ uri: moonpayWidgetUrl }} enableApplePay />;

```

#### Step 2: Register screen as a modal in the navigator

This enables the widget to slide up from the bottom of the screen.

```typescript React Native example theme={null}
import { createNativeStackNavigator } from "@react-navigation/native-stack";
const Stack = createNativeStackNavigator();

return (
  <Stack.Navigator>
    <Stack.Screen
      name="yourMoonpayWidgetScreenName"
      component={YourMoonpayWidgetScreen}
      options={{ presentation: "modal" }}
    />{" "}
  </Stack.Navigator>
);
```

#### Step 3: Configure the screen

Configure the screen so that all payment methods and KYC steps work correctly:

* Allow pop-ups at the in-app browser level so the customer can use PayPal without seeing an error
* Follow the *App Requirements for KYC* section below so the customer can upload their KYC documents and complete a selfie check.

## App requirements for KYC

<Warning>
  When not using a MoonPay SDK, make sure that the following requirements are
  met so that users can successfully complete KYC (Know Your Customer) steps.
</Warning>

These requirements make sure that customers can complete each KYC step, including uploading documents and doing a selfie check. Failing to follow these steps will cause new customers to drop off, as they won't be able to finish KYC or make a purchase.

# General app requirements for all implementations

All partner apps should ensure the following:

* `Feature-Policy` header for your webpage / frame or any other container has no restrictions for initializing camera like value `camera 'none'`.
* `Permissions-Policy` header doesn't restrict access to a camera and microphone (for some cases) and if allow is set check for `"camera; microphone"` values.
* When using [iOS WKWebview](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/1614793-allowsinlinemediaplayback) you may need to set `allowsInlineMediaPlayback` to `true` in the `WKWebViewConfiguration` used in your app. This adjustment ensures that media content, like a camera feed, can be displayed properly within the web view, rather than forcing full-screen playback.
* Your website is being run on a secure `https` connection.

### WebView requirements

Partner apps that use `WebView` should ensure the following:

* The web view is able to access device local storage and initialize camera (for older iOS versions, the camera can be accessed only from Safari browser or WebView with `SFSafariViewController`)
* HTML5 video playback is allowed (`<video>` tags are being used to send instructions): if video-instructions are not played, try using `WebChromeClient` to enable video playback
* Autoplay in fullscreen mode is disabled and `allowsInlineMediaPlayback` is set as `true` for WebView
* The selector file is implemented on your side (required for KYC document uploads)

### Iframe requirements

Partner apps that use `iframe` should ensure the following:

* Parent page header has no restrictions for initializing the camera, e.g. `camera=()`
* Parent page can alternatively include `camera=*` in the Permissions-Policy header
* The iframe allow property has `allow="accelerometer; autoplay; camera; encrypted-media; gyroscope; payment"`

## Feature comparison

When choosing what type of in-app browser to use, review the features that are compatible with each.

Note that certain mobile payment and social sign-in configurations are not compatible with certain in-app browsers, for example `WebView` is not compatible with Google Pay and Google sign-in.

| Feature        | Chrome Custom Tabs | SFSafariViewController | WebView | Iframe |
| -------------- | ------------------ | ---------------------- | ------- | ------ |
| Apple Pay      | ❌                  | ✅                      | ✅       | ❌      |
| Google Pay     | ✅                  | ❌                      | ❌       | ❌      |
| Apple sign-in  | ✅                  | ✅                      | ✅       | ✅      |
| Google sign-in | ✅                  | ✅                      | ❌       | ✅      |
| SDK events     | ❌                  | ❌                      | ✅       | ✅      |

<Frame>
  <img alt="social" />
</Frame>

## Customize logos and themes

### Custom logos

Contact your MoonPay team to customize the logos in your integration. Provide 2 logos in jpg or png formats:

* 1 square logo for the widget login screen
* 1 rectangular logo for transactional emails

### Custom themes

Customize your widget's theme in [your MoonPay dashboard](https://dashboard.moonpay.com/theme). Themes are tied to API keys and will be applied whenever you pass your API key to the MoonPay widget and / or transaction tracker.

<Check>
  **Impact:** Users are 20% more likely to get past the code (OTP) verification screen when the MoonPay widget has custom theming.
</Check>


# Mobile payments
Source: https://dev.moonpay.com/widget/faq-mobile-payments



## Does MoonPay support Apple Pay and Google Pay?

Yes.

## What are the benefits of using Apple Pay and Google Pay?

These payment options provide a frictionless way for your customers to make purchases. On average, users are more likely to purchase with Apple Pay / Google Pay over any other payment method when given the option.

## Apple Pay

### How do I integrate with Apple Pay?

Apple recommends using SFSafariViewController. SFSafariViewController is part of the SafariServices framework and lets users browse a web page or a website right inside your app.

NB: Apple Pay will not work if you try to load the MoonPay widget within an iframe. We recommend redirecting users to our [https://buy.moonpay.com](https://buy.moonpay.com) domain within SFSafariViewController.

### What if I want to use iOS WKWebview instead?

When iOS 13 was released in 2019, Apple said web pages loaded in WKWebView can now accept Apple Pay. Since then however Apple has not given any official guidance on their support for WKWebview and their developer documentation says only “Safari and SFSafariViewController objects support Apple Pay.”

Alternatively some partners have used the React Native in-app browser. If installed on iOS it gives you SFSafariViewController but the implementation is more difficult and not officially recommended by MoonPay.

### Can I use Apple Pay on desktop?

Yes, as long as:

1. The user is using Safari or your integration uses SFSafariViewController.
2. The user's card is already set up with Apple Pay.
3. The MoonPay widget is NOT in an iframe.

## Google Pay

### How do I integrate with Google Pay?

Google recommends using Chrome Custom Tabs for Google Pay support. Similar to Apple Pay, Google Pay will not work within an iframe. We recommend redirecting users to our [https://buy.moonpay.com](https://buy.moonpay.com) domain within Custom Tabs.

### Will Google Pay work in a web view?

Google Pay is not officially supported web views. We recommend partners use Chrome or Chrome Custom Tabs only.

Alternatively, some partners have used the React Native in-app browser. If installed on Android it gives you Chrome Custom Tabs.

### Can I use Google Pay on desktop?

Yes, as long as:

1. The user is using Chrome or your integration uses Chrome Custom Tabs. The default in-app Android webview does not support Google Pay.
2. The user's card is set up with Google Pay.
3. The MoonPay widget is NOT in an iframe.


# Sandbox testing guide
Source: https://dev.moonpay.com/widget/faq-sandbox-testing

MoonPay provides a dedicated sandbox environment designed for integration development and testing. Leveraging this sandbox helps you identify potential issues early, ensures compatibility, and minimizes risks during deployment.

## Sandbox on-ramp widget

You can test our on-ramp widget below:

<iframe title="Sandbox" />

## Initialize the MoonPay widget

Initialize the MoonPay widget using your test API key with our [SDK](/widget/on-ramp-web-sdk) or with a simple URL:

```html Widget embed URL theme={null}
https://buy.moonpay.com/?apiKey=pk_test_INSERT_YOUR_API_KEY
```

Using your test API key with this widget URL will automatically switch the environment to our sandbox. Your API key can be found on the [Developers Page](https://dashboard.moonpay.com/developers/api-keys) in your MoonPay dashboard.

## Create a sandbox test account

Know Your Customer (KYC) information entered will not be verified and when asked for documents you can skip by clicking on the "Skip document submission" button. **We recommend adding a US or UK address for sandbox accounts since these work best with our test credit cards**.

<Frame>
  <img alt="IDV Flow" />
</Frame>

## Sandbox token and testnet support

Our sandbox environment supports the following tokens and testnets:

| Token         | Testnet  | Notes                                                                                                                       |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| Bitcoin       | Testnet3 |                                                                                                                             |
| Ethereum      | Sepolia  |                                                                                                                             |
| ERC-20 tokens | Sepolia  | Transfers will use our [ERC-20 MoonPayToken](https://goerli.etherscan.io/token/0x9550949c46e27761b57f5391a25a7725444a938b). |
| Solana        | Testnet  |                                                                                                                             |
| Binance Coin  | Testnet  |                                                                                                                             |
| TON           | Testnet  |                                                                                                                             |
| Stellar       | Testnet  |                                                                                                                             |
| Litecoin      | Testnet  |                                                                                                                             |

## Add a payment method

At the payment screen choose the debit/credit card option and enter one of the following test card numbers. **Do not enter authentic payment card information, as this will result in a failed transaction.**

| Card Type                      | Card Number         | Expiration | CVC code |
| ------------------------------ | ------------------- | ---------- | -------- |
| MasterCard 3DS Challenge (USA) | 5385 3083 6013 5181 | 12/2030    | 123      |
| Visa 3DS Frictionless (UK)     | 4485 0403 7153 6584 | 12/2030    | 123      |
| Visa 3DS Challenge (UK)        | 4242 4242 4242 4242 | 12/2030    | 123      |

### Test Card for Declined Transactions

| Card type               | Card number         | Expiration | CVC code |
| ----------------------- | ------------------- | ---------- | -------- |
| Visa Insufficient funds | 4544 2491 6767 3670 | 12/2030    | 123      |

### Test Card for Off-Ramp Payouts

| Card type          | Card number         | Expiration | CVC code |
| ------------------ | ------------------- | ---------- | -------- |
| Visa Direct payout | 4000 0209 5159 5032 | 12/2030    | 123      |

## Returning testnet tokens

After testing, please return testnet coins to us at the wallet addresses below.

| Blockchain     | Testnet wallet address                                   |
| -------------- | -------------------------------------------------------- |
| `Bitcoin`      | tb1q45h8zexwztmz3nyd8gmkxhpavdsva4znwwhzvs               |
| `Bitcoin Cash` | bchtest:qrn45hfjpqd0w5p7dur5a2aasgp3nj8d8qh4exym5k       |
| `Ethereum`     | 0xc216eD2D6c295579718dbd4a797845CdA70B3C36               |
| `Litecoin`     | tltc1qjrv8pm0lumhyjkrrevk3p7wpwhtuz7e22mujw0             |
| `Ripple`       | rUZTCFB6zPyeEmDhrAVqVbBaLPWrzjKCQz                       |
| `Flow & FUSD`  | 0x4c6903af5fb0f9f2                                       |
| `Stellar`      | GD4KAFADEFXOLNWWUA4IZI5YG23AH2OSJMIJAZ6YLNHJWNPX3T366FIY |

***

## Sandbox Failure Reasons

* `Transaction processing failed` may happen when the testnet wallet is empty or you used the wrong card. Please reach out to your MoonPay representative.
* `Your Region is Not Supported` means MoonPay may not [support your country](https://support.moonpay.com/customers/docs/moonpays-unsupported-countries) or the cryptocurrency is [unsupported in your region](https://support.moonpay.com/customers/docs/list-of-supported-cryptocurrencies). New York, USA is not supported in sandbox but is supported in production.
* `You've made too many actions` or `You can't perform this action` means you have been rate limited. This happens when we detect unusual behavior and is not uncommon for partners to experience this while testing. The recommendation is to wait \~20 minutes before trying again.
* `Account is restricted or blocked` may happen if you are using a production MoonPay user account in sandbox or entered otherwise triggered one of our automated flags for suspicious behavior.

<Info>
  ### Empty testnet wallet

  An empty testnet wallet will result in a `Transaction processing failed` error when you and other developers try to complete transactions. You may top up the wallet with your own testnet coins or use any available online faucet to top up Sepolia ETH.
</Info>


# FAQ
Source: https://dev.moonpay.com/widget/faqs



<Warning>
  IPv6 Deprecation: IPv6 support for outbound requests will end on May 13, 2026.
  Please ensure our IPv4 ranges are explicitly allowlisted.
</Warning>

## Integrating

### Where can we integrate your solution (website, marketplace, in-game)?

You will be able to integrate it wherever you’d like. We surface an SDK and you can choose to pass a variety of query parameters to the Widget that is being spun up. You can pass token you want users to buy, destination wallet address and lots more. You can see all the [parameters here](/widget/ramps-sdk-buy-params).

### What does the customer journey look like?

This depends on the query parameters you use.

### What do the different team permissions in the dashboard do?

The Partner Dashboard uses role-based access control to manage team member permissions. Each team member is assigned one of the following roles:

| Role               | Access Level      | Permissions                                                                                                                                                         |
| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Administrator      | Full access       | Complete access to all dashboard features including dashboard analytics, transactions (with CSV export), team management, developer settings, and account settings. |
| Developer          | Limited access    | Can view dashboard analytics, transactions, and team members. Can manage API keys and developer settings. Cannot access account settings.                           |
| Analyst            | Read & export     | Can view dashboard analytics, transactions (with CSV export), and team members. Cannot access developer settings or account settings.                               |
| Support Specialist | Transactions only | Limited to viewing and managing transactions. Cannot access dashboard analytics, team management, developer settings, or account settings.                          |

### Does the end-user need to provide a wallet or are you providing (non)custodial wallets on checkout?

Both are possible. You can pass one, we can allow the user to create one (BTC and ETH) or you can allow users to input their own wallet address.

### Any recommended best practices for the integration?

Yes! Best practices for each product are outlined on their respective documentation pages.

### The widget is returning an error. How do I escalate this?

Please include a screenshot and steps to reproduce the error when reaching out to your MoonPay representative.

### Is there a way to customize the automated emails users receive?

We can add a partner logo in the automated email and change the partner name (`Partner_Name` via MoonPay) in the email subject upon request. Please reach out to your MoonPay representative.

### How do I change my API Keys?

Go to the [Developers > API Keys](https://dashboard.moonpay.com/developers/) page of your MoonPay dashboard and hit the roll button next to the API key you wish to replace. You will be given the option to immediately delete the old key or a 12hour rollover before the old API keys expire.

### Iframe shows an error instead of the widget

If you see a CSP error that says `buy.moonpay.com refused to connect`, you’ll need to allowlist your production domain(s). We require this when you embed the MoonPay widget in an iframe or use the overlay, drawer, or embedded options to prevent unauthorized third-parties from embedding the MoonPay widget.

To resolve the issue, add your production domain(s) to the [Settings page](https://dashboard.moonpaycloud.com/settings/) of your MoonPay dashboard.

<Frame>
  <img alt="CSP Error" />
</Frame>

### Region-based widget error

If you see a widget error that geo-blocks certain users, confirm that these users are in a region supported by MoonPay. [Non-supported countries, states, and territories for on-ramp](https://support.moonpay.com/hc/en-gb/articles/6557330712721-What-are-our-non-supported-countries-states-and-territories-for-on-ramp-product-)

### Sandbox Supported Currencies

Our sandbox environment supports a limited selection of testnet currencies; we recommend testing primarily with Ethereum on Sepolia, Solana Testnet, TON or the Bitcoin Testnet.

### Multiple accounts in production

In our production environment, we only allow one account per user. Creating multiple accounts in production may cause your account to be flagged or blocked.

### Test credit cards and KYC info in production

Only genuine card and KYC information may be used in our production environment. Do **not** use test credit card or test KYC information in production, as this will result in your account being blocked.

### Using platforms like Flutter

MoonPay does not offer an SDK for Flutter. You'll have to manually embed our widget in a WebView. Consider the following tips:

* You can create your own HTML that uses our [Web SDK](/widget/on-ramp-web-sdk) to embed our Widget. This will allow you to receive our Widget's events, if you wish. You'll then need to send them out to your Flutter app layer.
* If you're experiencing camera issues in Flutter's WebView, consider using the Flutter plugin compatible with our Web SDK, available at [https://pub.dev/packages/flutter\_inappwebview](https://pub.dev/packages/flutter_inappwebview).
* You can find further guidance on configuring Flutter camera permissions and other related documentation at [https://inappwebview.dev/docs/5.x.x/web-rtc/](https://inappwebview.dev/docs/5.x.x/web-rtc/).
* Custom Origin via `baseUrl` Property: For specific requirements, you can set a custom origin using the `baseUrl` property. This serves as the base URL for any relative paths in the HTML and sets the document's origin. Example:

```dart theme={null}
InAppWebView(
  initialData: InAppWebViewInitialData(
    data: htmlContent,
    baseUrl: Uri.parse("https://your.custom.origin"),
  ),
  // ... other configurations ...
)
```

This custom origin approach can be advantageous for scenarios involving scripts that validate the document's origin or for CORS policies. We recommend using `https://app_name`, `capacitor://` or equivalent as your custom origin for the `baseUrl` property. From here, add the domain to your allowlist in the settings page of your [MoonPay dashboard](https://dashboard.moonpay.com/settings/).

* Scrolling Issues within the MoonPay widget: When using these overflowing containers in Flutter with a WebViewWidget, you have to specify gesture recognizers: Example:

  ```dart theme={null}
  gestureRecognizers: <Factory<OneSequenceGestureRecognizer>>{
    Factory<OneSequenceGestureRecognizer>(
      () => EagerGestureRecognizer(),
    ),
  },
  ```

* Avoid using `enableDrag: true` when embedding a WebView inside a `showModalBottomSheet()`, as it may interfere with touch interactions. Instead, provide a dedicated close button for a better user experience.

## Payments

### I'm having trouble adding my credit/debit card to my account

Double check you are not in our sandbox environment. Genuine cards should never be added to sandbox accounts.

Has your card already been added to another account? There is a limit of one card per account. Either use the other account or try using another card.

### How do you handle chargebacks?

At MoonPay, we treat chargebacks seriously and have processes in place to prevent and handle chargebacks. For more information reach out to your MoonPay account representative.

### What payment methods are available by country?

Payment Methods offered will vary based on the users location. Reach out to your MoonPay account representative for additional details.

### How do I get paid?

Details can be found on our [partner support site](https://support.moonpay.com/hc/en-gb/articles/4406209996049-How-do-affiliate-payouts-work-).

### What are my purchase limits?

Purchase limits will vary by region, currency and level of Know Your Customer KYC documents provided. Additional details can be found on our customer support page [here](https://support.moonpay.com/hc/en-gb/sections/360002592157-Verifications-Limits-).

### What cryptocurrencies does MoonPay support?

There are more limitations for US users than non-US users. A complete list can be found [here](https://support.moonpay.com/hc/en-gb/articles/360009280177-Which-cryptocurrencies-do-you-support-).

### Do you support Bitcoin Segwit, Taproot and legacy BTC addresses?

Yes, we support Taproot, Segwit, and legacy addresses. A user can send to a BTC wallet address as long as it's a match for regex we use to validate: `^[13][a-km-zA-HJ-NP-Z1-9]{25,34}$|^(bc1)[0-9A-Za-z]{39,59}$`

Please be aware that MoonPay's Wallet does not support Taproot, and it is advised not to use it for Ordinals to avoid potential loss. This caution specifically applies to MoonPay wallets.

## Fees

### Are there any integration fees to partner with MoonPay?

MoonPay charges a tiered subscription fee that provides full access to all products, analytics, and engineering support. Detailed pricing and plans can be found [here](https://dashboard.moonpay.com/dashboard/on-ramp/subscribe). Once live, partners can also choose to add an affiliate fee to each transaction.

### Are there any trading fees, Payment Service Provider (PSP) fees etc for our clients?

MoonPay doesn’t charge distinct trading or psp fees. Instead, a variable fee is applied for every transaction.

### Any other fees that we need to know?

Based on the specific blockchain, a network or gas fee might be applicable, which varies with network traffic.

## Network infrastructure

### What are MoonPay's external IP addresses?

IPv4

* 34.76.118.184
* 34.77.238.249
* 34.79.17.44
* 34.89.242.107
* 34.140.248.51
* 34.159.58.44
* 34.159.89.69
* 35.246.202.26

<Warning>
  ### IPv6 Deprecation: IPv6 support for outbound requests will end on May 13,

  2026. Please ensure our IPv4 ranges are explicitly allowlisted.
</Warning>

* 2600:1900:4010:bd99::/64
* 2600:1900:40d0:3d::/64

### What are the rate limits for the MoonPay REST API?

350 requests in 10 seconds on:

* GET `v3/currency/:code/price`
* GET `v3/currency/:code/ask_price`
* GET `v3/currency/:code/bid_price`
* GET `v3/currency/price`
* GET `v3/currency/ask_price`
* GET `v3/currency/bid_price`
* GET `v3/currency/:code/quote`
* GET `v3/currency/:code/buy_quote`
* GET `v3/currency/:code/sell_quote`
* GET `v3/currency/:code/buy_quotes`
* GET `v4/ip_address`

30 requests per second on all other endpoints.

Reach out to your MoonPay representative if you require higher limits.

## Supported regions and methods

### Supported countries

Buy is **available** for all residents except those [in the following countries and US states](https://support.moonpay.com/hc/en-gb/articles/6557330712721-What-are-our-non-supported-countries-states-and-territories-for-on-ramp-product-).

Sell is **unavailable** for residents of Louisiana, Texas, New York and US Virgin Islands.

### Supported tokens

List of all MoonPay supported assets for [BUY/On-Ramp](https://support.moonpay.com/hc/en-gb/articles/360009280177-Which-cryptocurrencies-do-you-support-).

List of all MoonPay supported assets for [SELL/Off-Ramp](https://support.moonpay.com/hc/en-gb/articles/360013742837-Which-cryptocurrencies-can-I-sell-).

### Supported payment methods

List of MoonPay [supported payment methods](https://support.moonpay.com/hc/en-gb/articles/360017624078-What-are-your-supported-payment-methods-) for US and NON-US regions.


# Integration examples
Source: https://dev.moonpay.com/widget/integration-examples



## Desktop

### Uniswap On-Ramp

<iframe title="YouTube video player" />

### MetaMask Off-Ramp

<iframe title="YouTube video player" />

***

## iOS

### Jupiter On-Ramp

<iframe title="YouTube video player" />

### Phantom On-Ramp

<iframe title="YouTube video player" />

## Android

### Ledger On-Ramp

<iframe title="YouTube video player" />

### Trust Wallet Off-Ramp

<iframe title="YouTube video player" />


# Architecture
Source: https://dev.moonpay.com/widget/off-ramp-architecture

The MoonPay Off-Ramp is a standalone widget product with an optional API and webhooks for an enhanced user experience. We provide web and mobile SDKs to render the widget in your app and a backend Node SDK for performing server-side functions.

## Components for on-ramp integrations

| Component                                                             | Features                                                                                                                                                                                                                                             |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [URL integration](/widget/off-ramp-how-to-integrate-using-simple-url) | An alternative to using our SDKs Generate MoonPay widget links to show the widget in an iframe                                                                                                                                                       |
| [Web SDKs](/widget/off-ramp-web-sdk)                                  | [Parameters](/widget/off-ramp-how-to-integrate-using-sdk) to pre-fill cryptocurrency, fiat currency, crypto amount, user email, etc. Includes [communication layer](/widget/off-ramp-sdk-events-details) between partner apps and the MoonPay widget |
| [Mobile SDKs](/widget/off-ramp-react-native-sdk)                      | React Native SDK                                                                                                                                                                                                                                     |
| [Node SDK](/widget/off-ramp-node-sdk)                                 | Perform server-side functions, like [URL signing](/widget/off-ramp-enhance-security-using-signed-urls)                                                                                                                                               |
| [MoonPay API](/api-reference/widget)                                  | Get minimum / maximum sell amounts Get sell quote Show transaction history                                                                                                                                                                           |
| [Webhooks](/api-reference/widget)                                     | Get transaction updates                                                                                                                                                                                                                              |

## High-level diagram

This diagram shows a basic crypto sell flow and the components required for implementation. We recommend using our API and webhooks to provide helpful context in your app, including minimum / maximum sell amounts, quotes, and transaction history.

<Frame>
  <img alt="Architecture" />
</Frame>


# URL signing
Source: https://dev.moonpay.com/widget/off-ramp-enhance-security-using-signed-urls

Protecting your sensitive data

MoonPay is highly committed to security. For this reason, whenever sensitive information such as emails or wallet addresses are transmitted to the widget, you are required to use the parameter, otherwise, the MoonPay widget . This measure makes it more difficult for unauthorized third parties to misuse the the widget's pre-fill feature.

A signed URL helps limit access from unauthorized third parties by providing limited permissions and time to make a request. Passing the `signature` parameter is mandatory if you're using the `walletAddress` or `walletAddresses` parameter and it must be appended at the end of the URL. If your widget URL contains sensitive information, we strongly recommend using the `signature` parameter.

You can generate a `signature` of the URL server-side and append it to the end of the URL. If the `signature` is provided, we'll check the validity of the query string to make sure it has not been altered. If the signature is invalid for any reason the MoonPay widget will fail to load.

## How to sign URLs

Follow these steps for signing URLs:

1. Send your widget URL to your backend server.
2. Generate the signature using the secret key found in your [MoonPay dashboard](https://dashboard.moonpay.com/developers/).
   * Use your own code to generate signatures and sign URLs
   * Alternatively, use [our Node SDK](/widget/on-ramp-node-sdk) to generate signatures, sign URLs, and validate signatures.
3. Return either the signature or entire signed URL.
   * **If using a SDK**, return the signature and use `updateSignature`. Do not encode the signature, as the SDK handles this.
   * **If using a URL-based integration**, return the entire signed URL. Ensure that the value of `signature` and other parameters are URL-encoded.
4. Show the widget using the SDK or URL.

<Info>
  **Returning the signature vs entire signed URL**

  **Integrations using an SDK**: Return the signature by itself and use `updateSignature`

  **Integrations using URLs**: Return the entire signed URL
</Info>

## How to generate signatures

1. Create an HMAC (Hash-Based Message Authentication Code) using the SHA-256 hash function.
   1. Use your secret API key as the key and the original URL's query string as the message.
2. For URL-based integrations, make sure all query parameter values are URL-encoded before creating the signature.

<Info>
  All query parameter *values* (not the entire query string) need to be
  URL-encoded before generating the signature in order for it to be valid.
</Info>

## Code examples

### Integrations using an SDK

Integrations using a web or mobile SDK should calculate the signature, then return the signature by itself, not URL-encoded.

More details about signing with each SDK:

* [Web SDK](/widget/on-ramp-web-sdk#signing)
* [React SDK](/widget/on-ramp-react-sdk#url-signing)
* [React Native SDK](/widget/on-ramp-react-native-sdk#initialize)

<CodeGroup>
  ```typescript Node.js theme={null}
  import crypto from 'crypto';

  const secretKey = 'sk_test_key'; // Use your secret key

  const generateSignature = (url) => {
  const signature = crypto
  .createHmac('sha256', secretKey)
  .update(new URL(url).search) // Use the query string part of the URL
  .digest('base64'); // Convert the result to a base64 string

      console.log(signature) // Print the signature
      return signature // Return the signature

  };
  ```

  ```php PHP theme={null}
  <?php
    $host = 'https://buy-sandbox.moonpay.com';  // Base URL
    $query = '?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae';  // Query parameters

    $secretKey = 'sk_test_key';  // Your secret key

    // Create the HMAC SHA-256 hash and encode it in base64
    $signature = base64_encode(hash_hmac('sha256', $query, $secretKey, true));

    echo $signature;  // Print the signature
  ?>
  ```
</CodeGroup>

### Integrations using URLs

Integrations generating widget URLs should calculate the signature, URL-encode the signature, then return the whole signed URL.

<CodeGroup>
  ```typescript Node.js theme={null}
  import crypto from 'crypto';

  const originalUrl = '<https://buy-sandbox.moonpay.com?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae>';

  const signature = crypto
  .createHmac('sha256', 'sk_test_key') // Use your secret key
  .update(new URL(originalUrl).search) // Use the query string part of the URL
  .digest('base64'); // Convert the result to a base64 string

  const urlWithSignature = `${originalUrl}&signature=${encodeURIComponent(signature)}`; // Add the signature to the URL

  console.log(urlWithSignature); // Print the signed URL
  ```

  ```php PHP theme={null}
  <?php
    $host = 'https://buy-sandbox.moonpay.com';  // Base URL
    $query = '?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae';  // Query parameters

    $secretKey = 'sk_test_key';  // Your secret key

    // Create the HMAC SHA-256 hash and encode it in base64
    $signature = base64_encode(hash_hmac('sha256', $query, $secretKey, true));

    // URL encode the signature
    $encodedSignature = urlencode($signature);

    // Combine the base URL, query parameters, and the signature
    $signedUrl = $host . $query . "&signature=" . $encodedSignature;

    echo $signedUrl;  // Print the signed URL
  ?>
  ```
</CodeGroup>

<Warning>
  Attention: The API gateway of some cloud providers change your parameter's
  order, resulting in a failed signature validation.
</Warning>


# FAQ
Source: https://dev.moonpay.com/widget/off-ramp-faq



## Off-Ramp integration

### How do I change my API Keys?

Go to the [Developers > API Keys](https://dashboard.moonpay.com/developers/) page of your MoonPay dashboard and hit the roll button next to the API key you wish to replace. You will be given the option to immediately delete the old key or a 12hour rollover before the old API keys expire.

### Iframe shows an error instead of the widget

If you see a CSP error that says `sell.moonpay.com refused to connect`, you’ll need to allowlist your production domain(s). We require this when you embed the MoonPay widget in an iframe or use the overlay, drawer, or embedded options to prevent unauthorized third-parties from embedding the MoonPay widget.

To resolve the issue, add your production domain(s) to the [Settings page](https://dashboard.moonpaycloud.com/settings/) of your MoonPay dashboard.

<Frame>
  <img alt="CSP Error" />
</Frame>

### Region-based widget error

If you see a widget error that geo-blocks certain users, confirm that these users are in a region supported by MoonPay. [Non-supported countries for off-ramp](https://support.moonpay.com/hc/en-gb/articles/360013742837-Which-cryptocurrencies-can-I-sell-)

### Sandbox supported currencies

Our sandbox environment supports a limited selection of testnet currencies; we recommend testing primarily with Ethereum on Sepolia or the Bitcoin testnet.

### Multiple accounts in production

In our production environment, we only allow one account per user. Creating multiple accounts in production may cause your account to be flagged or blocked.

### Test credit cards and KYC info in production

Only genuine card and KYC information may be used in our production environment. Do **not** use test credit card or test KYC information in production, as this will result in your account being blocked.

### How many block confirmations does MoonPay require before processing/confirming receipt of my crypto? (Off-Ramp)

| code           | confirmationsRequired |
| -------------- | --------------------- |
| avax\_cchain   | 2                     |
| axs            | 12                    |
| bch            | 1                     |
| bnb\_bsc       | 14                    |
| btc            | 1                     |
| busd\_bsc      | 15                    |
| eth            | 12                    |
| eth\_arbitrum  | 5                     |
| eth\_immutable | 1                     |
| eth\_polygon   | 12                    |
| ltc            | 6                     |
| sol            | 1                     |
| trx            | 12                    |
| usdc           | 11                    |
| usdc\_polygon  | 12                    |
| usdt           | 12                    |
| usdt\_trx      | 12                    |
| xlm            | 1                     |

## Using platforms like Flutter

MoonPay does not offer an SDK for Flutter. You'll have to manually embed our widget in a WebView. Consider the following tips:

* You can create your own HTML that uses our [Web SDK](/widget/on-ramp-web-sdk) to embed our Widget. This will allow you to receive our Widget's events, if you wish. You'll then need to send them out to your Flutter app layer.
* If you're experiencing camera issues in Flutter's WebView, consider using the Flutter plugin compatible with our Web SDK, available at [https://pub.dev/packages/flutter\_inappwebview](https://pub.dev/packages/flutter_inappwebview).
* You can find further guidance on configuring Flutter camera permissions and other related documentation at [https://inappwebview.dev/docs/5.x.x/web-rtc/](https://inappwebview.dev/docs/5.x.x/web-rtc/).
* Custom Origin via `baseUrl` Property: For specific requirements, you can set a custom origin using the `baseUrl` property. This serves as the base URL for any relative paths in the HTML and sets the document's origin. Example:

```dart theme={null}
InAppWebView(
  initialData: InAppWebViewInitialData(
    data: htmlContent,
    baseUrl: Uri.parse("https://your.custom.origin"),
  ),
  // ... other configurations ...
)
```

This custom origin approach can be advantageous for scenarios involving scripts that validate the document's origin or for CORS policies. We recommend using `https://app_name`, `capacitor://` or equivalent as your custom origin for the `baseUrl` property. From here, add the domain to your allowlist in the settings page of your [MoonPay dashboard](https://dashboard.moonpay.com/settings/).

***

## App requirements for KYC

<Warning>
  When not using a MoonPay SDK, make sure that the following requirements are
  met so that users can successfully complete KYC (Know Your Customer) steps.
</Warning>

These requirements make sure that customers can complete each KYC step, including uploading documents and doing a selfie check. Failing to follow these steps will cause new customers to drop off, as they won't be able to finish KYC or make a purchase.

### General app requirements for all implementations

All partner apps should ensure the following:

* [ ] `Feature-Policy` header for your webpage / frame or any other container has no restrictions for initializing camera like value `camera 'none'`.
* [ ] `Permissions-Policy` header doesn't restrict access to a camera and microphone (for some cases) and if allow is set check for `"camera; microphone"` values.
* [ ] When using [iOS WKWebview](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/1614793-allowsinlinemediaplayback) you may need to set `allowsInlineMediaPlayback` to `true` in the `WKWebViewConfiguration` used in your app. This adjustment ensures that media content, like a camera feed, can be displayed properly within the web view, rather than forcing full-screen playback.
* [ ] Your website is being run on a secure `https` connection.

### WebView requirements

Partner apps that use `WebView` should ensure the following:

* [ ] The web view is able to access device local storage and initialize camera (for older iOS versions, the camera can be accessed only from Safari browser or WebView with `SFSafariViewController`)
* [ ] HTML5 video playback is allowed (`<video>` tags are being used to send instructions): if video-instructions are not played, try using `WebChromeClient` to enable video playback
* [ ] Autoplay in fullscreen mode is disabled and `allowsInlineMediaPlayback` is set as `true` for WebView
* [ ] The selector file is implemented on your side (required for KYC document uploads)

### Iframe requirements

Partner apps that use `iframe` should ensure the following:

* [ ] Parent page header has no restrictions for initializing the camera, e.g. `camera=()`
  * [ ] Parent page can alternatively include `camera=*` in the Permissions-Policy header

* [ ] The iframe allow property has `allow="accelerometer; autoplay; camera; encrypted-media; gyroscope; payment"`

## Payments

### Supported Off-Ramp cryptocurrencies by region

List of all MoonPay supported assets for [SELL/Off-Ramp](https://support.moonpay.com/customers/docs/moonpays-supported-currencies#selling-crypto).

### Which fiat currencies can users off-ramp with?

We enable payouts in the following fiat currencies:

* USD (United States Dollar)
* GBP (British Pound Sterling)
* EUR (Euro)

### How do you handle chargebacks?

At MoonPay, we treat chargebacks seriously and have processes in place to prevent and handle chargebacks. For more information reach out to your MoonPay account representative.

### When are funds refunded to the refund wallet address vs. being returned to the sender’s address?

If MoonPay receives the user’s cryptocurrency and the deposit is valid (correct amount, token, and network), but the sell transaction later fails due to an on MoonPay's side, the funds will be returned to the `refundWalletAddress` passed in the widget, as long as it’s safe to do so.

However, if the deposit is invalid due to user error such as wrong token, network, or amount, or if the user cancels the transaction before the deposit is confirmed, the funds will automatically be returned to the sender’s address.

### How do I get paid?

Details can be found on our MoonPay documentation [here](https://support.moonpay.com/hc/en-gb/articles/4406209996049-How-do-affiliate-payouts-work-).

### What are my sell limits?

Sell limits will vary by region, currency and level of Know Your Customer KYC documents provided. Additional details can be found on our customer support page [here](https://support.moonpay.com/hc/en-gb/sections/360002592157-Verifications-Limits-).

### What cryptocurrencies does MoonPay support?

There are more limitations for US users than non-US users. A complete list can be found [here](https://support.moonpay.com/hc/en-gb/articles/360009280177-Which-cryptocurrencies-do-you-support-).

### I'm having trouble adding my credit/debit card to my account?

Double check you are not in our sandbox environment. Genuine cards should never be added to sandbox accounts.

Has your card already been added to another account? There is a limit of one card per account. Either use the other account or try using another card.

### Any recommended best practices for the Off-Ramp integration?

Yes, you can find our recommended best practices [documented here](/widget).


# Overview
Source: https://dev.moonpay.com/widget/off-ramp-how-to-integrate-using-sdk

We have SDKs for all your tech stacks. Pick the one that is right for you.

## Web SDKs: [Web](/widget/off-ramp-web-sdk), [React](/widget/off-ramp-react-sdk), [Node.js](/widget/off-ramp-node-sdk)

## Mobile SDK: [React Native](/widget/off-ramp-react-native-sdk)


# URL Integration
Source: https://dev.moonpay.com/widget/off-ramp-how-to-integrate-using-simple-url

You can use the below pre-written code to quickly get started on adding a Sell Crypto button that opens the MoonPay widget in a new browser tab.

<Tabs>
  <Tab title="Sandbox">
    **URL**: `https://sell-sandbox.moonpay.com/?apiKey=pk_test_123`

    <CodeGroup>
      ```html sandbox.html theme={null}
      <!--Opens the MoonPay widget in a new browser tab-->
      <body>
          <div class="container">
              <button onclick="window.open('https://sell-sandbox.moonpay.com/?apiKey=pk_test_123', '_blank')">Buy with MoonPay</button>
          </div>
      </body>
      ```

      ```css sandbox.css theme={null}
      .container {
      background-color: #392a54;
      padding: 20px;
      text-align: center;
      }

      button {
      background-color: #7d00fe;
      border: none;
      color: white;
      padding: 15px 50px;
      font-size: 16px;
      cursor: pointer;
      border-radius: 4px;
      background-image: url("https://images.crunchbase.com/image/upload/c_lpad,h_170,w_170,f_auto,b_white,q_auto:eco,dpr_1/jglje7ar0xc6j5lvai6t");
      background-repeat: no-repeat;
      background-position: right center;
      background-size: contain;
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Production">
    **URL**: `https://sell.moonpay.com/?apiKey=pk_live_123`

    <CodeGroup>
      ```html sandbox.html theme={null}
      <!--Opens the MoonPay widget in a new browser tab-->
      <body>
          <div class="container">
              <button onclick="window.open('https://sell.moonpay.com/?apiKey=pk_live_123', '_blank')">Buy with MoonPay</button>
          </div>
      </body>
      ```

      ```css sandbox.css theme={null}
      .container {
      background-color: #392a54;
      padding: 20px;
      text-align: center;
      }

      button {
      background-color: #7d00fe;
      border: none;
      color: white;
      padding: 15px 50px;
      font-size: 16px;
      cursor: pointer;
      border-radius: 4px;
      background-image: url("https://images.crunchbase.com/image/upload/c_lpad,h_170,w_170,f_auto,b_white,q_auto:eco,dpr_1/jglje7ar0xc6j5lvai6t");
      background-repeat: no-repeat;
      background-position: right center;
      background-size: contain;
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Here's an example. Give it a try

<ExampleButtonSell />


# Node.js SDK
Source: https://dev.moonpay.com/widget/off-ramp-node-sdk



## Install

```bash theme={null}
npm install @moonpay/moonpay-node
```

View the package on [npm](https://www.npmjs.com/package/@moonpay/moonpay-node?activeTab=code).

## Setup

First, import the `MoonPay` class.

```typescript theme={null}
import { MoonPay } from '@moonpay/moonpay-node`;
```

Set up the `MoonPay` class with your secret key.

<Warning>
  NEVER use your secret key in client side code. Load your secret key from an environment variable instead.
</Warning>

```typescript theme={null}
const moonPay = new MoonPay("sk_test_...");
```

## Usage

Use the `moonPay` instance to access our functions.

### URL utilities

MoonPay URL utilities are namespaced under the `.url` property.

#### Signing your URL

If you include the `walletAddress` or `walletAddresses` query param, you'll need to sign the URL.

```typescript theme={null}
const signature = moonPay.url.generateSignature(
  "https://buy.moonpay.com/?apiKey=pk_test_123&walletAddress=...",
);
```

Or, return the signed URL, using the `returnFullURL` option.

```typescript theme={null}
const signedURL = moonPay.url.generateSignature(
  "https://buy.moonpay.com/?apiKey=pk_test_123&walletAddress=...",
  { returnFullURL: true },
);
```

#### Verifying a signature

Or, you can verify that a URL is correctly signed.

```typescript theme={null}
const isSignatureValid = moonPay.url.isSignatureValid(
  "[...]/?apiKey=pk_test_123&signature=someSignature",
);
```

#### Generating a signed URL

You can also have us generate the full, signed URL, based on some input parameters.

```typescript theme={null}
const params = {
  apiKey: "pk_test_123",
  baseCurrencyCode: "GBP",
};

const url = moonPay.url.generate({ flow: "buy", params });
```

## Example

Here's an example of an Express endpoint that signs a URL query param.

```typescript theme={null}
import express from "express";
import { MoonPay } from "@moonpay/moonpay-node";

const moonPay = new MoonPay("sk*test*...");
const app = express();

app.get("/moonpay_signature", (req, res) => {
  const { url } = req.query;
  const signature = moonPay.url.generateSignature(url);
  res.send({ signature });
});

app.listen(3000, () => console.log("Listening on port 3000!"));
```


# Overview
Source: https://dev.moonpay.com/widget/off-ramp-overview

MoonPay is the leading ramps provider in the space and continues to be the most popular gateway for crypto and NFT applications across the world. With the MoonPay fiat-to-crypto onramp users can seamlessly purchase cryptocurrencies directly from your website or web3 application.

<Info>
  Want to get a head-start on your integration? The **[MoonPay Demo
  Integrations](https://github.com/moonpay/moonpay-demo-integrations)** GitHub
  repository has working, clone-able example integrations ready to use - just
  add your API keys.
</Info>

## Off-Ramp user flow

Using our SDKs, there are several options to integrate MoonPay widget. For example, in a modal overlaid on top of your web app, or in an in-app web view.

To sell crypto, the user goes through the following steps in the widget:

1. Confirm the cryptocurrency, fiat, and amount to sell.
2. Log in to the widget using multi-factor authentication (MFA).
3. Select payout method.
4. Go through KYC, if the user is new to MoonPay.
5. Confirm the sale.
6. Recommended User confirms the crypto deposit in the partner app.
7. Partner app sends crypto on behalf of the user.

### Try the Off-Ramp flow in our sandbox environment

<iframe title="Sandbox" />

## Features

**Secure Crypto Transactions**: Our system supports 100+ cryptocurrencies and as the merchant of record MoonPay assumes full responsibility for all fraud disputes and chargebacks. All customers are required to pass MoonPay’s established Know Your Customer (KYC) and risk management procedures along with all applicable laws and regulations.

**Optimal conversion rates**: Millions of users have previously purchased cryptocurrencies using MoonPay, having stored their payment and KYC details, leading to maximized conversion rates.

**Diverse payment methods**: MoonPay accommodates a vast spectrum of payment methods for purchase and sale transactions: credit and debit cards, EUR, GBP, USD bank transfers, as well as Apple & Google Pay, ensuring users can transact according to their preference.

### Customize the widget

You can customize the widget to feel like a native part of your site or application by adjusting button and background colors. You can also add your company logo to the transactional emails sent to customers.

<Frame>
  <img alt="Customize on mobile" />
</Frame>

<Frame>
  <img alt="Emails" />
</Frame>

### Remove friction for your users

Improve your customers experience and speed things up by pre-filling information such as their wallet address, email, selected token, fiat currency, amounts, and their preferred payment method. Users don't have a digital wallet? We can create one for them using just their email address as they go through the purchase flow.

Through Single Sign-On, users can effortlessly log in using their Google or Apple accounts directly from the widget, serving as a smooth connector between the traditional web (Web 2.0) and blockchain-based platforms (Web 3.0).

For an in-depth look at customization features like pre-populating user information or altering the widget button's color, please visit our [off-ramp parameters page](/widget/ramps-sdk-sell-params).

## Supported currencies and regions

Review the following Support articles to see our supported currencies and regions for off-ramp:

* [Supported cryptocurrencies](https://support.moonpay.com/customers/docs/list-of-supported-cryptocurrencies)
* [Supported fiat currencies](https://support.moonpay.com/customers/docs/moonpays-supported-currencies#buying-crypto)
* [Unsupported regions](https://support.moonpay.com/customers/docs/moonpays-unsupported-countries)


# Quickstart
Source: https://dev.moonpay.com/widget/off-ramp-quickstart



## Overview

<Frame>
  <img alt="Overview" />
</Frame>

In this Quickstart, you will facilitate the sale of cryptocurrency via the MoonPay Off-Ramp, directly from your browser.

Whether you are a complete beginner to coding or a seasoned expert, this guide will take you through all of the necessary steps to have you converting cryptocurrency to fiat in no time.

***

## What you will accomplish

In this tutorial, you will:

* Configure Off-Ramps widget in a local environment
  * Create a new folder for the implementation
  * Initialize the widget in a file using HTML and JavaScript
  * Edit the widget parameters
  * Display the fully functional widget locally in your browser

***

## Prerequisites

Before beginning, you will need:

* **A MoonPay account**: If you do not have one, set one up through our team on [this page](https://dashboard.moonpay.com/signup).
* **An IDE (coding software):** Some popular ones are [Visual Studio](https://visualstudio.microsoft.com/downloads/), [IntelliJ IDEA](https://www.jetbrains.com/idea/), and [Eclipse](https://eclipseide.org/). We will be using Visual Studio in this tutorial.
* **A web browser:** Any web browser will work. We will be using Google Chrome in this tutorial.

***

## Implementation

### Step 1: Set up a file for your integration

In your IDE, create a new file for your On-Ramp code. Ours will be called `off-ramp.html`.

### Step 2: Retrieve API keys from the MoonPay Dashboard

* Navigate to your [MoonPay Dashboard](https://dashboard.moonpay.com/) and log in.
* Once logged in, navigate to the Developers tab on the sidebar → API Keys.
  * Here, you will be able to copy your API keys. In this tutorial, we will be using the publishable test key.

<Frame>
  <img alt="Dashboard" />
</Frame>

### Step 3: Insert HTML and code into off-ramp.html

* The code below will embed our Software Development Kit (SDK) directly into your HTML by way of `<script>` tags.
* You can think of this as a way of injecting code directly into HTML without having to create a separate linked file.

```html off-ramp.html theme={null}
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>MoonPay Integration</title>

    <!-- Adds the MoonPay SDK as a script to your HTML file -->
    <script
      defer
      src="https://static.moonpay.com/web-sdk/v1/moonpay-web-sdk.min.js"
    ></script>

    <!-- Initialize the MoonPay SDK immediately upon page load -->
    <script>
      document.addEventListener("DOMContentLoaded", () => {
        const moonpaySdk = window.MoonPayWebSdk.init({
          flow: "sell",
          environment: "sandbox",
          variant: "overlay",
          params: {
            apiKey: "pk_test", // Replace with your MoonPay publishable test API key
            baseCurrencyCode: "eth",
            baseCurrencyAmount: ".15",
            defaultBaseCurrencyCode: "eth",

            quoteCurrencyCode: "usd",
          },
        });

        // Open widget
        moonpaySdk.show();
      });
    </script>
  </head>

  <body>
    <div class="container"></div>
  </body>
</html>
```

* This script will detect when the HTML page loads and immediately run the JavaScript within the `<script>` tags when the load has finished. Remember to replace `pk_test` with your publishable test API key from **Step 1**.

* You can customize widget functionality (currencies, amounts, etc.) by adding and removing parameters in the JavaScript, whilst still preserving proper formatting.
  * All parameters can be found on [this page of our documentation](https://moonpay.readme.io/docs/off-ramp-how-to-configure-user-journey-params).

* For example, if we would like to display the widget with a default of selling *.05 BTC to EUR*, and set `lockAmount` to `true` in the parameters so that the user cannot modify the sell amount, we could modify the JavaScript like such:

  ```html off-ramp.html theme={null}
  <script>
    document.addEventListener("DOMContentLoaded", () => {
      const moonpaySdk = window.MoonPayWebSdk.init({
        flow: "sell",
        environment: "sandbox",
        variant: "overlay",
        params: {
          apiKey: "pk_test", // Replace with your MoonPay publishable test API key
          baseCurrencyCode: "btc",
          baseCurrencyAmount: ".05",
          defaultBaseCurrencyCode: "btc",
          quoteCurrencyCode: "eur",
          lockAmount: "true",
        },
      });

      // Open widget
      moonpaySdk.show();
    });
  </script>
  ```

### Step 4: Do a test transaction

* The first step of processing a test transaction using the MoonPay Off-Ramp is to make sure that `environment` is set to`"sandbox"`, as shown above in the example code. This puts your widget in test mode.
* Next, open up the widget, enter your email address, and log in.

<Frame>
  <img alt="Dashboard" />
</Frame>

* You will be prompted to configure your Sell transaction. Use [our test credit card for off-ramp payouts](/widget/faq-sandbox-testing#test-card-for-off-ramp-payouts) when prompted for a payout method.
* You'll eventually arrive at the below screen. Click on “View deposit details”.

<Frame>
  <img alt="Dashboard" />
</Frame>

* You will now see the below screen, prompting you to send the previously specified amount of cryptocurrency to a wallet on the corresponding blockchain. Click the “I’ve sent my crypto” button.

<Frame>
  <img alt="Dashboard" />
</Frame>

* When successful, you will see green checks on the Pending, Processing, and Sent pages! ✅

## Completion

Congratulations, you have just integrated the MoonPay Off-Ramp 🎉

Any questions? Feel free to visit our [Help Center](https://support.moonpay.com/hc/en-gb/categories/360001595097-Customer-Support-Help-Center) to dig into our other resources or drop us a line!


# React Native SDK
Source: https://dev.moonpay.com/widget/off-ramp-react-native-sdk



## Install

Install the official MoonPay package.

```bash theme={null}
npm install --save @moonpay/react-native-moonpay-sdk
```

### Install dependencies

Assuming you already installed `react` and `react-native` you need to install and configure `react-native-webview`.

```bash theme={null}
npm install --save react-native-webview
```

We also highly recommend to install the following polyfill to prevent any issues with URL formatting:

```bash theme={null}
npm install --save react-native-url-polyfill
```

## In-App Browser Implementation

You no longer need to install `expo-web-browser` or `react-native-inappbrowser-reborn` as optional dependencies. Instead, partners are now required to provide their own in-app browser implementation when using the MoonPay SDK. You can either use `expo-web-browser`, `react-native-inappbrowser-reborn`, or any standalone in-app browser of your choice. Alternatively, you can create a wrapper to manage the in-app browser you prefer to use.

## Initialize

Initialize the SDK in your application with the flow, environment and any parameters related to [Buy](/widget/ramps-sdk-buy-params), [Sell](/widget/ramps-sdk-sell-params) or Swap. Additionally you can choose to render the widget either as an in-app browser or a webview. If you're using the `walletAddress` or `walletAddresses` query param, you need to sign your widget URL before you can display the widget. Learn more about [URL signing](/widget/on-ramp-enhance-security-using-signed-urls).

**How to choose?**

* An `In-app browser` will allow you to use native features like Google Pay, social sign-in and popups.
* A `Webview` will allow you to use a communication layer between the widget and your app and therefore get your app to perform certain actions once some events occur in the widget. Additionally it will give you infinite choices on how it might look like. You can add it to a bottom sheet, drawer, or as full-screen. It's entirely up to you.

See below In-App browser examples. For additional examples you can look on our [Github page here](https://www.npmjs.com/package/@moonpay/react-native-moonpay-sdk).

<CodeGroup>
  ```typescript In-app browser theme={null}
  import { View, Button, Text, useEffect } from "react-native";
  import { useMoonPaySdk } from "@moonpay/react-native-moonpay-sdk";

  const YourComponent = () => {
    const { openWithInAppBrowser, generateUrlForSigning, updateSignature } =
      useMoonPaySdk({
        sdkConfig: {
          flow: "buy",
          environment: "sandbox",
          params: {
            apiKey: "pk_test_key",
          },
        },
        browserOpener: {
          open: (url) => {
            // Use any in-app browser or standalone browser here
            // Example with custom browser implementation
          },
        },
      });

    useEffect(() => {
      // The URL for signature should be sent to your backend, which should then
      // sign it with your API secret and return the signature.
      // Once you have the signature, you can update the SDK with it and show the widget.
      fetch("/sign-url", {
        headers: {
          "Content-Type": "application/json",
          Authorization: "Bearer <token>",
        },
        method: "POST",
        body: JSON.stringify({
          url: generateUrlForSigning(),
        }),
      })
        .then((res) => res.json())
        .then((data) => {
          const signature = data.signature;
          updateSignature(signature);
        });
    }, []);

    return (
      <View>
        <Button onPress={() => openWithInAppBrowser()}>
          <Text>Open in InApp browser</Text>
        </Button>
      </View>
    );
  };
  ```

  ```typescript In-app browser (w/wrapper) theme={null}
  import { View, Button, Text, useEffect } from "react-native";
  import { useMoonPaySdk } from "@moonpay/react-native-moonpay-sdk";

  const InAppBrowserWrapper = {
    open: async (url) => {
      // Use any in-app browser method here
      InAppBrowser.open(url);
    },
  };

  const YourComponent = () => {
    const { openWithInAppBrowser, generateUrlForSigning, updateSignature } =
      useMoonPaySdk({
        sdkConfig: {
          flow: "buy",
          environment: "sandbox",
          params: {
            apiKey: "pk_test_123",
          },
        },
        InAppBrowser: InAppBrowserWrapper,
      });

    useEffect(() => {
      // The URL for signature should be sent to your backend, which should then
      // sign it with your API secret and return the signature.
      // Once you have the signature, you can update the SDK with it and show the widget.
      fetch("/sign-url", {
        headers: {
          "Content-Type": "application/json",
          Authorization: "Bearer <token>",
        },
        method: "POST",
        body: JSON.stringify({
          url: generateUrlForSigning(),
        }),
      })
        .then((res) => res.json())
        .then((data) => {
          const signature = data.signature;
          updateSignature(signature);
        });
    }, []);

    return (
      <View>
        <Button onPress={() => openWithInAppBrowser()}>
          <Text>Open in InApp browser</Text>
        </Button>
      </View>
    );
  };
  ```

  ```typescript WebView theme={null}
  import { View, Button, Text } from "react-native";
  import { useMoonPaySdk } from "@moonpay/react-native-moonpay-sdk";

  const YourComponent = () => {
    const { MoonPayWebView } = useMoonPaySdk({
      flow: "buy",
      environment: "sandbox",
      params: {
        apiKey: "pk_test_key",
      },
    });

    useEffect(() => {
      // This is just an example of how it might look like.
      // You may handle this differently.
      fetch("/sign-url", {
        headers: {
          "Content-Type": "application/json",
          Authorization: "Bearer <token>",
        },
        method: "POST",
        body: JSON.stringify({
          url: sdk.generateUrlForSigning(),
        }),
      })
        .then((res) => res.json())
        .then((data) => {
          const signature = data.signature;
          sdk.updateSignature(data);
        });
    }, []);

    return (
      <View>
        <MoonPayWebView />
      </View>
    );
  };

  ```
</CodeGroup>

### Configuration

* Possible values for `flow`: buy, sell, swap, swapsCustomerSetup
* Possible values for `environment`: sandbox, production


# React SDK
Source: https://dev.moonpay.com/widget/off-ramp-react-sdk



<Info>
  An example React On-Ramp integration can be found on our Github
  [here](https://github.com/moonpay/moonpay-demo-integrations).
</Info>

## Install

To integrate MoonPay in your React app, you can use MoonPay's `moonpay-react` package.

```bash theme={null}
npm install @moonpay/moonpay-react
```

Once you've installed this, you're ready to set up your project to integrate the MoonPay widget.

## Add the provider

The first thing to do is add the MoonPay provider to the root of your React application. This will provide context throughout your app to allow you to use the MoonPay widget components.

```typescript setup.ts theme={null}
import { MoonPayProvider } from "@moonpay/moonpay-react";

export default function App() {
  return (
    <MoonPayProvider apiKey="pk_test_123" debug>
      <Home />
    </MoonPayProvider>
  );
}
```

The provider abstracts the complexity of loading the SDK into your app.

Now, use your desired component, passing variant and any parameters related to [Buy](/widget/ramps-sdk-buy-params), [Sell](/widget/ramps-sdk-sell-params), or Swap as props.

The environment is set based on which API key you use. Use the following keys:

* Sandbox environment: `pk_test...`
* Production environment: `pk_live...`

<CodeGroup>
  ```typescript Buy theme={null}
  import { MoonPayBuyWidget } from '@moonpay/moonpay-react';

  export default function Home() {
    return (
      {/*... other components */}
      <MoonPayBuyWidget
        variant="overlay"
        baseCurrencyCode="usd"
        baseCurrencyAmount="100"
        defaultCurrencyCode="eth"
        onLogin={async () => console.log("Customer logged in!")}
        visible
      />
      {/* ... other components*/}
    )
  }

  ```

  ```typescript Sell theme={null}
  import { MoonPaySellWidget } from '@moonpay/moonpay-react';

  export default function Home() {
    return (
      {/* ... other components */}
      <MoonPaySellWidget
        variant="overlay"
        baseCurrencyCode="eth"
        baseCurrencyAmount="0.045"
        visible
      />
      {/* ... other components */}
    )
  }
  ```

  ```typescript Swap theme={null}
  import { MoonPaySwapWidget } from '@moonpay/moonpay-react';

  export default function Home() {
    return (
      {/* ... other components */}
      <MoonPaySwapWidget variant="overlay" visible />
      {/* ... other components */}
    )
  }
  ```

  ```typescript Swap (w/customer setup) theme={null}
  import { MoonPaySwapsCustomerSetupWidget } from '@moonpay/moonpay-react';

  export default function Home() {
    return (
      {/* ... other components */}
      <MoonPaySwapsCustomerSetupWidget
        variant="overlay"
        amount="300"
        amountCurrencyCode="usd"
        onAuthToken={async ({ token }) => {
          // Once the customer has logged in in the widget, we share their
          // swaps-scoped authentication token with your app so you can
          // perform swaps requests on behalf of the customer.
          // The token needs to be passed as an Authorization header in the format
          // "Authorization: Bearer {token}".
          console.log("onAuthToken received with token:", token);
        }}
        onSwapsCustomerSetupComplete={async () => {
          // When this is received, you can close the widget and resume the
          // the swap flow in your UI.
          console.log("onSwapsCustomerSetupComplete received");
        }}
        visible
      />
      {/* ... other components */}
    )
  }
  ```
</CodeGroup>

### For Next.js

For Next.js, it's recommended to dynamically import the MoonPay components as shown below. This ensures efficient loading of the components and prevents server-side rendering (SSR). Otherwise you will see an error message: `ReferenceError: window is not defined`

```typescript theme={null}
import dynamic from "next/dynamic";

const MoonPayProvider = dynamic(
  () => import("@moonpay/moonpay-react").then((mod) => mod.MoonPayProvider),
  { ssr: false },
);

const MoonPayBuyWidget = dynamic(
  () => import("@moonpay/moonpay-react").then((mod) => mod.MoonPayBuyWidget),
  { ssr: false },
);
```

## Variants

### Embedded

The `embedded` variant shows the MoonPay widget will show as part of your page, wherever you place the component. This option lets you fine-tune the placement of the widget and allows you to integrate it into a specific part of your layout. This can minimize context switching for the user.

### Overlay

The `overlay` variant shows the widget as an iframe on top of your website. This option directs the user's attention towards completing their purchase while keeping them on your website.

### New tab

The `newTab` variant opens the widget in a new browser tab. This option lets the user complete their purchase in a full-screen experience. When using this option, we recommend you tell the user they'll be taken to MoonPay in a new tab. This provides guidance to the user that this is intended and part of the purchase flow.

### New window

The `newWindow` variant opens the widget in a new browser window with a fixed size. This variant is ideal if you want to provide a more controlled experience for the user while they complete their purchase.

## Display

You might want to control whether the SDK is showing based on some application state. This is there the `visible` prop comes into play. Using the `visible` prop ensures that the widget is properly shown and cleaned up as necessary. As a light example, here is how one could add a button to toggle the SDK embedded variant.

<CodeGroup>
  ```typescript highlight={13} Buy theme={null}
  import { MoonPayBuyWidget } from "@moonpay/moonpay-react";

  export default function Home() {
    const [visible, setVisible] = useState(false);

    return (
      <>
        <MoonPayBuyWidget
          variant="overlay"
          baseCurrencyCode="usd"
          baseCurrencyAmount="100"
          defaultCurrencyCode="eth"
          visible={visible}
        />
        <button onClick={() => setVisible(!visible)}>Toggle widget</button>
      </>
    );
  }
  ```

  ```typescript highlight={12} Sell theme={null}
  import { MoonPaySellWidget } from "@moonpay/moonpay-react";

  export default function Home() {
    const [visible, setVisible] = useState(false);

    return (
      <>
        <MoonPaySellWidget
          variant="overlay"
          baseCurrencyCode="eth"
          baseCurrencyAmount="0.045"
          visible={visible}
        />
        <button onClick={() => setVisible(!visible)}>Toggle widget</button>
      </>
    );
  }
  ```
</CodeGroup>

## URL signing

If you're using the `walletAddress` or `walletAddresses` query param, you need to sign your widget URL before you can display the widget. Learn more about [URL signing](/widget/on-ramp-enhance-security-using-signed-urls).

Each of our React components provides an `onUrlSignatureRequested` prop that takes an asynchronous function which is called whenever the URL is updated. It takes an argument of the current URL and the return value should be your generated signature, acquired by some means from your backend by signing the given URL. The widget then takes this returned signature and updates its URL to include it.

```typescript theme={null}
import { MoonPayBuyWidget } from "@moonpay/moonpay-react";

const handleGetSignature = async (url: string): Promise<string> => {
  const signature = await fetch(
    `https://YOUR_API_DOMAIN.com/sign-url?url=${url}`,
  );
  return signature;
};

export default function Home() {
  return (
    <>
      <MoonPayBuyWidget
        variant="overlay"
        baseCurrencyCode="usd"
        baseCurrencyAmount="100"
        defaultCurrencyCode="eth"
        onUrlSignatureRequested={handleGetSignature}
        visible
      />
    </>
  );
}
```


# SDK Ramp Events
Source: https://dev.moonpay.com/widget/off-ramp-sdk-events-details



## Interface: RampsChildToParentInterface

This interface represents the events that the Widget SDK can trigger from within the MoonPay Widget to partners' parent applications.

This allows partner apps to be informed and adapt to certain widget lifecycle events.

### Hierarchy

* `RampsSwapsKycChildToParentInterface`

  ↳ **`RampsChildToParentInterface`**

### Methods

#### `onAuthToken`

This event is only fired for those integrating with our Swaps (SDK+API) product.

`onAuthToken(props): Promise<void>`

Fired when the partner needs to receive an updated customer auth token so they can perform authorized actions on behalf of the customer.

**Parameters**

| Name    | Type                                                                         |
| ------- | ---------------------------------------------------------------------------- |
| `props` | [`OnAuthTokenProps`](/widget/on-ramp-sdk-events-properties#onauthtokenprops) |

**Returns**

`Promise<void>`

**Inherited from**

`RampsSwapsKycChildToParentInterface.onAuthToken`

#### `onClose`

`onClose(): Promise<void>`

Fired when the Widget is closing, triggered by either system logic or user actions.

**Returns**

`Promise<void>`

#### `onInitiateDeposit`

`onInitiateDeposit(props): Promise<OnInitiateDepositReplyProps>`

Called in the integrated sell flow, in the transaction tracker, when the widget is waiting for the sell amount to be deposited by the customer.

This allows the partner to trigger a deposit right from their wallet app.

**Parameters**

| Name    | Type                                                                                     |
| ------- | ---------------------------------------------------------------------------------------- |
| `props` | [`OnInitiateDepositProps`](/widget/on-ramp-sdk-events-properties#oninitiatedepositprops) |

**Returns**

`Promise`\<[`OnInitiateDepositReplyProps`](/widget/on-ramp-sdk-events-properties#oninitiatedepositreplyprops)>

#### `onLogin`

`onLogin(props): Promise<void>`

Fired when the customer logs in or their authentication is refreshed.

**Parameters**

| Name    | Type                                                                 |
| ------- | -------------------------------------------------------------------- |
| `props` | [`OnLoginProps`](/widget/on-ramp-sdk-events-properties#onloginprops) |

**Returns**

`Promise<void>`

#### `onReady`

`onReady(): Promise<void>`

Fired when the SDK's communication layer has been set up and the Widget is loaded.

**Returns**

`Promise<void>`

#### `onSwapsCustomerSetupComplete`

`onSwapsCustomerSetupComplete(): Promise<void>`

Fired when the Swaps Customer Setup flow has completed signaling to the parent app that the widget may now be closed.

**Returns**

`Promise<void>`

**Inherited from**

`RampsSwapsKycChildToParentInterface.onSwapsCustomerSetupComplete`

#### `onTransactionCreated`

`onTransactionCreated**(props): Promise<void>`

Fired when a buy or sell transaction is created, just before redirecting to the transaction tracker.

**Parameters**

| Name    | Type                                                                                           |
| ------- | ---------------------------------------------------------------------------------------------- |
| `props` | [`OnTransactionCreatedProps`](/widget/on-ramp-sdk-events-properties#ontransactioncreatedprops) |

**Returns**

`Promise<void>`

#### `onTransactionCompleted`

`onTransactionCompleted(props): Promise<void>`

Fired when a transaction is detected as completed or if a previously completed transaction is loaded again in the transaction tracker.

**Parameters**

| Name    | Type                                                                                               |
| ------- | -------------------------------------------------------------------------------------------------- |
| `props` | [`OnTransactionCompletedProps`](/widget/on-ramp-sdk-events-properties#ontransactioncompletedprops) |

**Returns**

`Promise<void>`

#### `onUnsupportedRegion`

`onUnsupportedRegion(): Promise<void>`

Fired when the Unsupported Region screen is triggered, independently of whether the widget redirects away from it.

**Returns**

`Promise<void>`


# SDK Event Properties
Source: https://dev.moonpay.com/widget/off-ramp-sdk-events-properties



## Interfaces

* [RampsChildToParentInterface](/widget/on-ramp-sdk-events-details#interface-rampschildtoparentinterface)

## Type Aliases

### CryptoCurrency

**CryptoCurrency**: `Object`

Represents a Crypto currency such as ETH

**Type declaration**

| Name              | Type               | Description                                                  |
| ----------------- | ------------------ | ------------------------------------------------------------ |
| `chainId`         | `string` \| `null` | The chain's Chain ID                                         |
| `code`            | `string`           | The code of the currency such as "eth"                       |
| `coinType`        | `string` \| `null` | The coin type as defined in SLIP-0044                        |
| `contractAddress` | `string` \| `null` | The address location of the token contract on the blockchain |
| `id`              | `string`           | The identifier of the crypto currency                        |
| `name`            | `string`           | The human readable name of the currency such as "Ethereum"   |
| `networkCode`     | `string` \| `null` | The currency's network such as "bitcoin" or "ethereum"       |

### FiatCurrency

**FiatCurrency**: `Object`

Represents a Fiat currency such as USD

**Type declaration**

| Name   | Type     | Description                                                 |
| ------ | -------- | ----------------------------------------------------------- |
| `code` | `string` | The code of the currency such as "usd"                      |
| `id`   | `string` | The identifier of the fiat currency                         |
| `name` | `string` | The human readable name of the currency such as "US Dollar" |

### OnAuthTokenProps

**OnAuthTokenProps**: `Object` This event is only fired for those integrating with our Swaps (SDK+API) product.

**Type declaration**

| Name        | Type     | Description                                                                    |
| ----------- | -------- | ------------------------------------------------------------------------------ |
| `csrfToken` | `string` | The customer's CSRF token. Only provided to authorized integrations.           |
| `token`     | `string` | The customer's authentication token. Only provided to authorized integrations. |

***

### OnInitiateDepositProps

**OnInitiateDepositProps**: `Object`

**Type declaration**

| Name                                       | Type                                                                     | Description                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `cryptoCurrency`                           | [`CryptoCurrency`](/widget/on-ramp-sdk-events-properties#cryptocurrency) | The crypto currency that is being off-ramped                                 |
| `cryptoCurrencyAmount`                     | `string`                                                                 | Crypto amount in its base unit (0.123 ETH === "0.123")                       |
| `cryptoCurrencyAmountSmallestDenomination` | `string`                                                                 | Crypto amount in its smallest unit (1 ETH === 1x10^18)                       |
| `depositWalletAddress`                     | `string`                                                                 | The wallet address where the crypto amount needs to be deposited             |
| `fiatCurrency`                             | [`FiatCurrency`](/widget/on-ramp-sdk-events-properties#fiatcurrency)     | The fiat currency that the customer will receive                             |
| `fiatCurrencyAmount`                       | `string` \| `null`                                                       | Fiat amount in its base unit (\$1.23 === "1.23"). Only set for fixed quotes. |
| `transactionId`                            | `string`                                                                 | The identifier of the transaction                                            |

### OnInitiateDepositReplyProps

**OnInitiateDepositReplyProps**: `Object`

**Type declaration**

| Name        | Type     | Description                                                                                    |
| ----------- | -------- | ---------------------------------------------------------------------------------------------- |
| `depositId` | `string` | The partner's identifier for a successful deposit. Can be any string, eg the transaction hash. |

### OnLoginProps

**OnLoginProps**: `Object`

**Type declaration**

| Name        | Type      | Description                                                                                 |
| ----------- | --------- | ------------------------------------------------------------------------------------------- |
| `isRefresh` | `boolean` | If true, the customer didn't actually log in but rather their authentication was refreshed. |

### OnTransactionCreatedProps

**OnTransactionCompletedProps**: `Object`

**Type declaration**

| Name                 | Type                                                                                                                                                                     | Description                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
| `baseCurrency`       | [`FiatCurrency`](/widget/on-ramp-sdk-events-properties#fiatcurrency)                                                                                                     | The base (fiat) currency              |
| `baseCurrencyAmount` | `number`                                                                                                                                                                 | The spent fiat amount                 |
| `id`                 | `string`                                                                                                                                                                 | The identifier of the transaction     |
| `status`             | [`TransactionStatus`](/widget/on-ramp-sdk-events-properties#transactionstatus) \| [`SellTransactionStatus`](/widget/on-ramp-sdk-events-properties#selltransactionstatus) | The current status of the transaction |

### OnTransactionCompletedProps

**OnTransactionCompletedProps**: `Object`

**Type declaration**

| Name                  | Type                                                                           | Description                                                         |
| --------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| `areFeesIncluded`     | `boolean`                                                                      | Whether the base currency amount includes fees                      |
| `baseCurrency`        | [`FiatCurrency`](/widget/on-ramp-sdk-events-properties#fiatcurrency)           | The base (fiat) currency                                            |
| `baseCurrencyAmount`  | `number`                                                                       | The spent fiat amount                                               |
| `createdAt`           | `string`                                                                       | When the transaction was created                                    |
| `extraFeeAmount`      | `number`                                                                       | The partner's fee amount, in the fiat currency                      |
| `feeAmount`           | `number`                                                                       | The MoonPay fee amount, in the fiat currency                        |
| `id`                  | `string`                                                                       | The identifier of the transaction                                   |
| `networkFeeAmount`    | `number`                                                                       | The network fees incurred in this transaction, in the fiat currency |
| `quoteCurrency`       | [`CryptoCurrency`](/widget/on-ramp-sdk-events-properties#cryptocurrency)       | The quote (crypto) currency                                         |
| `quoteCurrencyAmount` | `number`                                                                       | The expected or received quote amount                               |
| `status`              | [`TransactionStatus`](/widget/on-ramp-sdk-events-properties#transactionstatus) | The current status of the transaction                               |
| `walletAddress`       | `string`                                                                       | The customer's destination wallet address                           |
| `walletAddressTag`    | `string` \| `null`                                                             | The customer's destination wallet address tag                       |

### TransactionStatus

**TransactionStatus**: `"completed"` | `"failed"` | `"pending"` | `"waitingAuthorization"` | `"waitingPayment"`

### SellTransactionStatus

**SellTransactionStatus**: `"completed"` | `"failed"` | `"pending"` | `"waitingForDeposit"`


# Web SDK
Source: https://dev.moonpay.com/widget/off-ramp-web-sdk



<Info>
  An example Web SDK On-Ramp integration can be found on our Github [right
  here](https://github.com/moonpay/moonpay-demo-integrations/tree/main).
</Info>

## Import

There are two options when integrating the web SDK.

You can load the SDK using the `script` tag approach, or if you prefer an npm package with full type-safety, you can use [moonpay-js](https://www.npmjs.com/package/@moonpay/moonpay-js). Both approaches provide the same level of end functionality, so which one you choose will be based on your preference and what works best for your project.

<CodeGroup>
  ```bash Install from npm theme={null}
  npm install @moonpay/moonpay-js
  ```

  ```bash Using a script tag theme={null}
  <script defer src="https://static.moonpay.com/web-sdk/v1/moonpay-web-sdk.min.js"></script>
  ```
</CodeGroup>

Once you've included the script or package, you're ready to initialize the Web SDK and start integrating with our suite of cryptocurrency payment solutions.

### Initialize

Initializing the SDK is largely similar for both the package approach and script approach.

The script approach attaches the SDK constructor (`init`) to `window.MoonPayWebSdk`, whereas the package provides an asynchronous function to load the constructor.

<CodeGroup>
  ```ts via import theme={null}
  import { loadMoonPay } from "@moonpay/moonpay-js";

  const moonPay = await loadMoonPay();
  ```

  ```bash Using a script tag theme={null}
  const moonPay = window.MoonPayWebSdk.init;
  ```
</CodeGroup>

Or if you've opted for the package, the exported `loadMoonPay` function returns the SDK constructor.

Now, initialize the SDK in your application with the flow, environment, variant, and any parameters related to [On-Ramp](/widget/ramps-sdk-buy-params), [Off-Ramp](/widget/ramps-sdk-sell-params) or Swap.

<CodeGroup>
  ```typescript Buy theme={null}
  const widget = moonPay?.({
    flow: "buy",
    environment: "sandbox",
    params: {
      apiKey: "pk_test_123",
    },
    variant: "overlay",
    handlers: {
      async onTransactionCompleted(props) {
        console.log("onTransactionCompleted", props);
      },
    },
  });

  widget?.show();

  ```

  ```typescript Sell theme={null}
  const widget = moonPay?.({
    flow: "sell",
    environment: "sandbox",
    params: {
      apiKey: "pk_test_123",
    },
    variant: "overlay",
    handlers: {
      async onInitiateDeposit(props) {
        console.log(
          "onInitiateDeposit",
          props.cryptoCurrency.id,
          props.depositWalletAddress,
        );
        // Here you'd do your own sign and send...
        return {
          depositId: "your-deposit-identifier",
        };
      },
    },
  });

  widget?.show();
  ```

  ```typescript Swap theme={null}
  const moonPaySdk = moonPay({
    flow: "swap",
    environment: "sandbox",
    variant: "overlay",
    params: {
      apiKey: "pk_test_key",
    },
  });
  ```

  ```typescript Swap (w/customer setup) theme={null}
  const widget = moonPay?.({
    flow: "swapsCustomerSetup",
    environment: "sandbox",
    variant: "overlay",
    params: {
      apiKey: "pk_test_123",
      amount: "300",
      amountCurrencyCode: "usd",
    },
    handlers: {
      async onAuthToken({ token }) {
        // Once the customer has logged in in the widget, we share their
        // swaps-scoped authentication token with your app so you can
        // perform swaps requests on behalf of the customer.
        // The token needs to be passed as an Authorization header in the format
        // "Authorization: Bearer {token}".
        console.log("onAuthToken received with token:", token);
      },
      async onSwapsCustomerSetupComplete() {
        // When this is received, you can close the widget and resume the
        // the swap flow in your UI.
        console.log("onSwapsCustomerSetupComplete received");
      },
    },
  });

  widget?.show();
  ```
</CodeGroup>

### Configuration

* Possible values for `flow`: buy, sell, swap, swapsCustomerSetup
* Possible values for `environment`: sandbox, production
* Possible values for `variant`: embedded, overlay, newTab, newWindow

## Variants

### Embedded

When using the `embedded` variant, you can embed the MoonPay widget within a specific DOM element on your website. This option lets you fine-tune the placement of the widget and allows you to integrate it into a specific part of your layout. This can minimize context switching for the user. To use this variant, you must pass the `containerNodeSelector` property and a valid CSS selector for the container element where you want the widget to be embedded.

### Overlay

The `overlay` variant shows the widget as an iframe on top of your website. This option directs the user's attention towards completing their purchase while keeping them on your website. We have an additional `onCloseOverlay` handler for this variant should you want to run some code in the event that the overlay is closed.

<Info>
  Mobile payments, such as Apple Pay and Google Pay, are not supported with
  Overlay because it operates within an iframe.
</Info>

### New tab

The `newTab` variant opens the widget in a new browser tab. This option lets the user complete their purchase in a full-screen experience. When using this option, we recommend you tell the user they'll be taken to MoonPay in a new tab. This provides guidance to the user that this is intended and part of the purchase flow.

### New window

The `newWindow` variant opens the widget in a new browser window with a fixed size. This variant is ideal if you want to provide a more controlled experience for the user while they complete their purchase.

## Display

Depending on your SDK implementation, especially within contexts like mobile app webviews, be aware of the `useWarnBeforeRefresh` configuration. It's set to `true` by default, which prompts users with a warning if they try to refresh the page or navigate away. This is designed to avoid any unintentional data loss or interruption of ongoing tasks. However, this can sometimes lead to errors during redirections back to your application. If you'd like to prevent this behavior, simply set the `useWarnBeforeRefresh` configuration to `false`.

```typescript highlight={5} theme={null}
const moonPaySdk = moonPay({
  flow: "buy",
  environment: "sandbox",
  variant: "overlay",
  useWarnBeforeRefresh: false,
  params: {
    apiKey: "pk_test_key",
  },
});
```

(e.g. Mobile app webview) there is a `useWarnBeforeRefresh` SDK configuration setting that is enabled by default and warns users before a page refresh or navigation action occurs to prevent loss of unsaved data or interrupting an ongoing process. As a result, an error may appear when users try to redirect back to your application. You can disable this by disabling `useWarnBeforeRefresh` and setting it to false.

## Signing

If you're using the `walletAddress` or `walletAddresses` query param, in the `buy` or `swap` flows, you need to sign your widget URL before you can display the widget. Learn more about [URL signing](/widget/on-ramp-enhance-security-using-signed-urls).

```ts server.ts theme={null}
const moonPaySdk = moonPay({}); // Configure your SDK

const urlForSignature = moonPaySdk.generateUrlForSigning();

// The URL for signature should be sent to your backend, which should then
// sign it with your API secret and return the signature.
const response = await fetch("/sign-url", {
  method: "POST",
  body: JSON.stringify({ urlForSignature }),
});
const data = await response.json();

// Once you have the signature, you can update the SDK with it and show the
// widget.
moonPaySdk.updateSignature(data.signature);

moonPaySdk.show();
```


# Architecture
Source: https://dev.moonpay.com/widget/on-ramp-architecture

The MoonPay On-Ramp is a standalone widget product with an optional API and webhooks for an enhanced user experience. We provide web and mobile SDKs to render the widget in your app and a backend Node SDK for performing server-side functions.

## Components for on-ramp integrations

| Component                                                     | Features                                                                                                                                                                                                       |
| ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [URL integration](/widget/on-ramp-integrate-using-simple-url) | An alternative to using our SDKs Generate MoonPay widget links to show the widget in an iframe or mobile webview                                                                                               |
| [Web SDKs](/widget/on-ramp-web-sdk)                           | [Parameters](/widget/ramps-sdk-buy-params) to pre-fill cryptocurrency, amount, user email, etc. Includes [communication layer](/widget/on-ramp-sdk-events-details) between partner apps and the MoonPay widget |
| [Mobile SDKs](/widget/on-ramp-react-native-sdk)               | React Native SDK                                                                                                                                                                                               |
| [Node SDK](/widget/on-ramp-node-sdk)                          | Perform server-side functions, like [URL signing](/widget/on-ramp-enhance-security-using-signed-urls)                                                                                                          |
| [MoonPay API](/api-reference/widget)                          | Get minimum / maximum purchase amounts Get buy quote Show transaction history                                                                                                                                  |
| [Webhooks](/api-reference/widget/webhooks/overview)           | Get transaction updates                                                                                                                                                                                        |

## High-level diagram

This diagram shows a basic crypto purchase flow and the components required for implementation. We recommend using our API and webhooks to provide helpful context in your app, including minimum / maximum purchase amounts, quotes, and transaction history.

<Frame>
  <img alt="Purchase flow" />
</Frame>


# URL signing
Source: https://dev.moonpay.com/widget/on-ramp-enhance-security-using-signed-urls

Protecting your sensitive data

MoonPay is highly committed to security. For this reason, whenever sensitive information such as emails or wallet addresses are transmitted to the widget, you are required to use the parameter, otherwise, the MoonPay widget . This measure makes it more difficult for unauthorized third parties to misuse the the widget's pre-fill feature.

A signed URL helps limit access from unauthorized third parties by providing limited permissions and time to make a request. Passing the `signature` parameter is mandatory if you're using the `walletAddress` or `walletAddresses` parameter and it must be appended at the end of the URL. If your widget URL contains sensitive information, we strongly recommend using the `signature` parameter.

You can generate a `signature` of the URL server-side and append it to the end of the URL. If the `signature` is provided, we'll check the validity of the query string to make sure it has not been altered. If the signature is invalid for any reason the MoonPay widget will fail to load.

## How to sign URLs

Follow these steps for signing URLs:

1. Send your widget URL to your backend server.
2. Generate the signature using the secret key found in your [MoonPay dashboard](https://dashboard.moonpay.com/developers/).
   * Use your own code to generate signatures and sign URLs
   * Alternatively, use [our Node SDK](/widget/on-ramp-node-sdk) to generate signatures, sign URLs, and validate signatures.
3. Return either the signature or entire signed URL.
   * **If using a SDK**, return the signature and use `updateSignature`. Do not encode the signature, as the SDK handles this.
   * **If using a URL-based integration**, return the entire signed URL. Ensure that the value of `signature` and other parameters are URL-encoded.
4. Show the widget using the SDK or URL.

<Info>
  **Returning the signature vs entire signed URL**

  **Integrations using an SDK**: Return the signature by itself and use `updateSignature`

  **Integrations using URLs**: Return the entire signed URL
</Info>

## How to generate signatures

1. Create an HMAC (Hash-Based Message Authentication Code) using the SHA-256 hash function.
   1. Use your secret API key as the key and the original URL's query string as the message.
2. For URL-based integrations, make sure all query parameter values are URL-encoded before creating the signature.

<Info>
  All query parameter *values* (not the entire query string) need to be
  URL-encoded before generating the signature in order for it to be valid.
</Info>

## Code examples

### Integrations using an SDK

Integrations using a web or mobile SDK should calculate the signature, then return the signature by itself, not URL-encoded.

More details about signing with each SDK:

* [Web SDK](/widget/on-ramp-web-sdk#signing)
* [React SDK](/widget/on-ramp-react-sdk#url-signing)
* [React Native SDK](/widget/on-ramp-react-native-sdk#initialize)

<CodeGroup>
  ```typescript Node.js theme={null}
  import crypto from 'crypto';

  const secretKey = 'sk_test_key'; // Use your secret key

  const generateSignature = (url) => {
  const signature = crypto
  .createHmac('sha256', secretKey)
  .update(new URL(url).search) // Use the query string part of the URL
  .digest('base64'); // Convert the result to a base64 string

      console.log(signature) // Print the signature
      return signature // Return the signature

  };
  ```

  ```php PHP theme={null}
  <?php
    $host = 'https://buy-sandbox.moonpay.com';  // Base URL
    $query = '?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae';  // Query parameters

    $secretKey = 'sk_test_key';  // Your secret key

    // Create the HMAC SHA-256 hash and encode it in base64
    $signature = base64_encode(hash_hmac('sha256', $query, $secretKey, true));

    echo $signature;  // Print the signature
  ?>
  ```
</CodeGroup>

### Integrations using URLs

Integrations generating widget URLs should calculate the signature, URL-encode the signature, then return the whole signed URL.

<CodeGroup>
  ```typescript Node.js theme={null}
  import crypto from 'crypto';

  const originalUrl = '<https://buy-sandbox.moonpay.com?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae>';

  const signature = crypto
  .createHmac('sha256', 'sk_test_key') // Use your secret key
  .update(new URL(originalUrl).search) // Use the query string part of the URL
  .digest('base64'); // Convert the result to a base64 string

  const urlWithSignature = `${originalUrl}&signature=${encodeURIComponent(signature)}`; // Add the signature to the URL

  console.log(urlWithSignature); // Print the signed URL
  ```

  ```php PHP theme={null}
  <?php
    $host = 'https://buy-sandbox.moonpay.com';  // Base URL
    $query = '?apiKey=pk_test_key&currencyCode=eth&walletAddress=0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae';  // Query parameters

    $secretKey = 'sk_test_key';  // Your secret key

    // Create the HMAC SHA-256 hash and encode it in base64
    $signature = base64_encode(hash_hmac('sha256', $query, $secretKey, true));

    // URL encode the signature
    $encodedSignature = urlencode($signature);

    // Combine the base URL, query parameters, and the signature
    $signedUrl = $host . $query . "&signature=" . $encodedSignature;

    echo $signedUrl;  // Print the signed URL
  ?>
  ```
</CodeGroup>

<Warning>
  Attention: The API gateway of some cloud providers change your parameter's
  order, resulting in a failed signature validation.
</Warning>


# FAQ
Source: https://dev.moonpay.com/widget/on-ramp-faq



## How do I change my API Keys?

Go to the [Developers > API Keys](https://dashboard.moonpay.com/developers/) page of your MoonPay dashboard and hit the roll button next to the API key you wish to replace. You will be given the option to immediately delete the old key or a 12hour rollover before the old API keys expire.

## Iframe shows an error instead of the widget

If you see a CSP error that says `buy.moonpay.com refused to connect`, you’ll need to allowlist your production domain(s). We require this when you embed the MoonPay widget in an iframe or use the overlay, drawer, or embedded options to prevent unauthorized third-parties from embedding the MoonPay widget.

To resolve the issue, add your production domain(s) to the [Settings page](https://dashboard.moonpaycloud.com/settings/) of your MoonPay dashboard.

<Frame>
  <img alt="CSP Error" />
</Frame>

## Region-based widget error

If you see a widget error that geo-blocks certain users, confirm that these users are in a region supported by MoonPay. [Non-supported countries, states, and territories for on-ramp](https://support.moonpay.com/hc/en-gb/articles/6557330712721-What-are-our-non-supported-countries-states-and-territories-for-on-ramp-product-)

## Sandbox Supported Currencies

Our sandbox environment supports a limited selection of testnet currencies; we recommend testing primarily with Ethereum on Sepolia, Solana Testnet, or the Bitcoin Testnet.

## Multiple accounts in production

In our production environment, we only allow one account per user. Creating multiple accounts in production may cause your account to be flagged or blocked.

## Test credit cards and KYC info in production

Only genuine card and KYC information may be used in our production environment. Do **not** use test credit card or test KYC information in production, as this will result in your account being blocked.

## Using platforms like Flutter

MoonPay does not offer an SDK for Flutter. You'll have to manually embed our widget in a WebView. Consider the following tips:

* You can create your own HTML that uses our [Web SDK](/widget/on-ramp-web-sdk) to embed our Widget. This will allow you to receive our Widget's events, if you wish. You'll then need to send them out to your Flutter app layer.
* If you're experiencing camera issues in Flutter's WebView, consider using the Flutter plugin compatible with our Web SDK, available at [https://pub.dev/packages/flutter\_inappwebview](https://pub.dev/packages/flutter_inappwebview).
* You can find further guidance on configuring Flutter camera permissions and other related documentation at [https://inappwebview.dev/docs/5.x.x/web-rtc/](https://inappwebview.dev/docs/5.x.x/web-rtc/).
* Custom Origin via `baseUrl` Property: For specific requirements, you can set a custom origin using the `baseUrl` property. This serves as the base URL for any relative paths in the HTML and sets the document's origin. Example:

  ```dart theme={null}
  InAppWebView(
    initialData: InAppWebViewInitialData(
      data: htmlContent,
      baseUrl: Uri.parse("https://your.custom.origin"),
    ),
    // ... other configurations ...
  )
  ```

This custom origin approach can be advantageous for scenarios involving scripts that validate the document's origin or for CORS policies. We recommend using `https://app_name`, `capacitor://` or equivalent as your custom origin for the `baseUrl` property. From here, add the domain to your allowlist in the settings page of your [MoonPay dashboard](https://dashboard.moonpay.com/settings/).

* Scrolling Issues within the MoonPay widget: When using these overflowing containers in Flutter with a WebViewWidget, you have to specify gesture recognizers: Example:

  ```dart theme={null}
  gestureRecognizers: <Factory<OneSequenceGestureRecognizer>>{
    Factory<OneSequenceGestureRecognizer>(
      () => EagerGestureRecognizer(),
    ),
  },
  ```

## App requirements for KYC

<Warning>
  When not using a MoonPay SDK, make sure that the following requirements are
  met so that users can successfully complete KYC (Know Your Customer) steps.
</Warning>

These requirements make sure that customers can complete each KYC step, including uploading documents and doing a selfie check. Failing to follow these steps will cause new customers to drop off, as they won't be able to finish KYC or make a purchase.

### General app requirements for all implementations

All partner apps should ensure the following:

* `Feature-Policy` header for your webpage / frame or any other container has no restrictions for initializing camera like value `camera 'none'`.
* `Permissions-Policy` header doesn't restrict access to a camera and microphone (for some cases) and if allow is set check for `"camera; microphone"` values.
* When using [iOS WKWebview](https://developer.apple.com/documentation/webkit/wkwebviewconfiguration/1614793-allowsinlinemediaplayback) you may need to set `allowsInlineMediaPlayback` to `true` in the `WKWebViewConfiguration` used in your app. This adjustment ensures that media content, like a camera feed, can be displayed properly within the web view, rather than forcing full-screen playback.
* Your website is being run on a secure `https` connection.

### WebView requirements

Partner apps that use `WebView` should ensure the following:

* The web view is able to access device local storage and initialize camera (for older iOS versions, the camera can be accessed only from Safari browser or WebView with `SFSafariViewController`)
* HTML5 video playback is allowed (`<video>` tags are being used to send instructions): if video-instructions are not played, try using `WebChromeClient` to enable video playback
* Autoplay in fullscreen mode is disabled and `allowsInlineMediaPlayback` is set as `true` for WebView
* The selector file is implemented on your side (required for KYC document uploads)

### Iframe requirements

Partner apps that use `iframe` should ensure the following:

* Parent page header has no restrictions for initializing the camera, e.g. `camera=()`
  * Parent page can alternatively include `camera=*` in the Permissions-Policy header

* The iframe allow property has `allow="accelerometer; autoplay; camera; encrypted-media; gyroscope; payment"`

## Payments

### How Do You Handle Chargebacks?

At MoonPay, we treat chargebacks seriously and have processes in place to prevent and handle chargebacks. For more information reach out to your MoonPay account representative.

### How Do I Get Paid?

Details can be found on our MoonPay documentation [here](https://support.moonpay.com/hc/en-gb/articles/4406209996049-How-do-affiliate-payouts-work-).

### What Are My Purchase Limits?

Purchase limits will vary by region, currency and level of Know Your Customer KYC documents provided. Additional details can be found on our customer support page [here](https://support.moonpay.com/customers/docs/limits-faq).

### Can I Adjust Purchase Limits for My Users?

It is not possible to increase or decrease purchase limits for users or partners. MoonPay cannot modify the minimum or maximum purchase amounts for any cryptocurrency. For more details on limits, please refer to our Limits FAQ.

### What Cryptocurrencies Does MoonPay Support?

There are more limitations for US users than non-US users. A complete list can be found [here](https://support.moonpay.com/hc/en-gb/articles/360009280177-Which-cryptocurrencies-do-you-support-).

### Is There a Way to Customize The Automated Emails Users Receive?

We can add a partner logo in the automated email and change the partner name (`Partner_Name` via MoonPay) in the email subject upon request. Please reach out to your MoonPay representative.

### I'm Having Trouble Adding my Credit/Debit Card to My Account?

Double check you are not in our sandbox environment. Genuine cards should never be added to sandbox accounts.

Has your card already been added to another account? There is a limit of one card per account. Either use the other account or try using another card.


# Overview
Source: https://dev.moonpay.com/widget/on-ramp-integrate-using-sdk

We have SDKs for all your tech stacks. Pick the one that is right for you.

## Web SDKs: [Web](/widget/on-ramp-web-sdk), [React](/widget/on-ramp-react-sdk), [Node.js](/widget/on-ramp-node-sdk)

## Mobile SDK: [React Native](/widget/on-ramp-react-native-sdk)


# URL Integration
Source: https://dev.moonpay.com/widget/on-ramp-integrate-using-simple-url

You can use the below pre-written code to quickly get started on adding a **Buy Crypto** button that opens the MoonPay widget in a new browser tab.

<Tabs>
  <Tab title="Sandbox">
    **URL**: `https://buy-sandbox.moonpay.com/?apiKey=pk_test_123`

    <CodeGroup>
      ```html sandbox.html theme={null}
      <!--Opens the MoonPay widget in a new browser tab-->
      <body>
          <div class="container">
              <button onclick="window.open('https://buy-sandbox.moonpay.com/?apiKey=pk_test_123', '_blank')">Buy with MoonPay</button>
          </div>
      </body>
      ```

      ```css sandbox.css theme={null}
      .container {
      background-color: #392a54;
      padding: 20px;
      text-align: center;
      }

      button {
      background-color: #7d00fe;
      border: none;
      color: white;
      padding: 15px 50px;
      font-size: 16px;
      cursor: pointer;
      border-radius: 4px;
      background-image: url("https://images.crunchbase.com/image/upload/c_lpad,h_170,w_170,f_auto,b_white,q_auto:eco,dpr_1/jglje7ar0xc6j5lvai6t");
      background-repeat: no-repeat;
      background-position: right center;
      background-size: contain;
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Production">
    **URL**: `https://buy.moonpay.com/?apiKey=pk_live_123`

    <CodeGroup>
      ```html sandbox.html theme={null}
      <!--Opens the MoonPay widget in a new browser tab-->
      <body>
          <div class="container">
              <button onclick="window.open('https://buy.moonpay.com/?apiKey=pk_live_123', '_blank')">Buy with MoonPay</button>
          </div>
      </body>
      ```

      ```css sandbox.css theme={null}
      .container {
      background-color: #392a54;
      padding: 20px;
      text-align: center;
      }

      button {
      background-color: #7d00fe;
      border: none;
      color: white;
      padding: 15px 50px;
      font-size: 16px;
      cursor: pointer;
      border-radius: 4px;
      background-image: url("https://images.crunchbase.com/image/upload/c_lpad,h_170,w_170,f_auto,b_white,q_auto:eco,dpr_1/jglje7ar0xc6j5lvai6t");
      background-repeat: no-repeat;
      background-position: right center;
      background-size: contain;
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## Here's an example. Give it a try

<ExampleButton />


# Node.js SDK
Source: https://dev.moonpay.com/widget/on-ramp-node-sdk



## Install

```bash theme={null}
npm install @moonpay/moonpay-node
```

View the package on [npm](https://www.npmjs.com/package/@moonpay/moonpay-node?activeTab=code).

## Setup

First, import the `MoonPay` class.

```typescript theme={null}
import { MoonPay } from '@moonpay/moonpay-node`;
```

Set up the `MoonPay` class with your secret key.

<Warning>
  NEVER use your secret key in client side code. Load your secret key from an environment variable instead.
</Warning>

```typescript theme={null}
const moonPay = new MoonPay("sk_test_...");
```

## Usage

Use the `moonPay` instance to access our functions.

### URL utilities

MoonPay URL utilities are namespaced under the `.url` property.

#### Signing your URL

If you include the `walletAddress` or `walletAddresses` query param, you'll need to sign the URL.

```typescript theme={null}
const signature = moonPay.url.generateSignature(
  "https://buy.moonpay.com/?apiKey=pk_test_123&walletAddress=...",
);
```

Or, return the signed URL, using the `returnFullURL` option.

```typescript theme={null}
const signedURL = moonPay.url.generateSignature(
  "https://buy.moonpay.com/?apiKey=pk_test_123&walletAddress=...",
  { returnFullURL: true },
);
```

#### Verifying a signature

Or, you can verify that a URL is correctly signed.

```typescript theme={null}
const isSignatureValid = moonPay.url.isSignatureValid(
  "[...]/?apiKey=pk_test_123&signature=someSignature",
);
```

#### Generating a signed URL

You can also have us generate the full, signed URL, based on some input parameters.

```typescript theme={null}
const params = {
  apiKey: "pk_test_123",
  baseCurrencyCode: "GBP",
};

const url = moonPay.url.generate({ flow: "buy", params });
```

## Example

Here's an example of an Express endpoint that signs a URL query param.

```typescript theme={null}
import express from "express";
import { MoonPay } from "@moonpay/moonpay-node";

const moonPay = new MoonPay("sk*test*...");
const app = express();

app.get("/moonpay_signature", (req, res) => {
  const { url } = req.query;
  const signature = moonPay.url.generateSignature(url);
  res.send({ signature });
});

app.listen(3000, () => console.log("Listening on port 3000!"));
```


# Overview
Source: https://dev.moonpay.com/widget/on-ramp-overview

MoonPay is the leading ramps provider in the space and continues to be the most popular gateway for crypto and NFT applications across the world. With the MoonPay fiat-to-crypto On-Ramp, users can seamlessly purchase cryptocurrencies directly from your website or web3 application.

<Info>
  **Want to get a head-start on your integration?**

  The **[MoonPay Demo Integrations](https://github.com/moonpay/moonpay-demo-integrations)** GitHub repository has working, clone-able example integrations ready to use - just add your API keys.
</Info>

## On-Ramp user flow

Using our SDKs, there are several options to integrate MoonPay widget. For example, in a modal overlaid on top of your web app, or in an in-app web view.

To buy crypto, the user goes through the following steps in the widget:

<Steps>
  <Step>Confirm the cryptocurrency, fiat, and amount to purchase.</Step>
  <Step>Log in to the widget using multi-factor authentication (MFA).</Step>
  <Step>Select payment method.</Step>
  <Step>Go through KYC, if the user is new to MoonPay.</Step>
  <Step>Confirm the purchase.</Step>
  <Step>MoonPay sends the crypto to the user.</Step>
</Steps>

## Try the On-Ramp flow in our sandbox environment

<iframe title="Sandbox" />

## Features

**Secure crypto transactions**: Our system supports 100+ cryptocurrencies and as the merchant of record MoonPay assumes full responsibility for all fraud disputes and chargebacks. All customers are required to pass MoonPay’s established Know Your Customer (KYC) and risk management procedures along with all applicable laws and regulations.

**Optimal conversion rates**: Millions of users have previously purchased cryptocurrencies using MoonPay, having stored their payment and KYC details, leading to maximized conversion rates.

**Diverse payment methods**: MoonPay accommodates a vast spectrum of payment methods for purchase and sale transactions: credit and debit cards, EUR / GBP / USD bank transfers, PayPal, Venmo and local payment methods like PIX and Yellow Card, as well as Apple & Google Pay, ensuring users can transact according to their preference. With enablement from the MoonPay team, users can now also fund wallets through MoonPay using centralized exchanges (see [Configure the On-Ramp user journey](/widget/ramps-sdk-buy-params)).

**Customize the widget**: You can customize the widget to feel like a native part of your site or application by adjusting button and background colors. You can also add your company logo to the transactional emails sent to customers.

<Frame>
  <img alt="Customized UI" />
</Frame>

**Remove friction for your users**: Improve your customers' experience and speed up the buying process by pre-filling information such as their wallet address, email, selected token, fiat currency, amounts, and their preferred payment method. Users don't have a digital wallet? We can create one for them using just their email address as they go through the purchase flow.

<Frame>
  <img alt="Prefill" />
</Frame>

Through social sign-in, users can effortlessly log in using their Google or Apple accounts directly from the widget, serving as a smooth connector between the traditional web (Web2) and blockchain-based platforms (Web3).

## Supported currencies and regions

Review the following Support articles to see our supported currencies and regions for on-ramp:

* [Supported cryptocurrencies](https://support.moonpay.com/customers/docs/list-of-supported-cryptocurrencies)
* [Supported fiat currencies](https://support.moonpay.com/customers/docs/moonpays-supported-currencies#buying-crypto)
* [Unsupported regions](https://support.moonpay.com/customers/docs/moonpays-unsupported-countries)

## Get started

<Steps>
  <Step>
    Get your MoonPay account and API keys
    [here](https://dashboard.moonpay.com/).
  </Step>

  <Step>Start using our sandbox environment.</Step>

  <Step>
    Once you've completed the KYB process, your API keys will be made available
    in the developers tab of the dashboard.
  </Step>
</Steps>

If you have any questions, reach out to [support@moonpay.com](mailto:support@moonpay.com).


# Widget theming
Source: https://dev.moonpay.com/widget/on-ramp-personalize-appearance

Enhance your website or applications user experience by tailoring the MoonPay widget's appearance to align with your brand. These personalization options are referred to as a .

## Building your theme

Your website or application can feature a unique theme that includes a dedicated theme.

You can build your theme using [MoonPay dashboard theme builder](https://dashboard.moonpay.com/theme). Themes built on the MoonPay dashboard are tied to your API key and will show up wherever you use your API key (e.g. widget, transaction tracker).

<Frame>
  <img alt="Theming" />
</Frame>

## Implementing your theme

To apply your custom theme, simply set your newly created theme to the default and save the changes.

This will ensure that the widget or transaction tracker is initialized with the corresponding theme whenever you use your MoonPay API key.

## Examples

<Frame>
  <img alt="Mobile" />
</Frame>

<Frame>
  <img alt="Desktop" />
</Frame>

## Available personalizations

* **Brand logos**. Please contact your MoonPay team and include:
  * 1 rectangular logo for transactional emails

* **Color choices** accommodating both light and dark preferences.
  * Widget Background Color
  * Primary Button Color

* **Custom Loader** - for a simple approach to customizing the loader that your MoonPay widget displays, you can use the dashboard:
  1. Go to the B2B dashboard
  2. Navigate to "Theme" → "Loader"
  3. Choose your preferred loader type (MoonPay default or generic spinner)
  4. Select custom colors to match your brand
  5. Save changes

## Usage of `theme`

You can manually choose light or dark modes using the`theme` widget parameter. e.g. `theme=dark` or `theme=light`


# Quickstart
Source: https://dev.moonpay.com/widget/on-ramp-quickstart



## Overview

<Frame>
  <img alt="Quickstart overview" />
</Frame>

In this Quickstart, you will facilitate cryptocurrency purchases via the MoonPay On-Ramp directly from your browser.

Whether you are a complete beginner to coding or a seasoned expert, this guide will take you through all of the necessary steps to have you converting fiat to cryptocurrency in no time.

## What you will accomplish

In this tutorial, you will:

<Steps>
  <Step>Configure On-Ramps widget in a local environment</Step>
  <Step>Create a new folder for code</Step>
  <Step>Initialize the widget in a file using HTML and JavaScript</Step>
  <Step>Edit the widget parameters</Step>
  <Step>Display the fully functional widget locally in your browser</Step>
</Steps>

## Prerequisites

Before beginning, you will need:

* **A MoonPay account**: If you do not have one, set one up on [this page](https://dashboard.moonpay.com/).
* **An IDE (coding software):** Some popular ones are [Visual Studio Code](https://code.visualstudio.com/) and [IntelliJ WebStorm](https://www.jetbrains.com/webstorm/). We will be using Visual Studio Code in this tutorial.
* **A web browser:** Any web browser will work. We will be using Google Chrome in this tutorial.

## Implementation

### Step 1: Set up a file for your integration

In your IDE, create a new file for your On-Ramp code. Ours will be called `on-ramp.html`.

### Step 2: Retrieve API keys from the MoonPay Dashboard

* Navigate to your [MoonPay Dashboard](https://dashboard.moonpay.com/) and log in.
* Once logged in, navigate to the Developers tab on the sidebar → API Keys.
  * Here, you will be able to copy your API keys. In this tutorial, we will be using the publishable test key.

<Frame>
  <img alt="Dashboard" />
</Frame>

### Step 3: Insert HTML and code into `on-ramp.html`

* The code below will embed our Software Development Kit (SDK) directly into your HTML by way of `<script>` tags.
* You can think of this as a way of injecting code directly into HTML without having to create a separate linked file.

<CodeGroup>
  ```html on-ramp.html theme={null}
  <!DOCTYPE html>
  <html lang="en">
    <head>
      <meta charset="UTF-8" />
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <title>MoonPay Integration</title>

      <!-- Adds the MoonPay SDK as a script to your HTML file -->
      <script
        defer
        src="https://static.moonpay.com/web-sdk/v1/moonpay-web-sdk.min.js"
      ></script>

      <!-- Initialize the MoonPay SDK immediately upon page load -->
      <script>
        document.addEventListener("DOMContentLoaded", () => {
          const moonpaySdk = window.MoonPayWebSdk.init({
            flow: "buy",
            environment: "sandbox",
            variant: "overlay",
            params: {
              apiKey: "pk_test_123", // Replace with your MoonPay publishable API key
              baseCurrencyCode: "usd",
              baseCurrencyAmount: "30",
              defaultCurrencyCode: "eth",
            },
          });

          // Open widget
          moonpaySdk.show();
        });
      </script>
    </head>

    <body>
      <div class="container"></div>
    </body>
  </html>
  ```
</CodeGroup>

* This script will detect when the HTML page loads and immediately run the JavaScript within the `<script>` tags when the load has finished. Remember to replace `pk_test` with your publishable API key from **Step 1**.

* You can customize widget functionality (currencies, amounts, etc.) by adding and removing parameters in the JavaScript, whilst still preserving proper formatting.
  * All parameters can be found on [this page of our documentation](/widget/ramps-sdk-buy-params).

* For example, if we would like to display the widget with a default of *100 GBP worth of BTC*, and also specify the `walletAddress` in the parameters so that the user is not prompted for theirs, we could modify the JavaScript like such:

```html SDK Setup theme={null}
<script>
  document.addEventListener("DOMContentLoaded", () => {
    const moonpaySdk = window.MoonPayWebSdk.init({
      flow: "buy",
      environment: "sandbox",
      variant: "overlay",
      params: {
        apiKey: "pk_test", // Replace with your MoonPay publishable API key
        baseCurrencyCode: "gbp",
        baseCurrencyAmount: "100",
        defaultCurrencyCode: "btc",
        walletAddress: "enter your wallet here",
      },
    });

    // Open widget
    moonpaySdk.show();
  });
</script>
```

### Step 4: Do a test transaction

* The first step of processing a test transaction using the MoonPay On-Ramp is to make sure that `environment` is set to`"sandbox"`, as shown above in the example code. This puts your widget in test mode.
* Next, open up the widget, enter your email address, and log in.

<Frame>
  <img alt="Login" />
</Frame>

* Next, you will be asked to enter a wallet address if one hasn’t been passed through the parameters already. If you already have existing wallet addresses with MoonPay, they will show up here. Any wallet address will work for a test transaction.
* Next, go and grab a test card from [this page of our documentation](/widget/faq-sandbox-testing#adding-a-payment-method).

<Warning>
  Never use a test credit card on anything other than a test widget that has
  environment: "sandbox", otherwise your MoonPay account may be blocked.
</Warning>

* If successful, you should see a screen that looks like the below.

<Frame>
  <img alt="Order complete" />
</Frame>

## Completion

Congratulations, you have just integrated the MoonPay On-Ramp! 🎉

There are so many ways to integrate this widget to enhance user experience when buying cryptocurrency. If you want to know about alternative ways to integrate with MoonPay, check our [Integrations (SDKs)](/widget/on-ramp-integrate-using-sdk) page.

Any questions? Feel free to visit our [Help Center](https://support.moonpay.com/hc/en-gb/categories/360001595097-Customer-Support-Help-Center) to dig into our other resources or drop us a line!


# React Native SDK
Source: https://dev.moonpay.com/widget/on-ramp-react-native-sdk



## Install

Install the official MoonPay package.

```bash theme={null}
npm install --save @moonpay/react-native-moonpay-sdk
```

### Install dependencies

Assuming you already installed `react` and `react-native` you need to install and configure `react-native-webview`.

```bash theme={null}
npm install --save react-native-webview
```

We also highly recommend to install the following polyfill to prevent any issues with URL formatting:

```bash theme={null}
npm install --save react-native-url-polyfill
```

## In-App Browser Implementation

You no longer need to install `expo-web-browser` or `react-native-inappbrowser-reborn` as optional dependencies. Instead, partners are now required to provide their own in-app browser implementation when using the MoonPay SDK. You can either use `expo-web-browser`, `react-native-inappbrowser-reborn`, or any standalone in-app browser of your choice. Alternatively, you can create a wrapper to manage the in-app browser you prefer to use.

## Initialize

Initialize the SDK in your application with the flow, environment and any parameters related to [Buy](/widget/ramps-sdk-buy-params), [Sell](/widget/ramps-sdk-sell-params) or Swap. Additionally you can choose to render the widget either as an in-app browser or a webview. If you're using the `walletAddress` or `walletAddresses` query param, you need to sign your widget URL before you can display the widget. Learn more about [URL signing](/widget/on-ramp-enhance-security-using-signed-urls).

**How to choose?**

* An `In-app browser` will allow you to use native features like Google Pay, social sign-in and popups.
* A `Webview` will allow you to use a communication layer between the widget and your app and therefore get your app to perform certain actions once some events occur in the widget. Additionally it will give you infinite choices on how it might look like. You can add it to a bottom sheet, drawer, or as full-screen. It's entirely up to you.

See below In-App browser examples. For additional examples you can look on our [Github page here](https://www.npmjs.com/package/@moonpay/react-native-moonpay-sdk).

<CodeGroup>
  ```typescript In-app browser theme={null}
  import { View, Button, Text, useEffect } from "react-native";
  import { useMoonPaySdk } from "@moonpay/react-native-moonpay-sdk";

  const YourComponent = () => {
    const { openWithInAppBrowser, generateUrlForSigning, updateSignature } =
      useMoonPaySdk({
        sdkConfig: {
          flow: "buy",
          environment: "sandbox",
          params: {
            apiKey: "pk_test_key",
          },
        },
        browserOpener: {
          open: (url) => {
            // Use any in-app browser or standalone browser here
            // Example with custom browser implementation
          },
        },
      });

    useEffect(() => {
      // The URL for signature should be sent to your backend, which should then
      // sign it with your API secret and return the signature.
      // Once you have the signature, you can update the SDK with it and show the widget.
      fetch("/sign-url", {
        headers: {
          "Content-Type": "application/json",
          Authorization: "Bearer <token>",
        },
        method: "POST",
        body: JSON.stringify({
          url: generateUrlForSigning(),
        }),
      })
        .then((res) => res.json())
        .then((data) => {
          const signature = data.signature;
          updateSignature(signature);
        });
    }, []);

    return (
      <View>
        <Button onPress={() => openWithInAppBrowser()}>
          <Text>Open in InApp browser</Text>
        </Button>
      </View>
    );
  };
  ```

  ```typescript In-app browser (w/wrapper) theme={null}
  import { View, Button, Text, useEffect } from "react-native";
  import { useMoonPaySdk } from "@moonpay/react-native-moonpay-sdk";

  const InAppBrowserWrapper = {
    open: async (url) => {
      // Use any in-app browser method here
      InAppBrowser.open(url);
    },
  };

  const YourComponent = () => {
    const { openWithInAppBrowser, generateUrlForSigning, updateSignature } =
      useMoonPaySdk({
        sdkConfig: {
          flow: "buy",
          environment: "sandbox",
          params: {
            apiKey: "pk_test_123",
          },
        },
        InAppBrowser: InAppBrowserWrapper,
      });

    useEffect(() => {
      // The URL for signature should be sent to your backend, which should then
      // sign it with your API secret and return the signature.
      // Once you have the signature, you can update the SDK with it and show the widget.
      fetch("/sign-url", {
        headers: {
          "Content-Type": "application/json",
          Authorization: "Bearer <token>",
        },
        method: "POST",
        body: JSON.stringify({
          url: generateUrlForSigning(),
        }),
      })
        .then((res) => res.json())
        .then((data) => {
          const signature = data.signature;
          updateSignature(signature);
        });
    }, []);

    return (
      <View>
        <Button onPress={() => openWithInAppBrowser()}>
          <Text>Open in InApp browser</Text>
        </Button>
      </View>
    );
  };
  ```

  ```typescript WebView theme={null}
  import { View, Button, Text } from "react-native";
  import { useMoonPaySdk } from "@moonpay/react-native-moonpay-sdk";

  const YourComponent = () => {
    const { MoonPayWebView } = useMoonPaySdk({
      flow: "buy",
      environment: "sandbox",
      params: {
        apiKey: "pk_test_key",
      },
    });

    useEffect(() => {
      // This is just an example of how it might look like.
      // You may handle this differently.
      fetch("/sign-url", {
        headers: {
          "Content-Type": "application/json",
          Authorization: "Bearer <token>",
        },
        method: "POST",
        body: JSON.stringify({
          url: sdk.generateUrlForSigning(),
        }),
      })
        .then((res) => res.json())
        .then((data) => {
          const signature = data.signature;
          sdk.updateSignature(data);
        });
    }, []);

    return (
      <View>
        <MoonPayWebView />
      </View>
    );
  };

  ```
</CodeGroup>

### Configuration

* Possible values for `flow`: buy, sell, swap, swapsCustomerSetup
* Possible values for `environment`: sandbox, production


# React SDK
Source: https://dev.moonpay.com/widget/on-ramp-react-sdk



<Info>
  An example React On-Ramp integration can be found on our Github
  [here](https://github.com/moonpay/moonpay-demo-integrations).
</Info>

## Install

To integrate MoonPay in your React app, you can use MoonPay's `moonpay-react` package.

```bash theme={null}
npm install @moonpay/moonpay-react
```

Once you've installed this, you're ready to set up your project to integrate the MoonPay widget.

## Add the provider

The first thing to do is add the MoonPay provider to the root of your React application. This will provide context throughout your app to allow you to use the MoonPay widget components.

```typescript setup.ts theme={null}
import { MoonPayProvider } from "@moonpay/moonpay-react";

export default function App() {
  return (
    <MoonPayProvider apiKey="pk_test_123" debug>
      <Home />
    </MoonPayProvider>
  );
}
```

The provider abstracts the complexity of loading the SDK into your app.

Now, use your desired component, passing variant and any parameters related to [Buy](/widget/ramps-sdk-buy-params), [Sell](/widget/ramps-sdk-sell-params), or Swap as props.

The environment is set based on which API key you use. Use the following keys:

* Sandbox environment: `pk_test...`
* Production environment: `pk_live...`

<CodeGroup>
  ```typescript Buy theme={null}
  import { MoonPayBuyWidget } from '@moonpay/moonpay-react';

  export default function Home() {
    return (
      {/*... other components */}
      <MoonPayBuyWidget
        variant="overlay"
        baseCurrencyCode="usd"
        baseCurrencyAmount="100"
        defaultCurrencyCode="eth"
        onLogin={async () => console.log("Customer logged in!")}
        visible
      />
      {/* ... other components*/}
    )
  }

  ```

  ```typescript Sell theme={null}
  import { MoonPaySellWidget } from '@moonpay/moonpay-react';

  export default function Home() {
    return (
      {/* ... other components */}
      <MoonPaySellWidget
        variant="overlay"
        baseCurrencyCode="eth"
        baseCurrencyAmount="0.045"
        visible
      />
      {/* ... other components */}
    )
  }
  ```

  ```typescript Swap theme={null}
  import { MoonPaySwapWidget } from '@moonpay/moonpay-react';

  export default function Home() {
    return (
      {/* ... other components */}
      <MoonPaySwapWidget variant="overlay" visible />
      {/* ... other components */}
    )
  }
  ```

  ```typescript Swap (w/customer setup) theme={null}
  import { MoonPaySwapsCustomerSetupWidget } from '@moonpay/moonpay-react';

  export default function Home() {
    return (
      {/* ... other components */}
      <MoonPaySwapsCustomerSetupWidget
        variant="overlay"
        amount="300"
        amountCurrencyCode="usd"
        onAuthToken={async ({ token }) => {
          // Once the customer has logged in in the widget, we share their
          // swaps-scoped authentication token with your app so you can
          // perform swaps requests on behalf of the customer.
          // The token needs to be passed as an Authorization header in the format
          // "Authorization: Bearer {token}".
          console.log("onAuthToken received with token:", token);
        }}
        onSwapsCustomerSetupComplete={async () => {
          // When this is received, you can close the widget and resume the
          // the swap flow in your UI.
          console.log("onSwapsCustomerSetupComplete received");
        }}
        visible
      />
      {/* ... other components */}
    )
  }
  ```
</CodeGroup>

### For Next.js

For Next.js, it's recommended to dynamically import the MoonPay components as shown below. This ensures efficient loading of the components and prevents server-side rendering (SSR). Otherwise you will see an error message: `ReferenceError: window is not defined`

```typescript theme={null}
import dynamic from "next/dynamic";

const MoonPayProvider = dynamic(
  () => import("@moonpay/moonpay-react").then((mod) => mod.MoonPayProvider),
  { ssr: false },
);

const MoonPayBuyWidget = dynamic(
  () => import("@moonpay/moonpay-react").then((mod) => mod.MoonPayBuyWidget),
  { ssr: false },
);
```

## Variants

### Embedded

The `embedded` variant shows the MoonPay widget will show as part of your page, wherever you place the component. This option lets you fine-tune the placement of the widget and allows you to integrate it into a specific part of your layout. This can minimize context switching for the user.

### Overlay

The `overlay` variant shows the widget as an iframe on top of your website. This option directs the user's attention towards completing their purchase while keeping them on your website.

### New tab

The `newTab` variant opens the widget in a new browser tab. This option lets the user complete their purchase in a full-screen experience. When using this option, we recommend you tell the user they'll be taken to MoonPay in a new tab. This provides guidance to the user that this is intended and part of the purchase flow.

### New window

The `newWindow` variant opens the widget in a new browser window with a fixed size. This variant is ideal if you want to provide a more controlled experience for the user while they complete their purchase.

## Display

You might want to control whether the SDK is showing based on some application state. This is there the `visible` prop comes into play. Using the `visible` prop ensures that the widget is properly shown and cleaned up as necessary. As a light example, here is how one could add a button to toggle the SDK embedded variant.

<CodeGroup>
  ```typescript highlight={13} Buy theme={null}
  import { MoonPayBuyWidget } from "@moonpay/moonpay-react";

  export default function Home() {
    const [visible, setVisible] = useState(false);

    return (
      <>
        <MoonPayBuyWidget
          variant="overlay"
          baseCurrencyCode="usd"
          baseCurrencyAmount="100"
          defaultCurrencyCode="eth"
          visible={visible}
        />
        <button onClick={() => setVisible(!visible)}>Toggle widget</button>
      </>
    );
  }
  ```

  ```typescript highlight={12} Sell theme={null}
  import { MoonPaySellWidget } from "@moonpay/moonpay-react";

  export default function Home() {
    const [visible, setVisible] = useState(false);

    return (
      <>
        <MoonPaySellWidget
          variant="overlay"
          baseCurrencyCode="eth"
          baseCurrencyAmount="0.045"
          visible={visible}
        />
        <button onClick={() => setVisible(!visible)}>Toggle widget</button>
      </>
    );
  }
  ```
</CodeGroup>

## URL signing

If you're using the `walletAddress` or `walletAddresses` query param, you need to sign your widget URL before you can display the widget. Learn more about [URL signing](/widget/on-ramp-enhance-security-using-signed-urls).

Each of our React components provides an `onUrlSignatureRequested` prop that takes an asynchronous function which is called whenever the URL is updated. It takes an argument of the current URL and the return value should be your generated signature, acquired by some means from your backend by signing the given URL. The widget then takes this returned signature and updates its URL to include it.

```typescript theme={null}
import { MoonPayBuyWidget } from "@moonpay/moonpay-react";

const handleGetSignature = async (url: string): Promise<string> => {
  const signature = await fetch(
    `https://YOUR_API_DOMAIN.com/sign-url?url=${url}`,
  );
  return signature;
};

export default function Home() {
  return (
    <>
      <MoonPayBuyWidget
        variant="overlay"
        baseCurrencyCode="usd"
        baseCurrencyAmount="100"
        defaultCurrencyCode="eth"
        onUrlSignatureRequested={handleGetSignature}
        visible
      />
    </>
  );
}
```


# SDK Ramp Events
Source: https://dev.moonpay.com/widget/on-ramp-sdk-events-details



## Interface: RampsChildToParentInterface

This interface represents the events that the Widget SDK can trigger from within the MoonPay Widget to partners' parent applications.

This allows partner apps to be informed and adapt to certain widget lifecycle events.

### Hierarchy

* `RampsSwapsKycChildToParentInterface`

  ↳ **`RampsChildToParentInterface`**

### Methods

#### `onAuthToken`

This event is only fired for those integrating with our Swaps (SDK+API) product.

`onAuthToken(props): Promise<void>`

Fired when the partner needs to receive an updated customer auth token so they can perform authorized actions on behalf of the customer.

**Parameters**

| Name    | Type                                                                         |
| ------- | ---------------------------------------------------------------------------- |
| `props` | [`OnAuthTokenProps`](/widget/on-ramp-sdk-events-properties#onauthtokenprops) |

**Returns**

`Promise<void>`

**Inherited from**

`RampsSwapsKycChildToParentInterface.onAuthToken`

#### `onClose`

`onClose(): Promise<void>`

Fired when the Widget is closing, triggered by either system logic or user actions.

**Returns**

`Promise<void>`

#### `onInitiateDeposit`

`onInitiateDeposit(props): Promise<OnInitiateDepositReplyProps>`

Called in the integrated sell flow, in the transaction tracker, when the widget is waiting for the sell amount to be deposited by the customer.

This allows the partner to trigger a deposit right from their wallet app.

**Parameters**

| Name    | Type                                                                                     |
| ------- | ---------------------------------------------------------------------------------------- |
| `props` | [`OnInitiateDepositProps`](/widget/on-ramp-sdk-events-properties#oninitiatedepositprops) |

**Returns**

`Promise`\<[`OnInitiateDepositReplyProps`](/widget/on-ramp-sdk-events-properties#oninitiatedepositreplyprops)>

#### `onLogin`

`onLogin(props): Promise<void>`

Fired when the customer logs in or their authentication is refreshed.

**Parameters**

| Name    | Type                                                                 |
| ------- | -------------------------------------------------------------------- |
| `props` | [`OnLoginProps`](/widget/on-ramp-sdk-events-properties#onloginprops) |

**Returns**

`Promise<void>`

#### `onReady`

`onReady(): Promise<void>`

Fired when the SDK's communication layer has been set up and the Widget is loaded.

**Returns**

`Promise<void>`

#### `onSwapsCustomerSetupComplete`

`onSwapsCustomerSetupComplete(): Promise<void>`

Fired when the Swaps Customer Setup flow has completed signaling to the parent app that the widget may now be closed.

**Returns**

`Promise<void>`

**Inherited from**

`RampsSwapsKycChildToParentInterface.onSwapsCustomerSetupComplete`

#### `onTransactionCreated`

`onTransactionCreated**(props): Promise<void>`

Fired when a buy or sell transaction is created, just before redirecting to the transaction tracker.

**Parameters**

| Name    | Type                                                                                           |
| ------- | ---------------------------------------------------------------------------------------------- |
| `props` | [`OnTransactionCreatedProps`](/widget/on-ramp-sdk-events-properties#ontransactioncreatedprops) |

**Returns**

`Promise<void>`

#### `onTransactionCompleted`

`onTransactionCompleted(props): Promise<void>`

Fired when a transaction is detected as completed or if a previously completed transaction is loaded again in the transaction tracker.

**Parameters**

| Name    | Type                                                                                               |
| ------- | -------------------------------------------------------------------------------------------------- |
| `props` | [`OnTransactionCompletedProps`](/widget/on-ramp-sdk-events-properties#ontransactioncompletedprops) |

**Returns**

`Promise<void>`

#### `onUnsupportedRegion`

`onUnsupportedRegion(): Promise<void>`

Fired when the Unsupported Region screen is triggered, independently of whether the widget redirects away from it.

**Returns**

`Promise<void>`


# SDK Event Properties
Source: https://dev.moonpay.com/widget/on-ramp-sdk-events-properties



## Interfaces

* [RampsChildToParentInterface](/widget/on-ramp-sdk-events-details#interface-rampschildtoparentinterface)

## Type Aliases

### CryptoCurrency

**CryptoCurrency**: `Object`

Represents a Crypto currency such as ETH

**Type declaration**

| Name              | Type               | Description                                                  |
| ----------------- | ------------------ | ------------------------------------------------------------ |
| `chainId`         | `string` \| `null` | The chain's Chain ID                                         |
| `code`            | `string`           | The code of the currency such as "eth"                       |
| `coinType`        | `string` \| `null` | The coin type as defined in SLIP-0044                        |
| `contractAddress` | `string` \| `null` | The address location of the token contract on the blockchain |
| `id`              | `string`           | The identifier of the crypto currency                        |
| `name`            | `string`           | The human readable name of the currency such as "Ethereum"   |
| `networkCode`     | `string` \| `null` | The currency's network such as "bitcoin" or "ethereum"       |

### FiatCurrency

**FiatCurrency**: `Object`

Represents a Fiat currency such as USD

**Type declaration**

| Name   | Type     | Description                                                 |
| ------ | -------- | ----------------------------------------------------------- |
| `code` | `string` | The code of the currency such as "usd"                      |
| `id`   | `string` | The identifier of the fiat currency                         |
| `name` | `string` | The human readable name of the currency such as "US Dollar" |

### OnAuthTokenProps

**OnAuthTokenProps**: `Object` This event is only fired for those integrating with our Swaps (SDK+API) product.

**Type declaration**

| Name        | Type     | Description                                                                    |
| ----------- | -------- | ------------------------------------------------------------------------------ |
| `csrfToken` | `string` | The customer's CSRF token. Only provided to authorized integrations.           |
| `token`     | `string` | The customer's authentication token. Only provided to authorized integrations. |

***

### OnInitiateDepositProps

**OnInitiateDepositProps**: `Object`

**Type declaration**

| Name                                       | Type                                                                     | Description                                                                  |
| ------------------------------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `cryptoCurrency`                           | [`CryptoCurrency`](/widget/on-ramp-sdk-events-properties#cryptocurrency) | The crypto currency that is being off-ramped                                 |
| `cryptoCurrencyAmount`                     | `string`                                                                 | Crypto amount in its base unit (0.123 ETH === "0.123")                       |
| `cryptoCurrencyAmountSmallestDenomination` | `string`                                                                 | Crypto amount in its smallest unit (1 ETH === 1x10^18)                       |
| `depositWalletAddress`                     | `string`                                                                 | The wallet address where the crypto amount needs to be deposited             |
| `fiatCurrency`                             | [`FiatCurrency`](/widget/on-ramp-sdk-events-properties#fiatcurrency)     | The fiat currency that the customer will receive                             |
| `fiatCurrencyAmount`                       | `string` \| `null`                                                       | Fiat amount in its base unit (\$1.23 === "1.23"). Only set for fixed quotes. |
| `transactionId`                            | `string`                                                                 | The identifier of the transaction                                            |

### OnInitiateDepositReplyProps

**OnInitiateDepositReplyProps**: `Object`

**Type declaration**

| Name        | Type     | Description                                                                                    |
| ----------- | -------- | ---------------------------------------------------------------------------------------------- |
| `depositId` | `string` | The partner's identifier for a successful deposit. Can be any string, eg the transaction hash. |

### OnLoginProps

**OnLoginProps**: `Object`

**Type declaration**

| Name        | Type      | Description                                                                                 |
| ----------- | --------- | ------------------------------------------------------------------------------------------- |
| `isRefresh` | `boolean` | If true, the customer didn't actually log in but rather their authentication was refreshed. |

### OnTransactionCreatedProps

**OnTransactionCompletedProps**: `Object`

**Type declaration**

| Name                 | Type                                                                                                                                                                     | Description                           |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------- |
| `baseCurrency`       | [`FiatCurrency`](/widget/on-ramp-sdk-events-properties#fiatcurrency)                                                                                                     | The base (fiat) currency              |
| `baseCurrencyAmount` | `number`                                                                                                                                                                 | The spent fiat amount                 |
| `id`                 | `string`                                                                                                                                                                 | The identifier of the transaction     |
| `status`             | [`TransactionStatus`](/widget/on-ramp-sdk-events-properties#transactionstatus) \| [`SellTransactionStatus`](/widget/on-ramp-sdk-events-properties#selltransactionstatus) | The current status of the transaction |

### OnTransactionCompletedProps

**OnTransactionCompletedProps**: `Object`

**Type declaration**

| Name                  | Type                                                                           | Description                                                         |
| --------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
| `areFeesIncluded`     | `boolean`                                                                      | Whether the base currency amount includes fees                      |
| `baseCurrency`        | [`FiatCurrency`](/widget/on-ramp-sdk-events-properties#fiatcurrency)           | The base (fiat) currency                                            |
| `baseCurrencyAmount`  | `number`                                                                       | The spent fiat amount                                               |
| `createdAt`           | `string`                                                                       | When the transaction was created                                    |
| `extraFeeAmount`      | `number`                                                                       | The partner's fee amount, in the fiat currency                      |
| `feeAmount`           | `number`                                                                       | The MoonPay fee amount, in the fiat currency                        |
| `id`                  | `string`                                                                       | The identifier of the transaction                                   |
| `networkFeeAmount`    | `number`                                                                       | The network fees incurred in this transaction, in the fiat currency |
| `quoteCurrency`       | [`CryptoCurrency`](/widget/on-ramp-sdk-events-properties#cryptocurrency)       | The quote (crypto) currency                                         |
| `quoteCurrencyAmount` | `number`                                                                       | The expected or received quote amount                               |
| `status`              | [`TransactionStatus`](/widget/on-ramp-sdk-events-properties#transactionstatus) | The current status of the transaction                               |
| `walletAddress`       | `string`                                                                       | The customer's destination wallet address                           |
| `walletAddressTag`    | `string` \| `null`                                                             | The customer's destination wallet address tag                       |

### TransactionStatus

**TransactionStatus**: `"completed"` | `"failed"` | `"pending"` | `"waitingAuthorization"` | `"waitingPayment"`

### SellTransactionStatus

**SellTransactionStatus**: `"completed"` | `"failed"` | `"pending"` | `"waitingForDeposit"`


# Web SDK
Source: https://dev.moonpay.com/widget/on-ramp-web-sdk



<Info>
  An example Web SDK On-Ramp integration can be found on our Github
  [here](https://github.com/moonpay/moonpay-demo-integrations).
</Info>

## Import

There are two options when integrating the web SDK.

You can load the SDK using the `script` tag approach, or if you prefer an npm package with full type-safety, you can use [moonpay-js](https://www.npmjs.com/package/@moonpay/moonpay-js). Both approaches provide the same level of end functionality, so which one you choose will be based on your preference and what works best for your project.

<CodeGroup>
  ```bash Install from npm theme={null}
  npm install @moonpay/moonpay-js
  ```

  ```bash Using a script tag theme={null}
  <script defer src="https://static.moonpay.com/web-sdk/v1/moonpay-web-sdk.min.js"></script>
  ```
</CodeGroup>

Once you've included the script or package, you're ready to initialize the Web SDK and start integrating with our suite of cryptocurrency payment solutions.

## Initialize

Initializing the SDK is largely similar for both the package approach and script approach.

The script approach attaches the SDK constructor (`init`) to `window.MoonPayWebSdk`, whereas the package provides an asynchronous function to load the constructor.

<CodeGroup>
  ```ts via import theme={null}
  import { loadMoonPay } from "@moonpay/moonpay-js";

  const moonPay = await loadMoonPay();
  ```

  ```bash Using a script tag theme={null}
  const moonPay = window.MoonPayWebSdk.init;
  ```
</CodeGroup>

Or if you've opted for the package, the exported `loadMoonPay` function returns the SDK constructor.

Now, initialize the SDK in your application with the flow, environment, variant, and any parameters related to [On-Ramp](/widget/ramps-sdk-buy-params), [Off-Ramp](/widget/ramps-sdk-sell-params) or Swap.

<CodeGroup>
  ```typescript Buy theme={null}
  const widget = moonPay?.({
    flow: "buy",
    environment: "sandbox",
    params: {
      apiKey: "pk_test_123",
    },
    variant: "overlay",
    handlers: {
      async onTransactionCompleted(props) {
        console.log("onTransactionCompleted", props);
      },
    },
  });

  widget?.show();

  ```

  ```typescript Sell theme={null}
  const widget = moonPay?.({
    flow: "sell",
    environment: "sandbox",
    params: {
      apiKey: "pk_test_123",
    },
    variant: "overlay",
    handlers: {
      async onInitiateDeposit(props) {
        console.log(
          "onInitiateDeposit",
          props.cryptoCurrency.id,
          props.depositWalletAddress,
        );
        // Here you'd do your own sign and send...
        return {
          depositId: "your-deposit-identifier",
        };
      },
    },
  });

  widget?.show();
  ```

  ```typescript Swap theme={null}
  const moonPaySdk = moonPay({
    flow: "swap",
    environment: "sandbox",
    variant: "overlay",
    params: {
      apiKey: "pk_test_key",
    },
  });
  ```

  ```typescript Swap (w/customer setup) theme={null}
  const widget = moonPay?.({
    flow: "swapsCustomerSetup",
    environment: "sandbox",
    variant: "overlay",
    params: {
      apiKey: "pk_test_123",
      amount: "300",
      amountCurrencyCode: "usd",
    },
    handlers: {
      async onAuthToken({ token }) {
        // Once the customer has logged in in the widget, we share their
        // swaps-scoped authentication token with your app so you can
        // perform swaps requests on behalf of the customer.
        // The token needs to be passed as an Authorization header in the format
        // "Authorization: Bearer {token}".
        console.log("onAuthToken received with token:", token);
      },
      async onSwapsCustomerSetupComplete() {
        // When this is received, you can close the widget and resume the
        // the swap flow in your UI.
        console.log("onSwapsCustomerSetupComplete received");
      },
    },
  });

  widget?.show();
  ```
</CodeGroup>

### Configuration

* Possible values for `flow`: buy, sell, swap, swapsCustomerSetup
* Possible values for `environment`: sandbox, production
* Possible values for `variant`: embedded, overlay, newTab, newWindow

## Variants

### Embedded

When using the `embedded` variant, you can embed the MoonPay widget within a specific DOM element on your website. This option lets you fine-tune the placement of the widget and allows you to integrate it into a specific part of your layout. This can minimize context switching for the user. To use this variant, you must pass the `containerNodeSelector` property and a valid CSS selector for the container element where you want the widget to be embedded.

### Overlay

The `overlay` variant shows the widget as an iframe on top of your website. This option directs the user's attention towards completing their purchase while keeping them on your website. We have an additional `onCloseOverlay` handler for this variant should you want to run some code in the event that the overlay is closed.

<Info>
  Mobile payments, such as Apple Pay and Google Pay, are not supported with
  Overlay because it operates within an iframe.
</Info>

### New tab

The `newTab` variant opens the widget in a new browser tab. This option lets the user complete their purchase in a full-screen experience. When using this option, we recommend you tell the user they'll be taken to MoonPay in a new tab. This provides guidance to the user that this is intended and part of the purchase flow.

### New window

The `newWindow` variant opens the widget in a new browser window with a fixed size. This variant is ideal if you want to provide a more controlled experience for the user while they complete their purchase.

## Display

Depending on your SDK implementation, especially within contexts like mobile app webviews, be aware of the `useWarnBeforeRefresh` configuration. It's set to `true` by default, which prompts users with a warning if they try to refresh the page or navigate away. This is designed to avoid any unintentional data loss or interruption of ongoing tasks. However, this can sometimes lead to errors during redirections back to your application. If you'd like to prevent this behavior, simply set the `useWarnBeforeRefresh` configuration to `false`.

```typescript highlight={5} theme={null}
const moonPaySdk = moonPay({
  flow: "buy",
  environment: "sandbox",
  variant: "overlay",
  useWarnBeforeRefresh: false,
  params: {
    apiKey: "pk_test_key",
  },
});
```

(e.g. Mobile app webview) there is a `useWarnBeforeRefresh` SDK configuration setting that is enabled by default and warns users before a page refresh or navigation action occurs to prevent loss of unsaved data or interrupting an ongoing process. As a result, an error may appear when users try to redirect back to your application. You can disable this by disabling `useWarnBeforeRefresh` and setting it to false.

## Signing

If you're using the `walletAddress` or `walletAddresses` query param, in the `buy` or `swap` flows, you need to sign your widget URL before you can display the widget. Learn more about [URL signing](/widget/on-ramp-enhance-security-using-signed-urls).

```ts server.ts theme={null}
const moonPaySdk = moonPay({}); // Configure your SDK

const urlForSignature = moonPaySdk.generateUrlForSigning();

// The URL for signature should be sent to your backend, which should then
// sign it with your API secret and return the signature.
const response = await fetch("/sign-url", {
  method: "POST",
  body: JSON.stringify({ urlForSignature }),
});
const data = await response.json();

// Once you have the signature, you can update the SDK with it and show the
// widget.
moonPaySdk.updateSignature(data.signature);

moonPaySdk.show();
```


# Overview
Source: https://dev.moonpay.com/widget/ramps-sdk-buy-params

The following parameters can be used to customize the user journey in the widget.

| Parameter                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey` required              | Your publishable API key. This is used to assign customers and transactions to your MoonPay account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `currencyCode`                 | The code of the cryptocurrency (e.g., btc, eth, matic) you want the customer to purchase. The customer will not be able to select another currency. To differentiate between networks, use the currency codes listed in the [MoonPay Dashboard](https://dashboard.moonpay.com/login?sessionExpired=true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `defaultCurrencyCode`          | The code of the cryptocurrency you would prefer the customer to purchase. The customer can still select another currency. If both `currencyCode` and `defaultCurrencyCode` are passed, `currencyCode` will take precedence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `walletAddress`                | The cryptocurrency wallet address the purchased funds will be sent to. If you pass a valid wallet address the customer won't be prompted to enter one.When pre-filling wallet addresses, you must pass `currencyCode` and [sign the URL](/widget/on-ramp-enhance-security-using-signed-urls). Values need to be URL encoded in order to generate a valid signature.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `walletAddressTag`             | The secondary cryptocurrency wallet address identifier/memo for coins such as EOS, XLM, XRP and XMR. This parameter will be skipped if `walletAddress` or `currencyCode` is not passed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `walletAddresses`              | A JSON string representing the wallet addresses you want to use for multiple cryptocurrencies. If the customer selects a cryptocurrency for which you have passed a valid wallet address, the customer won't be prompted to enter one. The currency code must be lowercase.An example for BTC and EOS: \{"btc":"tb1qst9rvjnhym6kwmdkwgfs4h5dtp7cau5346jp9x","eos":"eosmoonpay23"}If you use this parameter, only the cryptocurrencies for which you pass a wallet address will be shown to the customer, unless you also pass the `showAllCurrencies` parameter. If both `walletAddresses` and `walletAddress` are passed, `walletAddresses` takes precedence.For the following token types, you only need to provide a single wallet address: BEP-2, bnb BEP-20, bnb\_bsc ERC-20, eth EOS, eos Polygon, pol\_polygon TRC-20, trxWhen using this parameter, you must sign URLs. Learn more about [signing URLs](/widget/on-ramp-enhance-security-using-signed-urls). |
| `walletAddressTags`            | A JSON string representing the wallet address tags you want to use for various cryptocurrencies. An example with EOS and XRP wallet address tags: \{"eos":"myeostag","xrp":"0123456789"}.If the customer selects a cryptocurrency for which you have passed a valid wallet address tag, the customer won't be prompted to enter one. This parameter will be skipped if walletAddresses is not passed.If both `walletAddressTags` and `walletAddressTag` are passed, `walletAddressTags` takes precedence.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `colorCode`                    | The color code for the widget main color. It is used for buttons, links and highlighted text. Only hexadecimal codes are accepted, for example #FF2B8F. You can also apply a different color for dark mode by adding a comma separated color code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `theme`                        | Enable dark mode or light mode as the default appearance for the widget. Possible values are dark, light.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `themeId`                      | ID of the theme created for your application or website. See [Themes](/widget/on-ramp-personalize-appearance) page.**NB**: This parameter is seldom used. If you built your theme using the MoonPay dashboard theme builder, you do not need to use `themeId`, as this theme will be applied wherever you use your API key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `language`                     | The ISO 639-1 standard language code representing the language the widget should use.If you pass a code for a language we do not support, the widget will remain in the current default language. This is usually the language of the customer's browser; if we do not offer that language, the widget will use English (en).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `baseCurrencyCode`             | The code of the fiat currency (e.g. usd, aud, gbp) you want the customer to purchase with.Refer to our Currencies API to get a full list of supported currencies.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `baseCurrencyAmount`           | A positive integer representing how much fiat the customer wants to spend. Best used together with the `baseCurrencyCode` & `currencyCode` parameters.Refer to our Currencies API to get the minimum and maximum values for each currency.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `quoteCurrencyAmount`          | A positive integer representing how much crypto the customer wants to buy. Best used together with the `currencyCode` & `baseCurrencyCode` parameters.Refer to our Currencies API to get the minimum and maximum values for each currency.Note that if you pass both `baseCurrencyAmount` and `quoteCurrencyAmount`, the quote currency amount will take precedence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `contractAddress`\*\*          | The contract address of the token you want pre-selected for the user in the widget. \[Only supported for DeFi Buy integrations.]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `networkCode`\*\*              | Defines the network where the token contract exists (e.g., `solana`, `ethereum`). Must match the blockchain where the token contract is deployed. \[Only supported for DeFi Buy integrations.]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lockAmount`                   | Set this parameter to true to lock the `baseCurrencyAmount` set for the customer and prevent them from modifying it. This parameter will be skipped if `baseCurrencyAmount` is not passed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `email`                        | The customer's email address. If you pass a valid email address, the customer won't be prompted to enter one.If a customer is already logged in and their e-mail address doesn't match with the URL address, the customer will be logged out automatically.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `externalTransactionId`        | An identifier you would like to associate with the transaction. This identifier will be present whenever we pass you transaction data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `externalCustomerId`           | An identifier you would like to associate with the customer. This identifier will be present whenever we pass you customer data, allowing you to match our data with your own existing customer data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `paymentMethod`                | Pre-select the payment method you want the customer to use. Possible values are credit\_debit\_card, gbp\_bank\_transfer, gbp\_open\_banking\_payment, apple\_pay, google\_pay, sepa\_bank\_transfer, pix\_instant\_payment, interac, paypal, revolut\_pay, venmo and moonpay\_balance.If payment method is unavailable users will default to our payment selection screen.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `redirectURL`                  | A URL you'd like to redirect the customer to after they complete the buy flow in the widget. We will append the transaction's ID and status as query parameters to your URL.MoonPay will add transactionId=\{\{transactionId}}\&transactionStatus=pending to the redirectURL.HTTPS or Universal/App Link URLs are supported. Custom-scheme links (e.g., myapp\://…) are not supported.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `showAllCurrencies`            | Set this parameter true to show all cryptocurrencies enabled on your account, including those for which you did not pass any wallet address via the `walletAddresses` parameter. You don't need to set this if you did not use the `walletAddresses` parameter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `showOnlyCurrencies`           | A comma-separated list of currency codes. Set this parameter if you want to show only some of the cryptocurrencies enabled on your account, without having to pass wallet addresses for those currencies. If both the `walletAddresses` and `showOnlyCurrencies` parameters are passed we will only show matching currencies present in both fields. All other currencies will not be included.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `showWalletAddressForm`        | Set this parameter true to show the wallet address form, even though you've already passed a valid wallet address via the `walletAddress` or `walletAddresses` parameters. The customer will be able to see the valid wallet address, but will not be able to change it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `unsupportedRegionRedirectUrl` | A URL you'd like to redirect the customer upon coming from unsupported region. After the user lands on an unsupported region screen, they will be redirected to provided URL after 3 seconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `skipUnsupportedRegionScreen`  | Set this parameter to true if you want to skip the widget's unsupported region screen and immediately redirect the customer. If you set this parameter, you also need to set `unsupportedRegionRedirectUrl`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

\*\*Only supported for DeFi Buy integrations.


# Off-ramp widget parameters
Source: https://dev.moonpay.com/widget/ramps-sdk-sell-params

The following parameters can be used to customize the user journey in the widget.

| Parameter                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey` required              | Your publishable API key. This is used to assign customers and transactions to your MoonPay account.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `baseCurrencyCode`             | The code of the cryptocurrency you want the customer to sell. If you pass a `baseCurrencyCode`, the currency will be selected by default and the customer won't be able to select another currency.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `defaultBaseCurrencyCode`      | The code of the cryptocurrency you would prefer the customer to sell. If you pass a `defaultBaseCurrencyCode`, the currency will be selected by default, but the customer will still be able to select another currency.If both `baseCurrencyCode` and `defaultBaseCurrencyCode` are passed, `baseCurrencyCode` will take precedence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `refundWalletAddress`          | The cryptocurrency wallet address the funds will be sent to in case we have to issue a refund. If you pass a valid wallet address, the customer won't be prompted to enter one. This parameter will be skipped if `baseCurrencyCode` is not passed.It is mandatory to sign URLs when using this parameter. Learn about [signing URLs](/widget/off-ramp-enhance-security-using-signed-urls).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `refundWalletAddresses`        | A JSON string representing the wallet addresses you want to use for various cryptocurrencies in case we have to issue a refund. An example with BTC and BCH wallet addresses: \{"btc": "tb1qst9rvjnhym6kwmdkwgfs4h5dtp7cau5346jp9x", "bch": "bchtest:qraax8trdwct02968swqf4mpq3y5msqp8y7tmalm77"}If the customer selects a cryptocurrency for which you have passed a valid wallet address, the customer won't be prompted to enter one. If you use the `refundWalletAddresses` parameter, only the cryptocurrencies for which you pass a wallet address will be shown to the customer, unless you also pass the `showAllCurrencies` parameter. If both `refundWalletAddress` and `refundWalletAddresses` are passed, `refundWalletAddresses` takes precedence.When using this parameter, you must sign URLs. Learn about [signing URLs](/widget/off-ramp-enhance-security-using-signed-urls).            |
| `colorCode`                    | The color code for the widget main color. It is used for buttons, links and highlighted text. Only hexadecimal codes are accepted, for example: #FF2B8F.You can also apply a different color for dark mode by adding a comma separated color code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `theme`                        | Enable dark mode or light mode as the default appearance for the widget. Possible values: dark, light.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `themeId`                      | ID of the theme created for your application or website. See [Themes](/widget/customize-the-widgets-appearance) page.**NB**: This parameter is seldom used. If you built your theme using the MoonPay dashboard theme builder, you do not need to use `themeId`, as this theme will be applied wherever you use your API key.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `language`                     | The ISO 639-1 standard language code representing the language the widget should use.If you pass a code for a language we do not support, the widget will remain in the current default language. This is usually the language of the customer's browser; if we do not offer that language, the widget will use English (en).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `quoteCurrencyCode`            | The code of the fiat currency you want the customer to be paid in. Possible values: AUD BGN BRL CHF COP CZK DKK DOP EGP EUR GBP HKD IDR ILS JOD KES KWD LKR MXN NGN NOK NZD OMR PEN PLN RON SEK THB TRY USD VND ZARRefer to our [supported currencies list](https://support.moonpay.com/customers/docs/moonpays-supported-currencies#selling) for more information.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `baseCurrencyAmount`           | A positive number representing how much crypto the customer wants to sell. Refer to our [Currencies API](/api-reference/widget) to get the minimum and maximum values for each currency.If you pass a valid amount, the customer will go directly to the next steps of the widget (wallet address, login or bank details form). This parameter will be skipped if `baseCurrencyCode` is not passed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `quoteCurrencyAmount`          | A positive integer representing the fiat equivalent of crypto the customer wants to sell. Best used together with the `quoteCurrencyCode` & `baseCurrencyCode` parameters.Refer to our [Currencies API](/api-reference/widget) to get the minimum and maximum values for each currency.Note that if you pass both `baseCurrencyAmount` and `quoteCurrencyAmount`, the base currency amount will take precedence.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `lockAmount`                   | Set this parameter to true to lock the `baseCurrencyAmount` set for the customer and prevent them from modifying it. This parameter will be skipped if `baseCurrencyAmount` is not passed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `email`                        | The customer's email address. If you pass a valid email address, the customer won't be prompted to enter one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `externalTransactionId`        | An identifier you would like to associate with the transaction. This identifier will be present whenever we pass you transaction data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `externalCustomerId`           | An identifier you would like to associate with the customer. This identifier will be present whenever we pass you customer data, allowing you to match our data with your own existing customer data.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `paymentMethod`                | Pre-select the payout method you want the customer to use. Possible values are credit\_debit\_card, ach\_bank\_transfer,gbp\_bank\_transfer, gbp\_open\_banking\_payment, sepa\_bank\_transfer, paypal, venmo and moonpay\_balance.If payout method is unavailable users will default to our payout selection screen.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `redirectURL`                  | A URL you'd like to redirect the customer to after they complete the sell flow in the widget.We will append the transaction ID, base currency code, base currency amount, deposit wallet address and respective tag, if applicable, as query parameters to your URL.**NB**: If the deposit wallet address tag is included in the parameters, you must include this with the deposit otherwise the transaction will fail.For example, if you submit the URL [www.app.com](http://www.app.com), we will redirect the customer to [www.app.com/?transactionId=\{\{id}}\&baseCurrencyCode=\{\{code}}](http://www.app.com/?transactionId=%7B%7Bid%7D%7D\&baseCurrencyCode=%7B%7Bcode%7D%7D) \&baseCurrencyAmount=\{\{amount}}\&depositWalletAddress=\{\{address}}\&depositWalletAddressTag=\{\{tag}}.HTTPS or Universal/App Link URLs are supported. Custom-scheme links (e.g., myapp\://…) are not supported. |
| `showAllCurrencies`            | Set this parameter true if you always want to show all the cryptocurrencies enabled on your account, including those for which you did not pass any wallet address via the `refundWalletAddresses` parameter. You don't need to set this if you did not use the `refundWalletAddresses` parameter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `showWalletAddressForm`        | Set this parameter true if you always want to show the wallet address form, even though you've already passed a valid wallet address via the `refundWalletAddress` or `refundWalletAddresses` parameters. The customer will be able to see the valid wallet address, but will not be able to change it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `unsupportedRegionRedirectUrl` | A URL you'd like to redirect the customer upon coming from unsupported region. After the user lands on an unsupported region screen, they will be redirected to provided URL after 3 seconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `skipUnsupportedRegionScreen`  | Set this parameter true if you want to skip the widget's unsupported region screen and immediately redirect the customer. If you set this parameter, you also need to set `unsupportedRegionRedirectUrl`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |


# Requote Webhooks
Source: https://dev.moonpay.com/widget/requote-webhooks



## Sell Transaction Requote Required Webhook

### Overview

The `sell_transaction_requote_required` webhook notifies partners when a sell transaction requires a requote due to price changes or other market conditions.

This webhook enables partners to surface requote notifications in-app, providing a better user experience than email-only notifications.

**Webhook Type:** `sell_transaction_requote_required`

**Note:** API Reference coming soon!

### Use Case

When a sell transaction requires a requote, users traditionally receive only an email notification. This approach has several limitations:

* Users may not check their email immediately
* Email notifications can be missed or filtered to spam
* There's no in-app acknowledgment of the requote

By subscribing to this webhook, partners can:

* Display in-app notifications when requotes occur
* Prompt users to accept new quotes within your application
* Provide a seamless, high-intent user experience
* Reduce transaction abandonment due to missed requotes

### Webhook Payload

The webhook delivers a JSON payload with the following structure.

```json Example payload theme={null}
{
  "type": "sell_transaction_requote_required",
  "data": {
    "id": "transaction_id",
    "status": "requoteRequired",
    "createdAt": "2026-02-13T10:30:00.000Z",
    "updatedAt": "2026-02-13T11:45:00.000Z",
    "baseCurrencyAmount": 1000.0,
    "quoteCurrencyAmount": 950.0,
    "baseCurrency": "usdc",
    "quoteCurrency": "usd",
    "externalCustomerId": "customer_123",
    "walletAddress": "0x...",
    "externalTransactionId": "your_transaction_id"
  }
}
```

## Field Descriptions

| Field                        | Type              | Description                                                 |
| ---------------------------- | ----------------- | ----------------------------------------------------------- |
| `type`                       | string            | Always `sell_transaction_requote_required` for this webhook |
| `data.id`                    | string            | MoonPay transaction identifier                              |
| `data.status`                | string            | Transaction status (will be `requoteRequired`)              |
| `data.createdAt`             | string (ISO 8601) | Timestamp when the transaction was created                  |
| `data.updatedAt`             | string (ISO 8601) | Timestamp when the requote was triggered                    |
| `data.baseCurrencyAmount`    | number            | Amount of cryptocurrency to sell                            |
| `data.quoteCurrencyAmount`   | number            | Updated fiat amount the user will receive                   |
| `data.baseCurrency`          | string            | Cryptocurrency code (e.g., `usdc`, `btc`, `eth`)            |
| `data.quoteCurrency`         | string            | Fiat currency code (e.g., `usd`, `eur`, `gbp`)              |
| `data.externalCustomerId`    | string            | Your customer identifier (if provided)                      |
| `data.walletAddress`         | string            | Blockchain wallet address for the transaction               |
| `data.externalTransactionId` | string            | Your transaction identifier (if provided)                   |

***

## Subscribing to the Webhook

To receive `sell_transaction_requote_required` webhooks:

1. Configure your webhook endpoint in the MoonPay Dashboard or via API.

2. Add the webhook type to your subscription:
   * Navigate to **Settings → Webhooks** in your MoonPay Dashboard
   * Select `sell_transaction_requote_required` from the available webhook types
   * Ensure your endpoint is configured to handle `POST` requests

3. Verify your endpoint is properly configured and can receive webhooks.

***

## Implementation Guidelines

<Steps>
  <Step title="Webhook receipt">
    Your endpoint should:

    * Respond with a `200 OK` status code within 10 seconds
    * Process the webhook asynchronously if needed
    * Implement idempotency (handle duplicate webhook deliveries)
  </Step>

  <Step title="User notification">
    When receiving this webhook:

    * Display an in-app notification to the user
    * Show the updated `quoteCurrencyAmount` clearly
    * Provide a clear call-to-action to accept or decline the new quote
    * Include a timeout/expiration time for the requote
  </Step>

  <Step title="User action">
    Allow users to:

    * Accept the new quote and continue the transaction
    * Decline and cancel the transaction
    * View the price difference between original and requoted amounts
  </Step>

  <Step title="Security">
    * Verify webhook signatures to ensure authenticity (see Webhook Security section)
    * Use HTTPS endpoints only
    * Validate the webhook payload structure before processing
  </Step>
</Steps>

## Testing

### Sandbox Environment

Test the webhook in the MoonPay sandbox environment before going live:

* Use sandbox API keys from your MoonPay Dashboard
* Configure your webhook endpoint to receive sandbox webhooks
* Trigger test requotes to verify your implementation

### Verification Checklist

* Webhook endpoint responds with `200 OK`
* In-app notification displays correctly
* User can accept the new quote
* User can decline the requote
* Idempotency is handled properly
* Webhook signature verification is implemented

## Related Webhooks

Other sell transaction webhooks you may want to subscribe to:

* `sell_transaction_created` – When a sell transaction is initiated
* `sell_transaction_completed` – When a sell transaction completes successfully
* `sell_transaction_failed` – When a sell transaction fails

## Support

For questions or issues with this webhook:

* Email: [support@moonpay.com](mailto:support@moonpay.com)