Getting Started with the Merchant Data API

What you can do

Query payins -- Retrieve inbound payment transactions with filtering and pagination.
Query payouts -- Retrieve outbound payment transactions including settlement amounts.
Query claims -- Retrieve chargeback and dispute claims, including related payins.
Run aggregations -- Get totals and per-status breakdowns for any dataset.

All data is automatically scoped to your merchant account. You only see your own transactions.

Prerequisites

Before you begin, make sure you have:

A Shop ID -- Your numeric shop identifier, used as your API username.
An API token -- Your password for API authentication.

Contact your account manager if you do not have these credentials.

Authentication

Every request to the API requires HTTP Basic Authentication. Encode your Shop ID and API token as base64(YOUR_SHOP_ID:YOUR_API_TOKEN) and pass it in the Authorization header.

Authorization: Basic base64(YOUR_SHOP_ID:YOUR_API_TOKEN)

Your first query

The API exposes a single GraphQL endpoint at POST /graphql. All queries are sent as JSON POST requests to this endpoint.

The following query retrieves your 10 most recent payins within a date range:

GraphQL query

query {
  payins(
    first: 10
    filter: {
      createdDateFrom: "2026-01-01"
      createdDateTo: "2026-01-31"
    }
  ) {
    edges {
      node {
        transactionId
        amount
        currency
        transactionStatusName
        createdTs
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    summary {
      rowCount
      pageSizeLimit
    }
  }
}

curl

curl -X POST https://api.payretailers.com/data-api/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic $(echo -n 'YOUR_SHOP_ID:YOUR_API_TOKEN' | base64)" \
  -d '{
    "query": "query { payins(first: 10, filter: { createdDateFrom: \"2026-01-01\", createdDateTo: \"2026-01-31\" }) { edges { node { transactionId amount currency transactionStatusName createdTs } cursor } pageInfo { hasNextPage endCursor } summary { rowCount pageSizeLimit } } }"
  }'

Python

import requests
from requests.auth import HTTPBasicAuth

url = "https://api.payretailers.com/data-api/graphql"

query = """
query {
  payins(
    first: 10
    filter: {
      createdDateFrom: "2026-01-01"
      createdDateTo: "2026-01-31"
    }
  ) {
    edges {
      node {
        transactionId
        amount
        currency
        transactionStatusName
        createdTs
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    summary {
      rowCount
      pageSizeLimit
    }
  }
}
"""

response = requests.post(
    url,
    json={"query": query},
    auth=HTTPBasicAuth("YOUR_SHOP_ID", "YOUR_API_TOKEN"),
    headers={"Content-Type": "application/json"},
)

data = response.json()
print(data)

TypeScript

import axios from "axios";

const url = "https://api.payretailers.com/data-api/graphql";

const query = `
query {
  payins(
    first: 10
    filter: {
      createdDateFrom: "2026-01-01"
      createdDateTo: "2026-01-31"
    }
  ) {
    edges {
      node {
        transactionId
        amount
        currency
        transactionStatusName
        createdTs
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    summary {
      rowCount
      pageSizeLimit
    }
  }
}
`;

const credentials = Buffer.from("YOUR_SHOP_ID:YOUR_API_TOKEN").toString("base64");

const response = await axios.post(
  url,
  { query },
  {
    headers: {
      "Content-Type": "application/json",
      Authorization: `Basic ${credentials}`,
    },
  }
);

console.log(response.data);

Example response

{
  "data": {
    "payins": {
      "edges": [
        {
          "node": {
            "transactionId": "9c017f16-a41c-7040-8eb6-31030c7fea76",
            "amount": "55.03",
            "currency": "BRL",
            "transactionStatusName": "CANCELLED",
            "createdTs": "2026-01-31T23:59:15.167Z"
          },
          "cursor": "eyJ2IjoiMjAyNi0wMS0zMVQyMzo1OToxNS4xNjcw..."
        },
        {
          "node": {
            "transactionId": "9c015016-961c-7c45-9c1f-7e4d5393aef5",
            "amount": "60.00",
            "currency": "BRL",
            "transactionStatusName": "APPROVED",
            "createdTs": "2026-01-31T23:07:54.920Z"
          },
          "cursor": "eyJ2IjoiMjAyNi0wMS0zMVQyMzowNzo1NC45MjAw..."
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJ2IjoiMjAyNi0wMS0zMVQyMjowNjozNC44MjMw..."
      },
      "summary": {
        "rowCount": 10,
        "pageSizeLimit": 10
      }
    }
  }
}

Key concepts

Concept	Description
Cursor-based pagination	Results are paginated using opaque cursors. Pass the `endCursor` value as the `after` argument to fetch the next page.
Date range governance	Queries are limited to a 90-day date window by default. If you omit dates, the API returns the last 90 days.
Pinpoint filters	Filtering by `transactionId`, `trackingId`, `personId`, or `claimId` bypasses the default date range restriction.
Page size	Default is 1000 records per page. Maximum is 5000. Use the `first` argument to control page size.
Concurrent query limits	Your merchant account can run up to 10 queries simultaneously.
Query timeout	Queries that exceed 15 seconds are automatically cancelled.

Endpoint

The API is available at a single production endpoint:

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

See the Environments guide for details.

Next steps

Authentication -- Learn about PII access headers and security best practices.
Pagination, Filtering, and Sorting -- Master cursor-based pagination and all available filters.
Error Handling -- Understand the error envelope and build resilient integrations.
Data Model Reference -- Explore all entity fields, types, and relationships.