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

If you don't have a MONEI account already, you’ll need to create one to use the GraphQL API.

Embedded GraphQL Explorer

Use the embedded GraphQL Explorer 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

If you want to start playing with the API immediately, you can do it in the GraphQL 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

The API uses API keys to authenticate requests. You can view and manage your API key in the MONEI Dashboard → Settings → API Access.

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)

MONEI Connect 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: <PARTNER_API_KEY>' \
--header 'MONEI-Account-ID: <MONEI_ACCOUNT_ID>' \
--header 'User-Agent: MONEI/<PARTNER_NAME>/<VERSION>' \
--header 'Content-Type: application/json' \
--data-raw '{"query":"{account {name status}}"}'

GraphQL API Endpoint

POST https://graphql.monei.com

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: <YOUR_API_KEY>' \
--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 in you MONEI Dashboard.

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

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

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

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

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)

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

Mutations are the equivalent of REST’s data-modifying action verbs.

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

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