# Search and filter payments

The [Payment Search API](https://api-reference.checkout.com/tag/Payments/#operation/search) enables you to search and filter through your payments to retrieve data that matches your query.

> **Information**
>
> To authenticate requests to the Search API, your API key or access key must have the `payments:search` scope configured.

---

## Search through your payments

To search through your payments, you build out a query using a combination of:

- [Search fields](#Search_fields) to specify the fields to use to filter the results
- [Search syntax](#Search_syntax) to specify the logic behind when a value will result in a match

---

## Search fields

| Search field | Data type | Description |
| --- | --- | --- |
| `amount` | number | The payment amount. |
| `bin` | string | The card issuer's six-digit or eight-digit Bank Identification Number (BIN). |
| `currency` | token | The three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md). |
| `email` | string | The customer's email address. |
| `id` | string | The payment's unique identifier, with the prefix `pay_`. |
| `issuer` | string | The card issuer. |
| `issuing_country` | token | The card issuer's country, as a two-letter ISO 3166 alpha-2 [country code](https://www.checkout.com/docs/developer-resources/codes/country-codes.md). |
| `last4` | string | The last four digits of the card used for the payment. |
| `metadata` | – | A set of key-value pairs attached to the payment.<br><br>You can use wildcards to search or filter metadata values. Use the asterisk character (`*`) as a wildcard when creating your query. <br><br><br>You can use up to two wildcards, separated by at least one regular character. For example:<br><br>- `"metadata['OrderNo']:'1066*'"`<br>- `"metadata['product_type']:'*classic*'"` |
| `name` | string | The customer's name. |
| `payment_arn` | string | The Acquirer Reference Number (ARN), which you can use to query the issuing bank. |
| `payment_method` | string | The payment method used for the payment. You can provide the following values:<br><br>- `ACCEL`<br>- `ACH`<br>- `AMEX`<br>- `APPLE_PAY`<br>- `ALIPAY_CN`<br>- `ALIPAY_HK`<br>- `ALMA`<br>- `BANCONTACT`<br>- `BENEFIT`<br>- `CARTES_BANCAIRES`<br>- `DANA`<br>- `DISCOVER`<br>- `DCI`<br>- `EPS`<br>- `JCB`<br>- `FAWRY`<br>- `GCASH`<br>- `GOOGLE_PAY`<br>- `IDEAL`<br>- `KAKAOPAY`<br>- `KLARNA`<br>- `KNET`<br>- `MADA`<br>- `MASTERCARD`<br>- `MULTIBANCO`<br>- `NYCE`<br>- `OMANNET`<br>- `P24`<br>- `PAYPAL`<br>- `PULSE`<br>- `QPAY`<br>- `SEPA`<br>- `SEQURA`<br>- `SOFORT`<br>- `STAR`<br>- `STCPAY`<br>- `TAMARA`<br>- `TNG`<br>- `TRUEMONEY`<br>- `VISA`<br>- `WECHATPAY` |
| `payment_type` | string | The payment type, as one of the following:<br><br>- `Instalment`<br>- `MOTO`<br>- `Recurring`<br>- `Regular`<br>- `Unscheduled` |
| `processing_channel_id` | string | The ID of the processing channel used to process the payment. |
| `reference` | string | The reference to identify the payment with. |
| `scheme` | string | The card scheme, as one of the following values:<br><br>- Visa<br>- Mastercard |
| `status` | token | The most recent status of the payment, as one of the following values:<br><br>- `Authenticated`<br>- `Authentication Failed `<br>- `Authentication Requested`<br>- `Authorized`<br>- `Canceled`<br>- `Captured`<br>- `Card Verified`<br>- `Declined`<br>- `Deferred Capture`<br>- `Deferred Partial Refund`<br>- `Deferred Refund`<br>- `Disputed`<br>- `Expired`<br>- `Flagged `<br>- `Paid`<br>- `Partially Captured`<br>- `Partially Refunded`<br>- `Pending`<br>- `Refunded`<br>- `Rejected`<br>- `Retry Scheduled`<br>- `Returned`<br>- `Voided` |

---

## Search syntax

| Search syntax | Description | Usage |
| --- | --- | --- |
| `:` | Equal to. | `field:value` |
| `:()` | Equal to one or more of the encapsulated values. | `field:(value_1, value_2)` |
| `:>` | Greater than.<br><br>Used for numeric or `date-time` search fields. | `field:>value` |
| `:>=` | Greater than or equal to.<br><br>Used for numeric or `date-time` search fields. | `field:>=value` |
| `:<` | Less than.<br><br>Used for numeric or `date-time` search fields. | `field:<value` |
| `:<=` | Less than or equal to.<br><br>Used for numeric or `date-time` search fields. | `field:<=value` |
| `\` | Escape character. | `" 4’6\" "` |
| `AND`, `and` | Where results match both clauses. | `field_1:value_1 AND field_2:value_2` |
| `OR`, `or` | Where results match one of the clauses. | `field_1:value_1 OR field_2:value_2` |
| `NOT`, `not` | Where results do not match the clause. | `NOT field:value` |
| `( )` | Groups clauses. | `(field_1:value_1 AND field_2:value_2) OR field_3:value_3` |

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/search`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/search`

By default, the Search API searches through payments from the previous 90 days. Alternatively, you can use the `from` and `to` fields to specify a date range to search through.

To specify the maximum number of results to retrieve from the search, use the `limit` field.

Wrap text values in your search `query` in single quotes. For example, `"status:'refunded'"`.

### Request example

**ID**

```json
{
  "query": "id:'pay_mbabizu24mvu3mela5njyhpit4'",
  "limit": 20,
  "from": "2025-08-24T14:15:22Z",
  "to": "2025-08-24T14:15:22Z"
}
```

**Metadata**

```json
{
  "query": "metadata['OrderNo']:'1066FIDXP'",
  "limit": 20,
  "from": "2025-08-24T14:15:22Z",
  "to": "2025-08-24T14:15:22Z"  
}
```

**Metadata using wildcards**

```json
{
  "query": "metadata['OrderNo']:'1066*'",
  "limit": 20,
  "from": "2025-08-24T14:15:22Z",
  "to": "2025-08-24T14:15:22Z"  
}
```

**By amount**

```json
{
  "query": "amount:>10",
  "limit": 20,
  "from": "2025-08-24T14:15:22Z",
  "to": "2025-08-24T14:15:22Z"
}
```

**Status**

```json
{
  "query": "status:'Captured'",
  "limit": 20,
  "from": "2025-08-24T14:15:22Z",
  "to": "2025-08-24T14:15:22Z"
}
```

**Multiple parameters**

```json
{
  "query": "payment_arn:'24567938478028374655' AND status:'Refunded'",
  "limit": 20,
  "from": "2025-08-24T14:15:22Z",
  "to": "2025-08-24T14:15:22Z"
}
```

If the search returns more results than the value specified in `limit`, the results are spread across multiple pages. Each page contains a maximum number of results equal to the `limit` value.

The response returns a link to the next page in the `_links.next.href` field.

### Response example

```json
{
  "data": [
    {
      "id": "pay_mbabizu24mvu3mela5njyhpit4",
      "requested_on": "2025-08-24T14:15:22Z",
      "source": {
        "type": "card",
        "expiry_month": "04",
        "expiry_year": "2024",
        "name": "Jia Tsang",
        "scheme": "Visa",
        "local_schemes": "cartes bancaire",
        "last4": "3131",
        "fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
        "bin": "313131",
        "card_type": "credit",
        "card_wallet_type": "googlepay",
        "issuer": "GE CAPITAL FINANCIAL, INC",
        "issuer_country": "US",
        "avs_check": "G"
      },
      "amount": 10000,
      "amount_requested": 10000,
      "currency": "GBP",
      "payment_type": "regular",
      "processing_channel_id": "pc_vxt6yftthv4e5flqak6w2i7rim",
      "reference": "ORD-5023-4E89",
      "status": "captured",
      "balances": {
        "total_authorized": 200,
        "total_captured": 150,
        "total_refunded": 50
      },
      "3ds": {
        "eci": "02",
        "version": "2.1.0"
      },
      "risk": {
        "flagged": false,
        "score": "22"
      },
      "customer": {
        "email": "jia.tsang@checkout.com",
        "name": "Jia Tsang"
      },
      "billing_descriptor": {
        "name": "Purchase",
        "city": "London"
      },
      "metadata": {}
    }
  ],
  "_links": {
    "next": {
      "href": "https://{prefix}.api.checkout.com/payments/search/nGd7-altGkOfSl3fJptLxA?token=MTc0MDUwMjE2MjQxOCxlN2NiNTdmYy04MDA5LTQ3YmMtOTYzNi0zNDEyOWRmZTkwZTI"
    }
  }
}
```