# MONEI GraphQL API With MONEI GraphQL API you have full access to all MONEI features like analytics reports, payments, events, and much more. This API requires authentication and is intended to be used server side. Both **merchants** (their own account) and **[MONEI Connect](https://docs.monei.com/monei-connect/.md) partners** (acting on behalf of linked merchant accounts) can use it. If you want to know how GraphQL API works, check out [How to GraphQL](https://www.howtographql.com/). If you don't have a MONEI account already, you’ll need to [create](https://dashboard.monei.com/signup) one to use the GraphQL API. ## Embedded GraphQL Explorer[​](#embedded-graphql-explorer "Direct link to Embedded GraphQL Explorer") Use the [embedded GraphQL Explorer](https://docs.monei.com/apis/graphql/explorer/.md) to try the API directly from these docs. Paste any test-mode API key, browse the schema, and run queries against `https://graphql.monei.com/`. Every operation page (queries and mutations) has an "Open in Explorer ↗" link that pre-fills a stub query. No merchant login required. ## GraphQL API Explorer[​](#graphql-api-explorer "Direct link to GraphQL API Explorer") If you want to start playing with the API immediately, you can do it in the [GraphQL API Explorer](https://dashboard.monei.com/api-explorer) of your MONEI account. You can run Queries and Mutations in the explorer to see what the MONEI GraphQL API can offer you. The API Explorer is available to all MONEI users. note **Heads up!** MONEI's GraphQL Explorer makes use of your real, live, production data. ## Authentication[​](#authentication "Direct link to Authentication") The API uses API keys to authenticate requests. You can view and manage your API key in the [MONEI Dashboard → Settings → API Access](https://dashboard.monei.com/settings/api). ![API Access page in the MONEI Dashboard settings, showing your account ID and API key](/img/dashboard/en/settings-api-access.png) API Access page in the MONEI Dashboard settings, showing your account ID and API key Your API key enables full access to all MONEI resources, so be sure to keep it secure! Do not share your secret API key in publicly accessible areas such as GitHub, client-side code, and so forth. Include your API Key as an `Authorization` header in all your GraphQL requests. ### Partner authentication (MONEI Connect)[​](#partner-authentication-monei-connect "Direct link to Partner authentication (MONEI Connect)") [MONEI Connect](https://docs.monei.com/monei-connect/.md) partners use their **Partner API Key** plus a `MONEI-Account-ID` header naming the merchant account they're acting on behalf of. All queries and mutations on this page work identically — only the headers change. ``` curl --request POST 'https://graphql.monei.com' \ --header 'Authorization: ' \ --header 'MONEI-Account-ID: ' \ --header 'User-Agent: MONEI//' \ --header 'Content-Type: application/json' \ --data-raw '{"query":"{account {name status}}"}' ``` ## GraphQL API Endpoint[​](#graphql-api-endpoint "Direct link to GraphQL API Endpoint") ``` POST https://graphql.monei.com ``` ## Query GraphQL API[​](#query-graphql-api "Direct link to Query GraphQL API") You can access GraphQL API endpoint using cURL or any other HTTP client. ``` curl --request POST 'https://graphql.monei.com' \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data-raw '{"query":"{account {name status}}"}' ``` note You can explore GraphQL API Queries and Mutations in the interactive [GraphQL API Explorer](https://dashboard.monei.com/api-explorer) in you MONEI Dashboard. ## Example Queries[​](#example-queries "Direct link to Example Queries") In GraphQL, queries are the equivalent of REST’s GET action verb. Even though a POST is being sent to the GraphQL endpoint, if the body only contains queries, data will only be retrieved and not modified. The examples below mirror the queries the MONEI Dashboard itself runs — drop them into the [GraphQL Explorer](https://docs.monei.com/apis/graphql/explorer/.md) to see real data from your account. note All monetary fields are returned in the **smallest currency unit** (cents for EUR/USD). `1234` in EUR means `€12.34`. Timestamps for KPI/filter ranges are **unix seconds**. #### Retrieve a single payment[​](#retrieve-a-single-payment "Direct link to Retrieve a single payment") Look up one charge by ID — the core fields shown on the Dashboard payment-detail page. ``` query GetPayment($id: ID!) { charge(id: $id) { id orderId amount currency status statusCode statusMessage refundedAmount authorizationCode createdAt customer { email name phone } paymentMethod { method card { brand country last4 threeDSecure } } metadata { key value } } } ``` ``` { "id": "bc8eb8588e175ce4c957212f17ca051a" } ``` #### List payments with filters[​](#list-payments-with-filters "Direct link to List payments with filters") Powers the Dashboard **Payments** table — filter by date range, status, store, currency, customer email, etc. `range` takes two unix-second timestamps; `match` is exact; `matchPhrase` is case-insensitive. ``` query ListPayments($filter: SearchableChargeFilterInput, $search: String, $size: Int, $from: Int) { charges(filter: $filter, search: $search, size: $size, from: $from) { total items { id orderId amount currency status createdAt customer { email } paymentMethod { method card { brand last4 } } } } } ``` ``` { "filter": { "createdAt": {"range": [1748304000, 1748390399]}, "status": {"match": "SUCCEEDED"}, "currency": {"match": "EUR"} }, "size": 25, "from": 0 } ``` #### KPI report — payments over a date range[​](#kpi-report--payments-over-a-date-range "Direct link to KPI report — payments over a date range") Powers the **Dashboard overview** chart and KPI cards. Returns aggregated totals plus a time-bucketed series (`minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`) for the chosen currency. ``` query ChargesKPI( $start: Int! $end: Int! $interval: Interval! $timezone: String $currency: Currencies $storeId: ID ) { chargesDateRangeKPI( start: $start end: $end interval: $interval timezone: $timezone currency: $currency storeId: $storeId ) { currency total { succeededAmount succeededCount refundedAmount refundedCount failedCount capturedAmount directAmount } data { timestamp succeededAmount succeededCount refundedCount failedCount } } } ``` ``` { "start": 1745020800, "end": 1747612799, "interval": "day", "timezone": "Europe/Madrid", "currency": "EUR" } ``` Derived KPIs (compute client-side from `total`): * **Authorization rate** — `succeededCount / (succeededCount + failedCount)` * **Refund rate** — `refundedAmount / succeededAmount` * **Average ticket** — `succeededAmount / succeededCount` #### Subscriptions[​](#subscriptions "Direct link to Subscriptions") Active recurring billing — filter and paginate the same way as `charges`. ``` query ListSubscriptions($filter: SearchableSubscriptionFilterInput, $size: Int, $from: Int) { subscriptions(filter: $filter, size: $size, from: $from) { total items { id status amount currency interval intervalCount nextPaymentAt customer { email name } } } } ``` ``` { "filter": {"status": {"match": "ACTIVE"}}, "size": 25, "from": 0 } ``` #### Charge events (audit trail)[​](#charge-events-audit-trail "Direct link to Charge events (audit trail)") Every state change on a charge — useful for reconciliation, support, and debugging webhook delivery. ``` query ChargeEvents($chargeId: ID!, $size: Int, $from: Int) { chargeEvents(chargeId: $chargeId, size: $size, from: $from) { total items { id type createdAt object { status statusCode statusMessage amount refundedAmount } } } } ``` ## Example Mutations[​](#example-mutations "Direct link to Example Mutations") Mutations are the equivalent of REST’s data-modifying action verbs. #### Refund a payment[​](#refund-a-payment "Direct link to Refund a payment") Full or partial refund. `amount` is in minor units and required — pass the full original amount for a full refund. ``` mutation Refund($input: RefundPaymentInput!) { refundPayment(input: $input) { id status amount refundedAmount lastRefundAmount lastRefundReason } } ``` ``` { "input": { "paymentId": "bc8eb8588e175ce4c957212f17ca051a", "amount": 500, "refundReason": "requested_by_customer" } } ``` #### Capture an authorized payment[​](#capture-an-authorized-payment "Direct link to Capture an authorized payment") For `AUTH`-flow payments — captures funds previously authorized. Payment must be in `AUTHORIZED` status. Omit `amount` to capture the full authorized amount; capturing less auto-refunds the difference. ``` mutation Capture($input: CapturePaymentInput!) { capturePayment(input: $input) { id status amount authorizationCode } } ``` ``` { "input": { "paymentId": "bc8eb8588e175ce4c957212f17ca051a", "amount": 1000 } } ```