--- updatedAt: 2026-07-17T12:57:07.000Z --- Fetch the complete documentation index at: https://www.payretailers.dev/llms.txt. Use this file to discover all available pages before exploring further. # Data Model Reference This reference documents all entity types, fields, connections, filter inputs, and supporting types in the Merchant Data API. # Data Model Reference This reference lists every queryable type, its fields, and the filters that apply to it. All fields are read-only. Monetary amounts use the `Money` scalar (a decimal string with exactly two decimal places, for example `"250.00"`) and are paired with an ISO 4217 `currency` code where applicable. ## Scalars | Scalar | Representation | Example | | ---------- | ---------------------------------------- | ------------------------ | | `Money` | Decimal string, exactly 2 decimal places | `"250.00"` | | `Currency` | ISO 4217 three-letter uppercase code | `"BRL"` | | `Date` | Calendar date, `YYYY-MM-DD` | `"2026-06-30"` | | `DateTime` | RFC 3339 / ISO 8601 timestamp | `"2026-06-15T14:03:22Z"` | ## Query fields | Field | Returns | Arguments | | ------------------- | -------------------------- | ---------------------------------------------------------- | | `ping` | String (`"pong"`) | none | | `currentMerchantId` | String | none | | `payins` | Payin connection | `first`, `after`, `filter: PayinFilterInput` | | `payouts` | Payout connection | `first`, `after`, `filter: PayoutFilterInput` | | `claims` | Claim connection | `first`, `after`, `filter: ClaimFilterInput` | | `movementBalances` | MovementBalance connection | `first`, `after`, `filter: MovementBalanceFilterInput` | | `reportBalances` | ReportBalance collection | `filter: ReportBalanceFilterInput` | | `aggregations` | AggregationResult | `dataset: DatasetKind!`, `filter: AggregationFilterInput!` | ## Payin An incoming payment transaction made to your shop. Some customer and payer fields are personally identifiable and may be masked depending on your access level (see [Security and compliance](security-compliance.md)). | Field | Type | Notes | | -------------------------- | -------- | ------------------------------------------------ | | `merchantId` | Int | Scoped to your account. | | `merchantName` | String | | | `transactionId` | String | Payin ID. Cursor key; exact-match filterable. | | `trackingId` | String | Your external reference; exact-match filterable. | | `amount` | Money | | | `currency` | Currency | | | `createdDate` | Date | | | `createdTs` | DateTime | Secondary cursor key. | | `editedTs` | DateTime | | | `transactionStatusName` | String | Status label; filterable via `status`. | | `transactionDescription` | String | | | `countryName` | String | | | `shopId` | Int | | | `shopName` | String | | | `paymentMethodId` | Int | | | `paymentMethodName` | String | | | `paymentChannelTypeCode` | String | | | `customerEmail` | String | Personally identifiable; may be masked. | | `customerPersonalId` | String | Personally identifiable; may be masked. | | `isTest` | Boolean | | | `origin` | String | | | `customerFullName` | String | Personally identifiable; may be masked. | | `customerAddress` | String | Personally identifiable; may be masked. | | `customerCity` | String | Personally identifiable; may be masked. | | `customerPostalCode` | String | Personally identifiable; may be masked. | | `customerState` | String | Personally identifiable; may be masked. | | `customerPhone` | String | Personally identifiable; may be masked. | | `customerIp` | String | Personally identifiable; may be masked. | | `bankName` | String | | | `bankCountryName` | String | | | `notificationUrl` | String | | | `couponAmount` | Money | | | `bankAccountType` | String | | | `uniqueCustomerIdentifier` | String | Personally identifiable; may be masked. | | `couponCurrencyCode` | String | | | `payerPersonalId` | String | Personally identifiable; may be masked. | | `payerAccountNumber` | String | Personally identifiable; may be masked. | | `payerFullName` | String | Personally identifiable; may be masked. | | `payerEmail` | String | Personally identifiable; may be masked. | | `payerCity` | String | Personally identifiable; may be masked. | | `payerPhone` | String | Personally identifiable; may be masked. | | `payerAddress` | String | Personally identifiable; may be masked. | | `payerBankName` | String | | | `errorReason` | String | | | `standardizedError` | String | | | `normalisedErrorReason` | String | British spelling as returned on the wire. | `PayinFilterInput`: `transactionId`, `trackingId`, `shopId`, `status`, `personId`, `customerEmail`, `countryName`, `paymentMethodName`, `amountFrom`, `amountTo`, `createdDateFrom`, `createdDateTo`, `editedDateFrom`, `editedDateTo`. ## Payout An outgoing payment transaction from your shop, including a settlement amount and beneficiary and bank details. Some fields are personally identifiable and may be masked. | Field | Type | Notes | | ------------------------ | -------- | ------------------------------------------------ | | `merchantId` | Int | | | `merchantName` | String | | | `transactionId` | String | Payout ID. Cursor key; exact-match filterable. | | `trackingId` | String | Your external reference; exact-match filterable. | | `amount` | Money | | | `currency` | Currency | | | `settlementAmount` | Money | Amount actually settled to you. | | `createdDate` | Date | | | `createdTs` | DateTime | Secondary cursor key. | | `editedTs` | DateTime | | | `transactionStatusName` | String | | | `transactionDescription` | String | | | `countryName` | String | | | `shopId` | Int | | | `shopName` | String | | | `customerEmail` | String | Personally identifiable; may be masked. | | `customerPhone` | String | Personally identifiable; may be masked. | | `customerAddress` | String | Personally identifiable; may be masked. | | `customerCity` | String | Personally identifiable; may be masked. | | `customerPersonalId` | String | Personally identifiable; may be masked. | | `customerDocumentType` | String | | | `isTest` | Boolean | | | `paidDate` | Date | | | `paidTs` | DateTime | | | `beneficiaryFullName` | String | Personally identifiable; may be masked. | | `beneficiaryTypeCode` | String | | | `payoutAccountTypeCode` | String | | | `accountNumber` | String | Personally identifiable; may be masked. | | `accountAgencyNumber` | String | | | `bankName` | String | | | `recipientPixKey` | String | Personally identifiable; may be masked. | | `normalisedErrorReason` | String | British spelling as returned on the wire. | `PayoutFilterInput`: `transactionId`, `trackingId`, `shopId`, `status`, `personId`, `customerEmail`, `countryName`, `amountFrom`, `amountTo`, `settlementAmountFrom`, `settlementAmountTo`, `createdDateFrom`, `createdDateTo`, `editedDateFrom`, `editedDateTo`. ## Claim A dispute or chargeback against a transaction. Exposes the payins it relates to via `relatedPayins` (claims link to payins only). | Field | Type | Notes | | ---------------- | -------- | ------------------------------------------------- | | `merchantId` | Int | | | `merchantName` | String | | | `claimId` | String | Claim ID. Cursor key; exact-match filterable. | | `transactionId` | String | The disputed transaction; exact-match filterable. | | `amount` | Money | | | `createdDate` | Date | | | `createdTs` | DateTime | Secondary cursor key. | | `editedTs` | DateTime | | | `status` | String | Claim status label; filterable via `status`. | | `claimReason` | String | Filterable. | | `shopId` | Int | | | `shopName` | String | | | `processedDate` | Date | Resolution date. | | `processedTs` | DateTime | | | `comments` | String | | | `refundedAmount` | Money | | | `amountInFavor` | Money | | | `claimFee` | Money | | | `relatedPayins` | \[Payin] | The payins linked to this claim. | `ClaimFilterInput`: `claimId`, `transactionId`, `shopId`, `status`, `claimReason`, `amountFrom`, `amountTo`, `refundedAmountFrom`, `refundedAmountTo`, `createdDateFrom`, `createdDateTo`, `processedDateFrom`, `processedDateTo`. ## MovementBalance A single balance-affecting operation. Contains no personally identifiable data. | Field | Type | Notes | | --------------------- | -------- | ------------------------------------------------- | | `merchantId` | Int | | | `shopId` | Int | | | `createdTs` | DateTime | | | `createdDate` | Date | | | `operationId` | String | Cursor key. Filtering by it is a pinpoint lookup. | | `movementType` | String | Filterable. | | `movementDescription` | String | | | `balanceAmount` | Money | | | `totalBalance` | Money | Running total. | `MovementBalanceFilterInput`: `shopId`, `movementType`, `operationId`, `createdDateFrom`, `createdDateTo`. Date window default 1 day, maximum 31 days; `operationId` bypasses the window. ## ReportBalance A daily balance snapshot per shop, returned by the non-paginated `reportBalances` query (as `{ items }`). Contains no personally identifiable data. All amounts are `Money`. | Field | Notes | | -------------------------- | --------------------------------------------- | | `merchantId` | | | `shopId` | | | `createdDate` | Snapshot date. | | `openingBalance` | | | `volumePayin` | | | `mdr` | Merchant discount rate (fee on payin volume). | | `volumePayout` | | | `payoutFee` | | | `newClaims` | | | `claimsRefundFee` | | | `claimsWon` | | | `rollingReserve` | Funds withheld as a reserve. | | `rollingReserveReleased` | | | `otherFees` | | | `adjustmentsOther` | | | `adjustmentsFee` | | | `topUps` | | | `taxes` | | | `clearingFees` | | | `netAmountPayable` | | | `rollingReserveAdjustment` | | | `paymentAmount` | | | `closingBalance` | | `ReportBalanceFilterInput`: `shopId`, `createdDateFrom`, `createdDateTo`. Date window default and maximum 90 days. ## Aggregations `aggregations(dataset: DatasetKind!, filter: AggregationFilterInput!)` returns an `AggregationResult`. | Type / Field | Notes | | ------------------------------- | ---------------------------------------- | | `AggregationResult.totalCount` | Int. Overall count. | | `AggregationResult.sumAmount` | Money. Overall sum. | | `AggregationResult.byStatus` | \[AggregationByStatus] buckets. | | `AggregationByStatus.status` | String. The status label for the bucket. | | `AggregationByStatus.count` | Int. | | `AggregationByStatus.sumAmount` | Money. | `DatasetKind` (enum, UPPER\_CASE wire values): `PAYINS`, `PAYOUTS`, `CLAIMS`, `MOVEMENTBALANCES`, `REPORTBALANCES`. Only `PAYINS`, `PAYOUTS`, and `CLAIMS` are aggregatable; `MOVEMENTBALANCES` and `REPORTBALANCES` return `INVALID_FILTER`. `AggregationFilterInput`: `transactionId`, `shopId`, `status`, `personId`, `createdDateFrom`, `createdDateTo`. ## Pagination wrappers Paginated connections (`payins`, `payouts`, `claims`, `movementBalances`) share this shape: * `edges`: list of `{ cursor, node }`. * `pageInfo`: `{ hasNextPage, endCursor }`. * `summary`: `{ rowCount, pageSizeLimit, totalCount }`. `reportBalances` returns `{ items }` only, with no `pageInfo` or `summary`. ## Field naming notes * Field names are camelCase on the wire. * The API mixes British and American spelling in a few field names, for example `normalisedErrorReason` (British) alongside `standardizedError` (American). These are returned exactly as shown; do not normalise them. > **\_review\_needed (from Stage 1):** Transaction and claim `status` values are free-text > labels sourced from the data platform, not a fixed enum in the source. The distinct > status values and their casing must be enumerated from sample data before publication. ## Next steps * [Pagination, filtering, and sorting](pagination-filtering-sorting.md)