Getting Started with the Merchant Data API

The PayRetailers Merchant Data API is a read-only GraphQL API. It lets you query your
shop's transactional and balance data: payins, payouts, claims, movement balances, and
daily report balances, plus count and sum aggregations. Every result is automatically
scoped to the merchant resolved from your credentials.

There are no mutations and no subscriptions. Every operation is a query, and every query
is safe to repeat.

What you need

• Your Shop ID (the numeric shop identifier used as your API username).
• Your API token (used as your password).

If you do not have these, contact your PayRetailers account manager.

The endpoint

The API exposes a single HTTP endpoint:

POST https://api.payretailers.com/data-api/graphql

Send a JSON body containing your GraphQL query, optional variables, and optional
operationName. Authenticate every request with HTTP Basic authentication using your
Shop ID as the username and your API token as the password.

Your first query

The ping field is the simplest query. It returns the literal string "pong" and
confirms your credentials work end to end.

Request

curl -X POST https://api.payretailers.com/data-api/graphql \
  -u "YOUR_SHOP_ID:YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "query Ping { ping }"}'

Response

{
  "data": {
    "ping": "pong"
  }
}

If your credentials are missing or invalid, you receive an error instead:

{
  "errors": [
    {
      "message": "Your credentials are missing or could not be validated.",
      "extensions": {
        "code": "UNAUTHORIZED",
        "retryable": false
      }
    }
  ]
}

See Authentication for details, and
Error handling for the full list of error codes.

Querying your data

Once ping works, query real data. The following example lists the most recent payins
for June 2026, using cursor pagination.

Request

curl -X POST https://api.payretailers.com/data-api/graphql \
  -u "YOUR_SHOP_ID:YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query Payins($first: Int, $filter: PayinFilterInput) { payins(first: $first, filter: $filter) { edges { cursor node { transactionId amount currency transactionStatusName createdTs } } pageInfo { hasNextPage endCursor } summary { rowCount pageSizeLimit totalCount } } }",
    "variables": {
      "first": 50,
      "filter": { "createdDateFrom": "2026-06-01", "createdDateTo": "2026-06-30" }
    },
    "operationName": "Payins"
  }'

Response

{
  "data": {
    "payins": {
      "edges": [
        {
          "cursor": "eyJ0IjoiMjAyNi0wNi0xNSJ9",
          "node": {
            "transactionId": "PI-9000123",
            "amount": "250.00",
            "currency": "BRL",
            "transactionStatusName": "APPROVED",
            "createdTs": "2026-06-15T14:03:22Z"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJ0IjoiMjAyNi0wNi0xNSJ9"
      },
      "summary": {
        "rowCount": 1,
        "pageSizeLimit": 50,
        "totalCount": 1284
      }
    }
  }
}

What you can query

For the full field list of each type, see the
Data model reference.

Governance you should know about

The API applies automatic limits to protect the platform and ensure fair access:

• Page size: default 1000 items, hard cap 5000.
• Date window: default and maximum 90 days for most datasets; movement balances
  default 1 day and maximum 31 days.
• Query timeout: 15 seconds.
• Query depth: maximum 10 levels.
• Cursors: expire after 4 hours.
• Concurrent queries: up to 10 in flight per merchant, 200 platform-wide.

Exceeding a limit returns a deterministic error code. See Rate limits
and Pagination, filtering, and sorting.

Next steps

• Authentication — how credentials work.
• Pagination, filtering, and sorting — page through results.
• Error handling — interpret and recover from errors.
• Data model reference — every field on every type.
• Testing guide — validate your integration.