Query external transactions and disputes
The ids in these examples are placeholders — get real ones from paymentExternalTransactions and paymentExternalDisputes.
Use the paymentExternalTransactions and paymentExternalDisputes queries to retrieve the payment transactions and disputes recorded in OMS for your merchants, or paymentExternalTransaction and paymentExternalDispute to read one by id.
Get external transactions
Use paymentExternalTransactions query to retrieve external payment transactions. The filter argument accepts a PaymentExternalTransactionComplexFilterInput object (see Filtering). In this example, transactions are filtered by creation date, status and amount.
query externalTransactions {
paymentExternalTransactions(
filter: {
and: [
{ fields: { createdAt: { greaterThanOrEqualsTo: "2026-04-20T22:00:00.000Z" } } }
{ fields: { createdAt: { lessThanOrEqualsTo: "2026-04-22T22:00:00.000Z" } } }
{ fields: { status: { in: [pended, completed] } } }
{ fields: { amount: { lessThanOrEqualsTo: 100 } } }
]
}
) {
nodes {
id
number
amount
currency
status
startedAt
transactedAt
failedAt
merchant {
id
}
fees {
id
amount
}
disputes {
id
amount
status
reason
defenseEndAt
}
refundTransactions {
id
amount
fees {
id
amount
}
}
}
}
}{
"data": {
"paymentExternalTransactions": {
"nodes": [
{
"id": "1005",
"number": "12345678",
"amount": 10.1,
"currency": "EUR",
"status": "completed",
"startedAt": "2026-04-03T10:15:30.000Z",
"transactedAt": "2026-04-22T17:15:30.000Z",
"failedAt": null,
"merchant": {
"id": "1"
},
"fees": [
{
"id": "112",
"amount": 0.66
}
],
"disputes": [
{
"id": "12",
"amount": -10.1,
"status": "closed",
"reason": "Cancelled",
"defenseEndAt": null
}
],
"refundTransactions": [
{
"id": "1006",
"amount": -1.2,
"fees": [
{
"id": "113",
"amount": 0.4
}
]
}
]
},
{
"id": "1006",
"number": "R123456",
"amount": -1.2,
"currency": "EUR",
"status": "pended",
"startedAt": "2026-04-03T10:15:30.000Z",
"transactedAt": null,
"failedAt": null,
"merchant": {
"id": "1"
},
"fees": [
{
"id": "113",
"amount": 0.4
}
],
"disputes": [],
"refundTransactions": []
}
]
}
},
"extensions": {
"queryComplexity": 502,
"bucketBalance": 9498,
"bucketRestoreRate": 100
}
}Find an external transaction by number
Filter on number to look a transaction up by its provider transaction number, or on referenceCode to find the transactions of a given order or repayment request.
query externalTransactionByNumber {
paymentExternalTransactions(
filter: { fields: { number: { equals: "12345678" } } }
) {
totalCount
nodes {
id
number
referenceCode
status
amount
currency
}
}
}{
"data": {
"paymentExternalTransactions": {
"totalCount": 1,
"nodes": [
{
"id": "1005",
"number": "12345678",
"referenceCode": "12345",
"status": "completed",
"amount": 10.1,
"currency": "EUR"
}
]
}
},
"extensions": {
"queryComplexity": 123,
"bucketBalance": 9877,
"bucketRestoreRate": 100
}
}Get external disputes
Use paymentExternalDisputes query to retrieve payment disputes. The filter argument accepts a PaymentExternalDisputeComplexFilterInput object.
query externalDisputes {
paymentExternalDisputes {
nodes {
id
amount
externalTransaction {
id
amount
}
}
}
}{
"data": {
"paymentExternalDisputes": {
"nodes": [
{
"id": "12",
"amount": -10.1,
"externalTransaction": {
"id": "1005",
"amount": 10.1
}
}
]
}
},
"extensions": {
"queryComplexity": 102,
"bucketBalance": 9898,
"bucketRestoreRate": 100
}
}From transactions and disputes to the order
Every transaction carries in referenceCode the number of the order or repayment request (return) it belongs to; once OMS has linked the two records, the transaction also exposes them directly in order or repaymentRequest (both null until then). A refund reaches the order it refunds through the original payment, saleTransaction.order, and a dispute through the disputed transaction, externalTransaction.order. The example reads the three paths at once:
query paymentRecordsToOrder {
payment: paymentExternalTransaction(id: "3868") {
id
referenceCode
order {
id
number
}
repaymentRequest {
id
number
}
}
refund: paymentExternalTransaction(id: "3871") {
id
amount
referenceCode
repaymentRequest {
id
number
}
saleTransaction {
id
order {
id
number
}
}
}
dispute: paymentExternalDispute(id: "66") {
id
externalTransaction {
id
order {
id
number
}
}
}
}{
"data": {
"payment": {
"id": "3868",
"referenceCode": "claude-audit3pay-1787833477",
"order": {
"id": "9318",
"number": "claude-audit3pay-1787833477"
},
"repaymentRequest": null
},
"refund": {
"id": "3871",
"amount": -30.0,
"referenceCode": "claude-audit3pay-1787833477",
"repaymentRequest": null,
"saleTransaction": {
"id": "3868",
"order": {
"id": "9318",
"number": "claude-audit3pay-1787833477"
}
}
},
"dispute": {
"id": "66",
"externalTransaction": {
"id": "3868",
"order": {
"id": "9318",
"number": "claude-audit3pay-1787833477"
}
}
}
},
"extensions": {
"queryComplexity": 28,
"bucketBalance": 9972,
"bucketRestoreRate": 100
}
}The link works in the other direction too: the Order object lists its payment transactions in saleTransactions, and the RepaymentRequest object lists its refunds in refundTransactions.