Using the Platform API

Looking for the widget API? Take a look at the reference here.

Capability enablement

Capability access is enabled per partner. Some Platform API capabilities must be enabled on your account by MoonPay before you can call them. Requests to an endpoint for a capability that is not enabled fail with a plain 404 (Cannot POST /...) rather than a permissions error. If you get an unexpected 404 on an endpoint you expect access to, contact your MoonPay account team or support@moonpay.com to have the capability enabled.

Base URL

https://api.moonpay.com

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.

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 in the X-Api-Key header.

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",
  }),
});

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"
  }'

Client-side Authentication

For client-side API requests, use the accessToken returned from a connection as a Bearer token.

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

Response Format

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

Pagination

Some requests, like listing transactions, 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:

{
  "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:

Example

X-Request-Id: some-value

Error Handling

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

Example error response

{
  "code": 400,
  "type": "Invalid request",
  "message": "Invalid request. sourceAmount must be greater than 0."
}

OpenAPI

The API follows the OpenAPI 3.1 specification. You can use the spec to generate typed clients for any language. See the OpenAPI Spec page for the full specification and code generation instructions.

Documentation

Sessions

Customers

Payment Methods

Quotes

Transactions

Objects & Types

Capability enablement

Base URL

Authentication

Server-side Authentication

Client-side Authentication

Response Format

Rate limits

Debugging

Error Handling

OpenAPI

​Capability enablement

​Base URL

​Authentication

​Server-side Authentication

​Client-side Authentication

​Response Format

​Pagination

​Rate limits

​Debugging

​Error Handling

​OpenAPI

Capability enablement

Base URL

Authentication

Server-side Authentication

Client-side Authentication

Response Format

Pagination

Rate limits

Debugging

Error Handling

OpenAPI