How to Query Payments by Reference or Metadata

While the direct getPayment endpoint only accepts payment IDs, you can query payments by their reference or metadata using the list payments endpoint with a query filter.

Querying by Reference

To find a payment by its reference, use the /payments endpoint with a match filter:

{
    "$match": {
        "reference": "your_reference"
    }
}

Best Practices

Using the filtered query approach is more efficient than retrieving all payments and filtering client-side, as it reduces data transfer and server load. This helps prevent timeouts (504 errors) when querying large payment datasets.