List payment contracts

Credentials

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.

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

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

Node.js

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

import requests

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

print(response.text)

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.
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. 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. 
{
  "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. 
{
  "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. 
{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "payme_client_key",
  "status_error_code": 1,
  "session": "FhT3aXe7"
}