---
updatedAt: 2026-07-30T10:10:46.000Z
agentTools:
  projectIndex: https://developer.peachpayments.com/llms.txt
---

# Query a transaction by merchantTransactionId

Query the status of a transaction using the merchantTransactionId. Could return multiple results.

You can send two transaction status requests per minute per transaction.

For more information, see the [documentation](https://developer.peachpayments.com/docs/payments-api-flows#transaction-status-flow), and for sample calls, see our [public Postman collection](https://www.postman.com/peachpayments/peach-payments-public-workspace/request/22k36iv/payments-public?action=share&creator=20323380&ctx=documentation&active-environment=13324425-9345d747-fcdd-4a5c-83e4-6f637771b28b).


# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "version": "2.0.0",
    "title": "Payments API",
    "description": "The Payments API enables you to do a custom integration with Peach Payments and thereby support multiple payment methods.",
    "termsOfService": "https://swagger.io/terms/",
    "contact": {
      "name": "Peach Payments Support",
      "email": "support@peachpayments.com",
      "url": "https://support.peachpayments.com/support/home"
    },
    "license": {
      "name": "MIT",
      "url": "https://mit-license.org"
    }
  },
  "servers": [
    {
      "url": "https://testapi-v2.peachpayments.com",
      "description": "Sandbox testing environment."
    },
    {
      "url": "https://api-v2.peachpayments.com",
      "description": "Live production environment."
    }
  ],
  "paths": {
    "/payments": {
      "get": {
        "tags": [
          "Status"
        ],
        "summary": "Query a transaction by merchantTransactionId",
        "description": "Query the status of a transaction using the merchantTransactionId. Could return multiple results.\n\nYou can send two transaction status requests per minute per transaction.\n\nFor more information, see the [documentation](https://developer.peachpayments.com/docs/payments-api-flows#transaction-status-flow), and for sample calls, see our [public Postman collection](https://www.postman.com/peachpayments/peach-payments-public-workspace/request/22k36iv/payments-public?action=share&creator=20323380&ctx=documentation&active-environment=13324425-9345d747-fcdd-4a5c-83e4-6f637771b28b).\n",
        "operationId": "transaction_status",
        "parameters": [
          {
            "in": "query",
            "name": "authentication.userId",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/UserId"
            }
          },
          {
            "in": "query",
            "name": "authentication.password",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/Password"
            }
          },
          {
            "in": "query",
            "name": "authentication.entityId",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/EntityId"
            }
          },
          {
            "in": "query",
            "name": "merchantTransactionId",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/MerchantTransactionId"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MerchantTransactionIdStatusResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "500": {
            "description": "Internal server error.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UserId": {
        "description": "Authentication userId.",
        "type": "string",
        "pattern": "^[0-9a-f]{32}$",
        "minLength": 32,
        "maxLength": 32,
        "example": "5fb5e392d6fa11ef9b3002f694e28f55"
      },
      "Password": {
        "description": "Authentication password.",
        "type": "string",
        "example": "OMydSc7ewVmEKPZCAj2WxHoik"
      },
      "EntityId": {
        "description": "Authentication entityId",
        "type": "string",
        "pattern": "^[0-9a-f]{32}$",
        "minLength": 32,
        "maxLength": 32,
        "example": "8ac7a4c894809722019482d1df62029d"
      },
      "MerchantTransactionId": {
        "description": "Merchant-provided reference number, often used for reconciliation.",
        "type": "string",
        "pattern": "^[a-zA-Z0-9]{8,16}$",
        "minLength": 8,
        "maxLength": 16,
        "example": "test12345"
      },
      "Code": {
        "description": "The unique code that indicates the result status of the request.",
        "type": "string",
        "pattern": "^([0-9]{3}.[0-9]{3}.[0-9]{3})$",
        "minLength": 11,
        "maxLength": 11,
        "example": "800.100.152"
      },
      "Result": {
        "description": "The result object.",
        "type": "object",
        "required": [
          "code",
          "description"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/Code"
          },
          "description": {
            "type": "string",
            "example": "Request successfully processed."
          }
        }
      },
      "Timestamp": {
        "description": "The timestamp of the transaction.",
        "type": "string",
        "format": "date-time",
        "example": "2021-04-23T07:41:25.519947Z"
      },
      "UniqueId": {
        "description": "The unique transaction ID provided by Peach Payments.",
        "type": "string",
        "pattern": "^[0-9a-f]{32}$",
        "minLength": 32,
        "maxLength": 32,
        "example": "41a57893d4a44191be8cd410398464e6"
      },
      "PaymentType": {
        "description": "Payment type of the transaction. See the [payment methods documentation](https://developer.peachpayments.com/docs/pp-payment-methods#south-africa) for details on which payment methods support the RF payment type.",
        "type": "string",
        "enum": [
          "DB",
          "RF"
        ],
        "example": "DB"
      },
      "PaymentBrand": {
        "description": "The payment brand specifies the method of payment for the request.",
        "type": "string",
        "enum": [
          "PAYFLEX",
          "ZEROPAY",
          "1FORYOU",
          "MASTERPASS",
          "MPESA",
          "BLINKBYEMTEL",
          "MOBICRED",
          "CAPITECPAY",
          "PEACHEFT",
          "MCBJUICE",
          "RCS",
          "FLOAT",
          "HAPPYPAY",
          "MAUCAS",
          "MONEYBADGER",
          "PAYSHAP"
        ],
        "example": "PEACHEFT"
      },
      "Amount": {
        "description": "The payment request amount.",
        "type": "string",
        "pattern": "(?!0+$)(?!0+\\.00)^\\d{1,8}(\\.\\d{2})?$",
        "minLength": 1,
        "maxLength": 11,
        "example": "22.50"
      },
      "Currency": {
        "description": "The currency code of the payment request amount as defined by ISO-4217.",
        "type": "string",
        "format": "iso-4217",
        "pattern": "^[A-Z]{3}$",
        "minLength": 3,
        "maxLength": 3,
        "example": "ZAR"
      },
      "ResultDetails": {
        "description": "Additional details that can provide information about the status or result of the transaction.",
        "type": "object",
        "properties": {
          "ExtendedDescription": {
            "type": "string",
            "example": "Purchase Approved OK"
          },
          "AcquirerResponse": {
            "type": "string",
            "example": "Approved"
          },
          "UserDisplayMessage": {
            "type": "string",
            "example": "Message 16 - Your session was created."
          }
        }
      },
      "ConnectorTxID1": {
        "description": "The unique transaction identifier provided by the payment service provider.",
        "type": "string",
        "pattern": "^[\\S]{1,64}$",
        "minLength": 1,
        "maxLength": 64,
        "example": "8ac7a49f7921f2fd0179230196ec4bbe"
      },
      "CustomParameters": {
        "description": "A JSON object depicting custom information sent by the merchant. Echoed back in the response.",
        "type": "object"
      },
      "ResponseCard": {
        "description": "The card data structure holds information regarding a credit or debit card account.",
        "type": "object",
        "properties": {
          "bin": {
            "description": "The first six digits of the card number.",
            "type": "string",
            "pattern": "^[\\d]{6}$",
            "minLength": 6,
            "maxLength": 6,
            "example": "455112"
          },
          "last4Digits": {
            "description": "The last four digits of the card number.",
            "type": "string",
            "pattern": "^[\\d]{4}$",
            "minLength": 4,
            "maxLength": 4,
            "example": "2315"
          },
          "holder": {
            "description": "The card account holder.",
            "type": "string",
            "pattern": "^[\\w'\\-,.][^0-9_!¡?÷?¿/\\\\+=@#$%ˆ&*(){}|~<>;:[\\]]{2,127}$",
            "minLength": 3,
            "maxLength": 128,
            "example": "Jane Doe"
          },
          "expiryMonth": {
            "description": "The expiry month of the card.",
            "type": "string",
            "pattern": "^(0[1-9]|1[0-2])$",
            "minLength": 2,
            "maxLength": 2,
            "example": "01"
          },
          "expiryYear": {
            "description": "The expiry year of the card.",
            "type": "string",
            "pattern": "^(20)([0-9]{2})$",
            "minLength": 4,
            "maxLength": 4,
            "example": "2030"
          }
        }
      },
      "MerchantInvoiceId": {
        "description": "The merchant's invoice ID.",
        "type": "string",
        "pattern": "^[a-zA-Z0-9]{8,255}$",
        "minLength": 8,
        "maxLength": 255,
        "example": "20170630407200"
      },
      "Recon": {
        "description": "Transaction reconciliation data.",
        "type": "object",
        "properties": {
          "ciMerchantNumber": {
            "description": "The payment service provider merchant number.",
            "type": "string",
            "example": "123456789012345"
          },
          "rrn": {
            "description": "The reconciliation reference number from the payment service provider.",
            "type": "string",
            "example": "123456789012"
          },
          "authCode": {
            "description": "The authorisation code from the payment service provider.",
            "type": "string",
            "example": "123456"
          },
          "resultCode": {
            "description": "The result code from the payment service provider.",
            "type": "string"
          },
          "stan": {
            "description": "The STAN reference number from the payment service provider.",
            "type": "string",
            "example": "123456"
          }
        }
      },
      "MerchantTransactionIdStatusResponse": {
        "description": "The response for the status request using merchantTransactionId as the query field.",
        "type": "object",
        "required": [
          "result",
          "timestamp",
          "payments"
        ],
        "properties": {
          "result": {
            "$ref": "#/components/schemas/Result"
          },
          "timestamp": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "payments": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id",
                "paymentType",
                "paymentBrand",
                "amount",
                "currency",
                "merchantTransactionId",
                "result",
                "resultDetails",
                "connectorTxID1",
                "timestamp",
                "customParameters"
              ],
              "properties": {
                "id": {
                  "$ref": "#/components/schemas/UniqueId"
                },
                "paymentType": {
                  "$ref": "#/components/schemas/PaymentType"
                },
                "paymentBrand": {
                  "$ref": "#/components/schemas/PaymentBrand"
                },
                "amount": {
                  "$ref": "#/components/schemas/Amount"
                },
                "currency": {
                  "$ref": "#/components/schemas/Currency"
                },
                "merchantTransactionId": {
                  "$ref": "#/components/schemas/MerchantTransactionId"
                },
                "result": {
                  "$ref": "#/components/schemas/Result"
                },
                "resultDetails": {
                  "$ref": "#/components/schemas/ResultDetails"
                },
                "connectorTxID1": {
                  "$ref": "#/components/schemas/ConnectorTxID1"
                },
                "timestamp": {
                  "$ref": "#/components/schemas/Timestamp"
                },
                "customParameters": {
                  "$ref": "#/components/schemas/CustomParameters"
                },
                "card": {
                  "$ref": "#/components/schemas/ResponseCard"
                },
                "merchantInvoiceId": {
                  "$ref": "#/components/schemas/MerchantInvoiceId"
                },
                "recon": {
                  "$ref": "#/components/schemas/Recon"
                }
              }
            }
          }
        }
      },
      "ParameterErrors": {
        "description": "Error details of the request parameters which failed validation.",
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "value",
            "name",
            "message"
          ],
          "properties": {
            "value": {
              "description": "The value of the parameter which failed validation. Can be any value - string, number, boolean, array, or object.",
              "nullable": true
            },
            "name": {
              "type": "string",
              "description": "The name of the parameter."
            },
            "message": {
              "type": "string",
              "description": "A message describing the error."
            }
          }
        },
        "example": [
          {
            "value": "null",
            "name": "authenticationValue",
            "message": "Payments API requires authenticationValue."
          }
        ]
      },
      "Error400Result": {
        "description": "Error result object describing the error code and parameter errors.",
        "type": "object",
        "required": [
          "code",
          "parameterErrors",
          "description"
        ],
        "properties": {
          "code": {
            "$ref": "#/components/schemas/Code"
          },
          "parameterErrors": {
            "$ref": "#/components/schemas/ParameterErrors"
          },
          "description": {
            "type": "string",
            "example": "Errors in the processed request."
          }
        }
      },
      "Error400Response": {
        "description": "Error object describing the 400 status code error.",
        "type": "object",
        "required": [
          "result",
          "timestamp"
        ],
        "properties": {
          "result": {
            "$ref": "#/components/schemas/Error400Result"
          },
          "resultDetails": {
            "$ref": "#/components/schemas/ResultDetails"
          },
          "timestamp": {
            "$ref": "#/components/schemas/Timestamp"
          }
        }
      },
      "ErrorResponse": {
        "description": "Error object describing the error.",
        "type": "object",
        "required": [
          "result",
          "timestamp"
        ],
        "properties": {
          "result": {
            "$ref": "#/components/schemas/Result"
          },
          "resultDetails": {
            "$ref": "#/components/schemas/ResultDetails"
          },
          "timestamp": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "id": {
            "$ref": "#/components/schemas/UniqueId"
          },
          "paymentType": {
            "$ref": "#/components/schemas/PaymentType"
          },
          "paymentBrand": {
            "$ref": "#/components/schemas/PaymentBrand"
          },
          "customParameters": {
            "$ref": "#/components/schemas/CustomParameters"
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "$ref": "#/components/schemas/Currency"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error400Response"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Unauthorised.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorResponse"
            }
          }
        }
      }
    }
  }
}
```