# List payment contracts

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

- Sandbox: `GET https://sandbox.payme.io/api/payment-contracts`
- Production: `GET https://live.payme.io/api/payment-contracts`

## Credentials

- Header `PayMe-Merchant-Key` (API key)

Lists the payment contracts this seller initiated or, with `recipient=true`, the contracts it is the recipient of. Results are paginated (`page`, `per_page`) and can be filtered and sorted. Authenticate with the seller's MPL in the `PayMe-Merchant-Key` header.

To read one contract, call `GET /payment-contracts/{guid}` with the same header. It returns the same contract fields at the top level and again under `data`, plus `status_code` and `session`. It returns error `380` if no contract with this `guid` involves your seller account.

For the meaning of each `status`, see [Contract lifecycle](/b2b-payments/contracts#contract-lifecycle).

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`400` | `27` | Limit parameter should be between 1 and 500 | `per_page` is out of range.
`400` | `52` | Page parameter should be between 1 and 1000 | `page` is out of range.
`500` | `28` | Invalid order by option | `items_order_by_direction` isn't `asc` or `desc`.
`500` | `1` | Required parameter is missing | The `PayMe-Merchant-Key` header is missing. `status_additional_info` is `payme_client_key`.
`500` | `251` | Seller was not found | The seller key is unknown.
`500` | `163` | Account settings problem - please contact Customer Support | The seller is not active.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | The seller's `seller_payme_id` (MPL). |
| `recipient` | query | boolean | no | `true` – list the contracts where this seller is the recipient. Default `false`: the contracts this seller initiated. |
| `status` | query | integer | no | Only contracts in this status: `1` initial, waiting for the recipient; `2` recipient confirmed (moves to `3` at once); `3` approved, waiting for the due date; `4` completed; `5` failed or cancelled (see `error_code`). |
| `payment_type` | query | integer | no | `1` – only contracts that send a payment; `2` – only payment requests. |
| `payment_method` | query | string | no | Only contracts paid with this method: `funds-transfer`, `credit-card` or `il-direct-debit`. |
| `type` | query | integer | no | `1` – only one-time contracts; `2` – only recurring contracts. |
| `currency` | query | string | no | Only contracts in this currency (ISO 4217 code, e.g. `ILS`). |
| `amount` | query | integer | no | Only contracts of exactly this amount, in minor units. |
| `remote_id` | query | string | no | Only contracts with this `remote_id` (exact match). |
| `id` | query | string | no | Only the contract with this `guid`. |
| `due_date_min` | query | string | no | Earliest due date, inclusive. Expected format: `YYYY-MM-DD HH:MM:SS`. |
| `due_date_max` | query | string | no | Latest due date, inclusive. Expected format: `YYYY-MM-DD HH:MM:SS`. |
| `per_page` | query | number | no | Items per page, 1-500. Default: 500. A value outside this range returns error `27`. |
| `page` | query | number | no | Page number, 1-1000. Default: 1. A value outside this range returns error `52`. |
| `items_order_by_column` | query | string | no | Contract column to sort by: `created_at`, `due_date`, `amount` or `status`. An unknown column fails with HTTP `500`. Without it, no sort order is applied. |
| `items_order_by_direction` | query | string | no | Sort direction: `asc` or `desc`. Default: `asc`. Used only with `items_order_by_column`. Any other value returns error `28`. |

## Code samples

### curl

```bash
curl -X GET 'https://sandbox.payme.io/api/payment-contracts' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/payment-contracts", {
  method: "GET",
  headers: {
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
});

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

### Python

```python
import requests

response = requests.get(
    "https://sandbox.payme.io/api/payment-contracts",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/payment-contracts');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
    ],
]);

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

echo $response;
```

## Responses

### 200 — One page of contracts. (success)

| Field | Type | Description |
| --- | --- | --- |
| `items` | array | The contracts on this page. |
| `items[].id` | integer | PayMe's numeric ID of the contract. |
| `items[].guid` | string | The contract ID (`CONT…`). Use it in the contract URLs, e.g. `/payment-contracts/{guid}/invoices`. |
| `items[].description` | string | What the payment is for, as sent. |
| `items[].seller_payme_id` | string | The initiator's `seller_payme_id` (MPL). |
| `items[].remote_id` | string | Your reference, as sent. `null` if you didn't send one. |
| `items[].created_date` | string | When the contract was created, `YYYY-MM-DD HH:MM:SS`. |
| `items[].confirmed_by_recipient_date` | string | When the recipient approved, `YYYY-MM-DD HH:MM:SS`. `null` until then. |
| `items[].confirmed_by_initiator_date` | string | When the initiator side was confirmed, `YYYY-MM-DD HH:MM:SS`. `null` until then. |
| `items[].resolution_date` | string | Reserved. Currently always `null`. |
| `items[].status` | integer | Contract status: `1` initial, waiting for the recipient; `2` recipient confirmed (moves to `3` at once); `3` approved, waiting for the due date; `4` completed; `5` failed or cancelled (see `error_code`). |
| `items[].amount` | integer | Amount in minor units (`1000` = 10.00). |
| `items[].currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `items[].payme_signature` | string | Lowercase hex MD5 of the partner's client key, the partner's client password and the contract `guid`, joined with no separator. See [Callbacks](/b2b-payments/contracts#callbacks). |
| `items[].fast_reconciliation` | boolean | PayMe-internal processing flag. `false` for contracts created as described in these pages. |
| `items[].error_code` | integer | Why the contract failed: `11000`–`11004`, listed on [B2B payment contracts](/b2b-payments/contracts#errors). `null` while the contract hasn't failed. |
| `items[].error_note` | string | Free text about the failure, such as the cancellation note or the payment error message. `null` otherwise. |
| `items[].error_text` | string | The name of `error_code`, e.g. `Recipient Rejected`. `null` otherwise. |
| `items[].recipient` | object | The recipient details exactly as you sent them (only the keys you sent appear), plus `local_name` and `intl_name`. |
| `items[].recipient.payme_id` | string | As sent. |
| `items[].recipient.business_code` | integer | As sent: a number, or a string if you sent a string. |
| `items[].recipient.email` | string | As sent. |
| `items[].recipient.phone` | string | As sent. |
| `items[].recipient.name` | string | As sent. |
| `items[].recipient.language` | string | As sent. |
| `items[].recipient.local_name` | string | The recipient seller's registered business name. `""` while the recipient has no PayMe seller account. |
| `items[].recipient.intl_name` | string | The recipient seller's registered business name in English. `""` while the recipient has no PayMe seller account. |
| `items[].payment` | object | The payment details. |
| `items[].payment.type` | integer | `1` – the initiator sends a payment; `2` – the initiator requests a payment. |
| `items[].payment.method` | string | `funds-transfer`, `credit-card` or `il-direct-debit`. |
| `items[].payment.guarantee_type` | integer | Used by PayMe's financing services. Ignore it. |
| `items[].payment.due_date` | string | When the payment runs, `YYYY-MM-DD HH:MM:SS`. |
| `items[].payment.recurring` | object | Repetition of the payment. Both fields are `null` on a one-time contract. |
| `items[].payment.recurring.frequency_type` | integer | `1` day, `2` week, `3` month, `4` year, `5` quarter. |
| `items[].payment.recurring.iterations` | integer | Number of payments. |
| `links` | object | Links to other pages of the same query. |
| `links.first` | string | URL of the first page. |
| `links.last` | string | URL of the last page. |
| `links.prev` | string | URL of the previous page. `null` on the first page. |
| `links.next` | string | URL of the next page. `null` on the last page. |
| `meta` | object | Pagination details. |
| `meta.current_page` | integer | This page's number. |
| `meta.from` | integer | Position of the first contract on this page in the full result. |
| `meta.last_page` | integer | Number of the last page. |
| `meta.links` | array | Page links for building a pager. |
| `meta.links[].url` | string | URL of the page. `null` when there is no such page. |
| `meta.links[].label` | string | Label of the link: a page number, or the previous/next arrows. |
| `meta.links[].active` | boolean | `true` for the current page. |
| `meta.path` | string | The request URL without its query string. |
| `meta.per_page` | integer | Contracts per page. |
| `meta.to` | integer | Position of the last contract on this page in the full result. |
| `meta.total` | integer | Total number of contracts that match the query. |

```json
{
  "items": [
    {
      "id": 63,
      "guid": "CONT1700-000000AA-EXAMPLE1-CONT0001",
      "description": "December payment",
      "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
      "remote_id": "INV-2026-12",
      "created_date": "2026-11-09 12:00:13",
      "confirmed_by_recipient_date": "2026-11-10 09:15:42",
      "confirmed_by_initiator_date": "2026-11-10 09:15:42",
      "resolution_date": null,
      "status": 3,
      "amount": 500000,
      "currency": "ILS",
      "payme_signature": "5dbf1885ce1d4e082757a2cd6086edd1",
      "fast_reconciliation": false,
      "error_code": null,
      "error_note": null,
      "error_text": null,
      "recipient": {
        "business_code": 515555555,
        "email": "supplier@example.com",
        "phone": "0500000001",
        "name": "Example Supplies Ltd",
        "language": "en",
        "local_name": "Example Supplies Ltd",
        "intl_name": "Example Supplies Ltd"
      },
      "payment": {
        "type": 1,
        "method": "credit-card",
        "guarantee_type": 0,
        "due_date": "2026-12-22 10:00:00",
        "recurring": {
          "frequency_type": null,
          "iterations": null
        }
      }
    }
  ],
  "links": {
    "first": "https://sandbox.payme.io/api/payment-contracts?page=1",
    "last": "https://sandbox.payme.io/api/payment-contracts?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": null,
        "label": "&laquo; Previous",
        "active": false
      },
      {
        "url": "https://sandbox.payme.io/api/payment-contracts?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": null,
        "label": "Next &raquo;",
        "active": false
      }
    ],
    "path": "https://sandbox.payme.io/api/payment-contracts",
    "per_page": 500,
    "to": 1,
    "total": 1
  }
}
```

### 400 — `page` or `per_page` is out of range. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | The error message. |
| `status_additional_info` | string | More detail, such as the field or value that failed. |
| `status_error_code` | integer | PayMe error code. See the error table above. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |

```json
{
  "status_code": 1,
  "status_error_details": "Limit parameter should be between 1 and 500",
  "status_additional_info": "per_page",
  "status_error_code": 27,
  "session": "FhT3aXe7"
}
```

### 500 — A missing, unknown or inactive seller key, or an invalid sort. (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `1` on failure. |
| `status_error_details` | string | The error message. |
| `status_additional_info` | string | More detail, such as the field or value that failed. |
| `status_error_code` | integer | PayMe error code. See the error table above. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |

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