# List transactions

Building with an AI agent? Start at https://docs.payme.io/agents.md

- Sandbox: `POST https://sandbox.payme.io/api/get-transactions`
- Production: `POST https://live.payme.io/api/get-transactions`

## Credentials

- Header `PayMe-Partner-Key` (optional): Partner key, instead of `payme_client_key` in the body. Partners only.
- Header `PayMe-Merchant-Key` (optional): A seller's own MPL, instead of `seller_payme_id` in the body.
- Request body field `payme_client_key` (optional): Partner key. Partners only. Can also be sent in the `PayMe-Partner-Key` header. Without `seller_payme_id`, the query covers all your sellers.
- Request body field `seller_payme_id` (optional): The seller's MPL. A partner can send one MPL or an array of up to 100 MPLs of its own sellers to narrow the query. A seller sends its own MPL, here or in the `PayMe-Merchant-Key` header, and gets only its own data.

Returns money movements (payments, captures, refunds, voids and chargebacks) for one seller or all your sellers. Use it for amounts in a period: a refund or chargeback is its own row, with its own date and a positive `transaction_price`.

A partner sends `payme_client_key` (or the `PayMe-Partner-Key` header) and, optionally, `seller_payme_id`: one MPL or an array of up to 100 MPLs of its own sellers. Without it, the query covers all your sellers. A seller sends its own MPL as `seller_payme_id` in the body, or in the `PayMe-Merchant-Key` header, and gets only its own data.

#### Defaults
- `transaction_type` is `1` (sale transactions). A sale that is authorized and not yet captured is type `40`, so send `transaction_type: 40` to see it. Types are listed on [Transaction Types](/payments/codes-statuses/transaction-types).
- The default statuses are `validated`, `failed`, `refunded`, `p-refund`, `chargeback`, `partial-chargeback`, `chargeback-refund` and `partial-chargeback-refund`. `pending`, `voided` and `partial-void` rows are left out. Send `transaction_status: "validated"` when you add up volume. Statuses are listed on [Transaction Statuses](/payments/codes-statuses/transaction-statuses).
- A voided authorization returns no rows from a default query: with `transaction_type: 40` you get its authorization row, whose `sale_status` is `voided`, and adding `transaction_status: ["validated", "voided"]` also returns the `Void` row.

#### Telling rows apart
`transaction_action` says what each row is: `Debit`, `Authorize`, `Capture`, `Refund`, `Partial Refund`, `Void`, `Partial Void`, `Chargeback`, `Partial Chargeback`, `Chargeback Refund`, `Partial Chargeback Refund`, `Tokenize` or `Detokenize`. A refund is its own row, with a positive `transaction_price`, the action `Refund` or `Partial Refund`, and the status `refunded` or `p-refund`. A void adds no refund row. See [Reading the rows](/agents/steps/capture-refund-void#reading-the-rows). 

For a sale opened with `sale_payment_method` `multi`, `transaction_payment_method` shows the method the buyer actually used; the sale keeps `multi`. `transaction_error_code` is `null` on a successful transaction.

This call is rate limited per partner, or per seller when there's no partner key. On HTTP 429 (error `998`), wait for the `Retry-After` time and retry.

Timestamps in the response, and the date filters you send, are Asia/Jerusalem local time, not UTC. A 2–3 hour offset against a UTC clock is the timezone, not a bug. 

Results come in pages of up to 500 items (default 500). A call without `page` and `page_size` returns only the first 500. Paging, sorting and filter rules are on [Query APIs](/payments/query-apis).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Partner-Key` | header | string | no | Partner key, instead of `payme_client_key` in the body. Partners only. |
| `PayMe-Merchant-Key` | header | string | no | A seller's own MPL, instead of `seller_payme_id` in the body. |

## Request body

Content type: `application/json`

Every field is optional. Send at least your credentials.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `payme_client_key` | string | no | Partner key. Partners only. Can also be sent in the `PayMe-Partner-Key` header. Without `seller_payme_id`, the query covers all your sellers. |
| `seller_payme_id` | string | no | The seller's MPL. A partner can send one MPL or an array of up to 100 MPLs of its own sellers to narrow the query. A seller sends its own MPL, here or in the `PayMe-Merchant-Key` header, and gets only its own data. |
| `seller_id` | string | no | Your own ID for the seller, as sent to create-seller. Partners only. |
| `sale_payme_id` | string | no | PayMe's sale ID. |
| `sale_payme_code` | integer | no | PayMe's numeric sale code. |
| `transaction_id` | string | no | Your own order ID, as sent to generate-sale. It is not unique. |
| `payme_transaction_id` | string | no | PayMe's transaction ID. |
| `transaction_type` | integer | no | Transaction type, or an array of them. See [Transaction Types](/payments/codes-statuses/transaction-types). Default `1`. |
| `transaction_status` | string | no | Transaction status name, or an array of up to 100. See [Transaction Statuses](/payments/codes-statuses/transaction-statuses). The default set is in the description above. |
| `sale_status` | string | no | Status of the transaction's sale, for example `completed`, or an array of up to 100. See [Sale Statuses](/payments/codes-statuses/sale-statuses). |
| `sale_currency` | string | no | Currency, 3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code, for example `ILS`, or an array of up to 100. |
| `sale_payment_method` | string | no | Payment method of the sale, for example `credit-card`, or an array of up to 100. See [Wallets & APMs](/payments/wallets-apms). |
| `transaction_payment_method` | string | no | Payment method actually used on the transaction, for example `bit` on a `multi` sale. |
| `transaction_created` | string | no | Exact creation date and time, `yyyy-mm-dd hh:mm:ss`. |
| `transaction_created_min` | string | no | Created at or after this time, `yyyy-mm-dd hh:mm:ss`. |
| `transaction_created_max` | string | no | Created at or before this time, `yyyy-mm-dd hh:mm:ss`. |
| `transaction_price` | integer | no | Exact transaction amount, in minor units (`5075` = 50.75). |
| `sale_price` | integer | no | Exact sale amount, in minor units. |
| `sale_auth_number` | string | no | Authorization number from the card company. |
| `buyer_card_mask` | string | no | Masked card number, first 6 and last 4 digits. |
| `buyer_card_last_four_digits` | string | no | Last four digits of the card. |
| `buyer_card_is_foreign` | boolean | no | `true` returns only foreign cards, `false` only local cards. |
| `buyer_name` | string | no | Buyer's full name. |
| `buyer_email` | string | no | Buyer's email. |
| `buyer_phone` | string | no | Buyer's phone number. |
| `buyer_social_id` | string | no | Buyer's national ID number. |
| `sale_is_3ds` | boolean | no | `true` returns only transactions paid with 3D Secure, `false` only those without it. |
| `transaction_is_matched` | boolean | no | `true` returns only transactions that PayMe has matched (correlated) in its reconciliation, `false` only the others. |
| `page` | integer | no | Page number, `1`–`1000`. Default `1`. Out of range returns error `52`. |
| `page_size` | integer | no | Items per page, `1`–`500`. Default `500`. Out of range returns error `27`. |
| `items_order_by_column` | string | no | Field to sort by, for example `transaction_created_at`. Without it, the order isn't guaranteed. A field that doesn't exist fails the call. |
| `items_order_by_direction` | string | no | `asc` (default) or `desc`, in upper or lower case. Used only with `items_order_by_column`. Any other value returns error `28`. |

### Request example

```json
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "transaction_status": "validated",
  "transaction_created_min": "2026-10-01 00:00:00",
  "transaction_created_max": "2026-10-31 23:59:59",
  "sale_currency": "ILS",
  "items_order_by_column": "transaction_created_at",
  "page": 1,
  "page_size": 500
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/get-transactions' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Partner-Key: <PayMe-Partner-Key>' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  --data-raw '{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "transaction_status": "validated",
  "transaction_created_min": "2026-10-01 00:00:00",
  "transaction_created_max": "2026-10-31 23:59:59",
  "sale_currency": "ILS",
  "items_order_by_column": "transaction_created_at",
  "page": 1,
  "page_size": 500
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/get-transactions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Partner-Key": "<PayMe-Partner-Key>",
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
  body: JSON.stringify({
    "payme_client_key": "XXXXXXXX",
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "transaction_status": "validated",
    "transaction_created_min": "2026-10-01 00:00:00",
    "transaction_created_max": "2026-10-31 23:59:59",
    "sale_currency": "ILS",
    "items_order_by_column": "transaction_created_at",
    "page": 1,
    "page_size": 500
  }),
});

console.log(await response.text());
```

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/get-transactions",
    headers={
        "PayMe-Partner-Key": "<PayMe-Partner-Key>",
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    json={
        "payme_client_key": "XXXXXXXX",
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "transaction_status": "validated",
        "transaction_created_min": "2026-10-01 00:00:00",
        "transaction_created_max": "2026-10-31 23:59:59",
        "sale_currency": "ILS",
        "items_order_by_column": "transaction_created_at",
        "page": 1,
        "page_size": 500,
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "payme_client_key": "XXXXXXXX",
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "transaction_status": "validated",
  "transaction_created_min": "2026-10-01 00:00:00",
  "transaction_created_max": "2026-10-31 23:59:59",
  "sale_currency": "ILS",
  "items_order_by_column": "transaction_created_at",
  "page": 1,
  "page_size": 500
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/get-transactions');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'PayMe-Partner-Key: <PayMe-Partner-Key>',
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
```

## Responses

### 200 — OK (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `items_count` | integer | Number of items on this page. There is no total count. |
| `items` | array | The transactions. |
| `items[].seller_payme_id` | string | The seller's MPL. |
| `items[].seller_id` | string | Your own ID for the seller, or `null`. |
| `items[].sale_payme_id` | string | PayMe's sale ID. |
| `items[].sale_payme_code` | integer | PayMe's numeric sale code. |
| `items[].transaction_id` | string | Your own order ID, as you sent it to generate-sale. Not a PayMe ID, and not unique. |
| `items[].payme_transaction_id` | string | PayMe's transaction ID. Use it in `transaction_ids` on withdraw-balance. |
| `items[].transaction_created_at` | string | Creation time, `yyyy-mm-dd hh:mm:ss`, Asia/Jerusalem. |
| `items[].sale_type` | integer | Numeric sale type, see [Sale Types](/payments/codes-statuses/sale-types). |
| `items[].sale_status` | string | Status of the sale, see [Sale Statuses](/payments/codes-statuses/sale-statuses). |
| `items[].transaction_status` | string | Status of this row, see [Transaction Statuses](/payments/codes-statuses/transaction-statuses). |
| `items[].transaction_type` | integer | Transaction type, see [Transaction Types](/payments/codes-statuses/transaction-types). |
| `items[].transaction_action` | string | What this row is: `Authorize`, `Tokenize`, `Detokenize`, `Debit`, `Capture`, `Refund`, `Partial Refund`, `Void`, `Partial Void`, `Chargeback`, `Partial Chargeback`, `Chargeback Refund` or `Partial Chargeback Refund`. |
| `items[].sale_currency` | string | Currency, 3-letter ISO 4217 code. |
| `items[].sale_description` | string | What the buyer paid for. |
| `items[].sale_installments` | integer | Number of installments. |
| `items[].sale_payment_method` | string | Payment method of the sale, see [Wallets & APMs](/payments/wallets-apms). |
| `items[].transaction_payment_method` | string | Payment method used on this transaction. For a `multi` sale, the method the buyer chose. |
| `items[].transaction_price` | integer | Amount of this row, in minor units. Positive for refunds and chargebacks too. |
| `items[].transaction_price_after_fees` | string | Net amount after PayMe fees, in minor units, as a numeric string. Final once settled. |
| `items[].sale_vat` | string | VAT rate at the time of the sale, as a fraction (`"0.18"` = 18%). |
| `items[].sale_auth_number` | string | Authorization number from the card company. |
| `items[].sale_is_3ds` | boolean | `true` if the payment used 3D Secure. |
| `items[].transaction_release_date` | string | When the funds are expected in the seller's balance, `yyyy-mm-dd hh:mm:ss`, or `null`. |
| `items[].transaction_voucher` | string | Voucher number of the transaction. |
| `items[].transaction_reference_number` | string | Reference number from the gateway, or `null`. |
| `items[].transaction_first_payment` | string | First installment, in minor units, or the full amount when there are no installments. |
| `items[].transaction_periodical_payment` | string | Each later installment, in minor units. `0` when there are no installments. |
| `items[].transaction_arn` | string | Acquirer reference number (ARN), or `null`. |
| `items[].transaction_acquirer` | string | Acquirer that processed the transaction, or `null`. |
| `items[].transaction_discounter` | string | Company that settles the transaction, or `null`. |
| `items[].transaction_credit_type` | string | Credit type of the card transaction, as reported by the acquirer. |
| `items[].transaction_error_code` | string | Error code on failure. `null` on success. |
| `items[].transaction_error_text` | string | Gateway message for the transaction. |
| `items[].transaction_comment` | string | Chargeback reason. `null` except on chargeback rows. |
| `items[].transaction_is_matched` | boolean | `true` when PayMe has matched (correlated) the transaction in its reconciliation. |
| `items[].transaction_match_statuses` | array | The reconciliation statuses set on the transaction. Empty when it isn't matched. |
| `items[].transaction_is_canceled` | boolean | `true` if the transaction was canceled before it was transmitted. |
| `items[].transaction_is_eligible_for_manual_auth` | boolean | `true` when the transaction was processed by an Israeli acquirer. |
| `items[].sale_fees` | object | Fees on this row. Rates are percent strings. `*_total` fields are in minor units, without VAT, computed on `transaction_price`. |
| `items[].sale_fees.sale_processing_fee` | string | Processing rate, percent of the amount (`"2.50"` = 2.5%). |
| `items[].sale_fees.sale_processing_fee_total` | integer | Processing fee, in minor units. |
| `items[].sale_fees.sale_processing_charge` | string | Fixed processing charge per sale, in major units (`"1.20"` = 1.20). |
| `items[].sale_fees.sale_discount_fee` | string | Discount rate (early settlement of installments) per installment, percent. |
| `items[].sale_fees.sale_discount_fee_total` | integer | Discount fee, in minor units. |
| `items[].sale_fees.sale_rapid_settlement_fee` | string | Rapid settlement rate, percent. |
| `items[].sale_fees.sale_rapid_settlement_fee_total` | integer | Rapid settlement fee, in minor units. |
| `items[].sale_fees.sale_annual_interest_rate` | string | Annual interest rate (percent) behind the discount and rapid settlement fees, or `null`. |
| `items[].sale_fees.sale_market_fee` | string | Platform (market) fee rate, percent of the amount. |
| `items[].sale_fees.sale_market_fee_fixed` | number | Fixed platform fee per sale, in major units. |
| `items[].sale_fees.sale_market_fee_total` | integer | Platform fee, in minor units: the percent part plus the fixed part. |
| `items[].sale_business_data` | object | Only on `transaction_type` `50` rows: business details of the paying seller. On these rows `sale_fees` is `{}`. |
| `items[].sale_buyer_details` | object | The buyer and the card used. |
| `items[].sale_buyer_details.buyer_card_mask` | string | Masked card number: first 6 and last 4 digits. |
| `items[].sale_buyer_details.buyer_card_expiry` | string | Card expiry, `MMYY`. |
| `items[].sale_buyer_details.buyer_card_brand` | string | Card brand, for example `Visa`. |
| `items[].sale_buyer_details.buyer_card_is_foreign` | boolean | `true` for a card issued outside the seller's country, `false` for a local card. |
| `items[].sale_buyer_details.buyer_name` | string | Buyer's full name. |
| `items[].sale_buyer_details.buyer_email` | string | Buyer's email. |
| `items[].sale_buyer_details.buyer_phone` | string | Buyer's phone number. |
| `items[].sale_buyer_details.buyer_social_id` | string | Buyer's national ID number. |
| `items[].transaction_invoice_url` | string | Link to the transaction's invoice, or `null`. |
| `items[].transaction_invoice_doc_number` | string | Invoice document number, or `null`. |

```json
{
  "status_code": 0,
  "items_count": 1,
  "items": [
    {
      "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
      "seller_id": null,
      "sale_payme_id": "SALE1499-869577YG-Y2QXJ6PK-INXR2FAE",
      "sale_payme_code": 115498,
      "transaction_id": "order-12345",
      "payme_transaction_id": "TRAN1499-869602B9-7QIUNKHI-F0SL1AOV",
      "transaction_created_at": "2026-10-12 17:26:42",
      "sale_type": 1,
      "sale_status": "completed",
      "transaction_status": "validated",
      "transaction_type": 1,
      "transaction_action": "Debit",
      "sale_currency": "ILS",
      "sale_description": "Handmade ceramic bowl",
      "sale_installments": 1,
      "sale_payment_method": "credit-card",
      "transaction_payment_method": "credit-card",
      "transaction_price": 9000,
      "transaction_price_after_fees": "8617",
      "sale_vat": "0.18",
      "sale_auth_number": "2154577",
      "sale_is_3ds": false,
      "transaction_release_date": "2026-10-19 06:00:00",
      "transaction_voucher": "10784",
      "transaction_reference_number": null,
      "transaction_first_payment": "9000",
      "transaction_periodical_payment": "0",
      "transaction_arn": null,
      "transaction_acquirer": null,
      "transaction_discounter": null,
      "transaction_credit_type": "1",
      "transaction_error_code": null,
      "transaction_error_text": "Permitted transaction",
      "transaction_comment": null,
      "transaction_is_matched": false,
      "transaction_match_statuses": [],
      "transaction_is_canceled": false,
      "transaction_is_eligible_for_manual_auth": false,
      "sale_fees": {
        "sale_processing_fee": "2.50",
        "sale_processing_fee_total": 225,
        "sale_processing_charge": "1.20",
        "sale_discount_fee": "0.00",
        "sale_discount_fee_total": 0,
        "sale_rapid_settlement_fee": "0.00",
        "sale_rapid_settlement_fee_total": 0,
        "sale_annual_interest_rate": null,
        "sale_market_fee": "0.00",
        "sale_market_fee_fixed": 0,
        "sale_market_fee_total": 0
      },
      "sale_buyer_details": {
        "buyer_card_mask": "458045******4580",
        "buyer_card_expiry": "1228",
        "buyer_card_brand": "Visa",
        "buyer_card_is_foreign": false,
        "buyer_name": "Israel Israeli",
        "buyer_email": "buyer@example.com",
        "buyer_phone": "0500000001",
        "buyer_social_id": "000000018"
      },
      "transaction_invoice_url": null,
      "transaction_invoice_doc_number": null
    }
  ]
}
```

### 500 — Error. Most errors return HTTP 500. Paging errors (`52`, `27`) return HTTP 400, and the rate limit (`998`) returns HTTP 429. The body is the same. See [Errors](/payments/getting-started/errors). (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_code` | integer | PayMe error code. |
| `status_error_details` | string | Error message. |
| `status_additional_info` | string | The field the error refers to, when there is one. |

```json
{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "payme_client_key",
  "status_error_code": 1
}
```