Search and filter payments
Beta

Last updated: September 4, 2024

The Payment Search API enables you to search and filter through your payments to retrieve data that matches your query.

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

search fields to specify the fields to use to filter the results
search syntax to specify the logic behind when a value will result in a match

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.
`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.
`last4`	string	The last four digits of the card used for the payment.
`metadata`	–	A set of key-value pairs attached to the payment.
`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: `ACCEL` `ACH` `AMEX` `APPLE_PAY` `ALIPAY_CN` `ALIPAY_HK` `ALMA` `BANCONTACT` `BENEFIT` `CARTES_BANCAIRES` `DANA` `DISCOVER` `DCI` `EPS` `JCB` `FAWRY` `GCASH` `GOOGLE_PAY` `IDEAL` `KAKAOPAY` `KLARNA` `KNET` `MADA` `MASTERCARD` `MULTIBANCO` `NYCE` `OMANNET` `P24` `PAYPAL` `PULSE` `QPAY` `SEPA` `SEQURA` `SOFORT` `STAR` `STCPAY` `TAMARA` `TNG` `TRUEMONEY` `VISA` `WECHATPAY`
`payment_type`	string	The payment type, as one of the following: `Instalment` `MOTO` `Recurring` `Regular` `Unscheduled`
`reference`	string	The reference to identify the payment with.
`scheme`	string	The card scheme, as one of the following values: Visa Mastercard
`status`	token	The most recent status of the payment, as one of the following values: `authenticated` `authentication_failed` `authorized` `captured` `captured_partial` `card_verified` `declined` `deferred_capture` `deferred_partial_refund` `deferred_refund` `disputed` `expired` `flagged` `paid` `pending` `refunded` `rejected` `returned` `refunded_partial` `voided`

Search syntax	Description	Usage
`:`	Equal to.	`field:value`
`:()`	Equal to one or more of the encapsulated values.	`field:(value_1, value_2)`
`:>`	Greater than. Used for numeric or datetime search fields.	`field:>value`
`:>=`	Greater than or equal to. Used for numeric or datetime search fields.	`field:>=value`
`:<`	Less than. Used for numeric or datetime search fields.	`field:<value`
`:<=`	Less than or equal to. Used for numeric or datetime 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`

post

https://api.checkout.com/payments/search

By default, the Search API searches through payments from the previous 30 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'".


1{
2  "query": "id:'pay_mbabizu24mvu3mela5njyhpit4'",
3  "limit": 20,
4  "from": "2023-08-24T14:15:22Z",
5  "to": "2023-08-24T14:15:22Z"
6}


1{
2  "data": [
3    {
4      "id": "pay_mbabizu24mvu3mela5njyhpit4",
5      "requested_on": "2023-08-24T14:15:22Z",
6      "source": {
7        "type": "card",
8        "expiry_month": "04",
9        "expiry_year": "2024",
10        "name": "Jia Tsang",
11        "scheme": "Visa",
12        "local_schemes": "cartes bancaire",
13        "last4": "3131",
14        "fingerprint": "B16D9C2EF0C861A8825C9BD59CCE9171D84EBC45E89CC792B5D1D2D0DDE3DAB7",
15        "bin": "313131",
16        "card_type": "credit",
17        "card_wallet_type": "googlepay",
18        "issuer": "GE CAPITAL FINANCIAL, INC",
19        "issuer_country": "US",
20        "avs_check": "G"
21      },
22      "amount": 10000,
23      "amount_requested": 10000,
24      "currency": "GBP",
25      "payment_type": "regular",
26      "processing_channel_id": "pc_vxt6yftthv4e5flqak6w2i7rim",
27      "reference": "ORD-5023-4E89",
28      "status": "captured",
29      "balances": {
30        "total_authorized": 200,
31        "total_captured": 150,
32        "total_refunded": 50
33      },
34      "3ds": {
35        "eci": "02",
36        "version": "2.1.0"
37      },
38      "risk": {
39        "flagged": false,
40        "score": "22"
41      },
42      "customer": {
43        "email": "[email protected]",
44        "name": "Jia Tsang"
45      },
46      "billing_descriptor": {
47        "name": "Purchase",
48        "city": "London"
49      },
50      "metadata": {}
51    }
52  ]
53}

Search and filter payments
Beta

Search through your payments

Search fields

Search syntax

Request example

Response example