# B2B Payments

## Contracts

- [Contracts](https://docs.payme.io/b2b-payments/contracts): A payment contract moves money between two sellers on a due date (payment.type 1 send, 2 request). Methods: funds-transfer, credit-card, il-direct-debit (ILS); card/direct debit max 5000000 minor units. Card: tokenize (generate-sale sale_type token), attach with add-card-to-seller; direct debit attaches itself after bank approval. Send buyer_key at the TOP LEVEL of POST /payment-contracts; without it PayMe charges the payer's valid card that expires last. Auth: PayMe-Merchant-Key header. Callback payme_signature = md5(client key + client password + guid). Errors 11000-11004, 380-394.

# Contracts

A payment contract moves money between two PayMe sellers on a set date. The seller that creates the contract is the **initiator**; the other seller is the **recipient**. The initiator either sends a payment (`payment.type` `1`) or requests one (`payment.type` `2`). PayMe asks the recipient to approve the contract by SMS or email, and runs the payment on `payment.due_date`.

For the whole flow, from creating a contract to approval, payment and errors, see [Run a B2B payment contract end to end](https://docs.payme.io/b2b-payments/contracts/contract-lifecycle).

Amounts are in minor units (`1000` = 10.00).

## Payment methods

The **payer** is the initiator on `payment.type` `1` and the recipient on `payment.type` `2`.

| `payment.method` | Paid from | Limits |
|---|---|---|
| `funds-transfer` | The payer's PayMe balance | Don't send `buyer_key` (error `394`) |
| `credit-card` | A card attached to the payer's seller account | Up to `5000000` (50,000.00) per contract (error `393`) |
| `il-direct-debit` | An Israeli direct-debit authorization attached to the payer's seller account | `ILS` only (error `320`); up to `5000000` per contract (error `393`) |

## Before you start

1. The initiator needs a PayMe seller account and its `seller_payme_id` (MPL). Partners create one with [`create-seller`](https://docs.payme.io/payments/merchants-management/post-create-seller).
2. For `credit-card` or `il-direct-debit`, add the payment method to the payer's seller account, as described below.
3. Create the contract with [`POST /payment-contracts`](https://docs.payme.io/b2b-payments/contracts/post-user).

## Add a card or direct-debit authorization

Tokenize the card or the bank account with [`generate-sale`](https://docs.payme.io/payments/tokenization/post-generate-sale-tokenization) and `sale_type` `token`. The callback carries a `buyer_key` that identifies this payment method. Save it.

```http
POST https://sandbox.payme.io/api/generate-sale
Content-Type: application/json

{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sale_price": 100,
  "currency": "ILS",
  "product_name": "Card for payment contracts",
  "sale_payment_method": "credit-card",
  "sale_type": "token",
  "sale_callback_url": "https://www.example.com/callback",
  "sale_return_url": "https://www.example.com/return"
}
```

- For a direct-debit authorization, send `"sale_payment_method": "il-direct-debit"` instead. See [Israeli Direct Debit](https://docs.payme.io/payments/il-direct-debit/post-generate-sale-il-direct-debit).
- `sale_price` is required but not charged: PayMe sets it to `100` on a token request.
- To prefill the payment page, add the buyer's details to the `sale_url` as query parameters: `first_name`, `last_name`, `phone`, `email` and `social_id`. For example: `https://sandbox.payme.io/sale/generate/SALE1700-000000AA-EXAMPLE1-SALE0001?first_name=Dana&last_name=Cohen&phone=0500000001&email=dana%40example.com`.

### Attach a card

Attach the card's `buyer_key` to the payer's seller account with [`add-card-to-seller`](https://docs.payme.io/payments/merchants-management/post-add-card-to-seller). Attached cards are listed in `seller_credit_cards` of [`get-sellers`](https://docs.payme.io/payments/query-apis/post-get-sellers).

```http
POST https://sandbox.payme.io/api/add-card-to-seller
Content-Type: application/json

{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567"
}
```

### Direct-debit authorizations attach themselves

You don't attach a direct-debit authorization yourself. Once the bank approves it, usually after a few days, PayMe attaches it to the seller account. It then appears in `seller_bank_authorizations` of [`get-sellers`](https://docs.payme.io/payments/query-apis/post-get-sellers) with `auth_status` `Active`. Until then it can't pay a contract (error `391`).

## Choose the payment method of a contract

Send the payment method's `buyer_key` **at the top level** of the [`POST /payment-contracts`](https://docs.payme.io/b2b-payments/contracts/post-user) body, not inside `payment`. `buyer_key` applies only to `credit-card` and `il-direct-debit`; it must belong to the payer's account (error `392`).

If you don't send `buyer_key` on a contract that sends a payment (`payment.type` `1`), PayMe picks a payment method from the payer's account:

- `credit-card`: among the attached cards that are still valid on `payment.due_date`, the card that **expires last**. If no attached card is valid on the due date, the call fails with error `390`.
- `il-direct-debit`: the last authorization with `auth_status` `Active`. If there is none, the call fails with error `391`.

## Hosts and authentication

Contracts use the Payments API hosts: `https://sandbox.payme.io/api` for testing and `https://live.payme.io/api` for production. Contract endpoints are under `/payment-contracts`.

Every contract call identifies the seller by its `seller_payme_id` (MPL) in the `PayMe-Merchant-Key` header. On `POST /payment-contracts` you can send `seller_payme_id` in the JSON body instead; the file endpoints (`…/invoices`) read the header only. Partners can also send their client key in the `PayMe-Partner-Key` header. A call without a seller key fails with HTTP `500` and error `1`. See [Authentication](https://docs.payme.io/payments/getting-started/authentication) for the keys themselves.

To move funds between two sellers' balances right away, without a contract, use [Transfer funds between sellers](https://docs.payme.io/b2b-payments/wallets/post-generate-transfer).

## Contract lifecycle

| `status` | Meaning |
|---|---|
| `1` | Initial: waiting for the recipient to approve |
| `2` | Recipient confirmed. PayMe confirms the initiator side at once, so the contract moves straight on to `3` |
| `3` | Approved: waiting for the due date |
| `4` | Completed: the payment ran |
| `5` | Failed or cancelled: see `error_code` |

- PayMe runs an approved contract once `payment.due_date` has passed.
- A contract that isn't approved in time is cancelled automatically, with `error_code` `11002` or `11003`.
- The initiator can cancel a contract with `PUT /payment-contracts/{guid}/cancellations`, sending the `PayMe-Merchant-Key` header and a JSON body such as `{"error_note": "Order cancelled"}`. The contract moves to status `5` with `error_code` `11001`. A completed or failed contract can't be cancelled (error `382`).
- Retrying a create is safe: a request that repeats the initiator, recipient, `amount`, `currency`, `payment.due_date` and `payment.type` of a contract created in the last 5 minutes (and not failed) returns that contract instead of creating a second one.

## Callbacks

If the contract has a `callback_url`, PayMe sends it a `POST` on every status change. The body is form-encoded (`application/x-www-form-urlencoded`, not JSON). It holds `notify_type` and every field of the contract, as in the [create response](https://docs.payme.io/b2b-payments/contracts/post-user).

| `notify_type` | When |
|---|---|
| `payment-contract-created` | The contract was created |
| `payment-contract-recipient-approved` | The recipient approved |
| `payment-contract-initiator-approved` | The initiator side was confirmed; the contract waits for the due date (status `3`) |
| `payment-contract-recipient-rejected` | The recipient rejected the contract (`error_code` `11000`) |
| `payment-contract-initiator-rejected` | The initiator side rejected the contract |
| `payment-contract-canceled` | The initiator cancelled the contract (`error_code` `11001`) |
| `payment-contract-confirmation-timeout` | The contract wasn't approved in time (`error_code` `11002` or `11003`) |
| `payment-contract-payment-completed` | The payment ran (status `4`) |
| `payment-contract-payment-failed` | The payment failed (`error_code` `11004`) |

**Verify `payme_signature`.** Contracts use a shorter formula than [sale callbacks](https://docs.payme.io/payments/getting-started/callbacks#verifying-a-callback-payme_signature): the lowercase hex MD5 of the partner's client key, the partner's client password and the contract `guid`, joined with no separator. The partner is the initiator's partner. A seller without a partner client key can't compute it: re-read the contract with `GET /payment-contracts/{guid}` (header `PayMe-Merchant-Key`) instead.

## Errors

### Contract `error_code`

Values of `error_code` on a failed contract, with their `error_text`:

| `error_code` | `error_text` |
|--------------|--------------|
| `11000` | Recipient Rejected |
| `11001` | Initiator Canceled |
| `11002` | Recipient Confirmation Timeout |
| `11003` | Initiator Confirmation Timeout |
| `11004` | Payment Processing Failure |

This is the complete list. For `11004`, `error_note` is free text and may contain a regular PayMe error message.

### API error codes

The contract endpoints return these codes in `status_error_code`:

| Code | Message | When |
|---|---|---|
| `380` | Payment contract not found | No contract with this `guid` involves your seller account |
| `381` | Not enough details for unique recipient identification | Only `recipient.business_code` was sent and it matches no PayMe seller. Add `email` or `phone` |
| `382` | Cannot perform action due to payment contract status inconsistency | The action isn't allowed in the contract's current status |
| `383` | Initiator and recipient are the same | The recipient is the initiator's own account |
| `384` | Recipient account settings problem - please contact Customer Support | The recipient's seller account is inactive |
| `385` | Action not allowed - please contact Customer Support | Your seller account isn't a side of this contract, or didn't upload this file |
| `386` | Uploading multiple files not allowed - please contact Customer Support | Two files of the same `type`, or an unknown `type`, in one upload |
| `387` | Uploading multiple files with same name not allowed | Two files with the same `name` in one upload |
| `388` | File type has to be the same | A replacement file has a different `type` |
| `389` | The payment method isn't attached to the payer's account, please attach it or use a different one | The payer has no attached card or direct-debit authorization |
| `390` | The credit card expiration date is lower than the payment's due date, please add another payment method | No attached card is valid on `payment.due_date` |
| `391` | We didn't find any bank debits we can use for that account, please create a new one or select a different payment method | No direct-debit authorization is `Active` |
| `392` | The selected payment method isn't matching the provided token | `buyer_key` isn't one of the payer's attached payment methods |
| `393` | The contract amount is over the maximum amount for the selected payment method | A `credit-card` or `il-direct-debit` contract over `5000000` |
| `394` | The selected payment method does not match the provided token | `buyer_key` sent with `funds-transfer` |

- [Create a payment contract](https://docs.payme.io/b2b-payments/contracts/post-user): POST /payment-contracts — Create a payment contract

# Create a payment contract

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

## Credentials

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

Creates a contract that sends a payment to another seller (`payment.type` `1`) or requests a payment from one (`payment.type` `2`). PayMe asks the recipient to approve it by SMS or email; once it is approved, the payment runs on `payment.due_date`. See [B2B payment contracts](/b2b-payments/contracts) for the setup, the statuses and the callbacks.

- **Authentication:** send the initiator's `seller_payme_id` (MPL) in the `PayMe-Merchant-Key` header, or as `seller_payme_id` in the body.
- **Amounts** are in minor units (`1000` = 10.00).
- **Payment method:** for `credit-card` and `il-direct-debit`, send the payment method's `buyer_key` at the **top level** of the body, not inside `payment`. Without it, on a contract that sends a payment, PayMe charges the payer's attached card that is valid on the due date and expires last (or the last `Active` direct-debit authorization).
- **Retries are safe:** a request that repeats the initiator, recipient, `amount`, `currency`, `payment.due_date` and `payment.type` of a contract created in the last 5 minutes (and not failed) returns that contract instead of creating a new one.

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`422` | `20` | (a validation message) | A required field is missing or a value is invalid. `status_additional_info` joins all the validation messages.
`400` | `252` | Currency is not allowed for this seller | `currency` isn't enabled for the initiator or the recipient.
`400` | `320` | Currency is not supported | `il-direct-debit` with a currency other than `ILS`.
`400` | `25` | Please verify phone number | `recipient.phone` isn't a valid mobile or international number.
`400` | `251` | Seller was not found | `recipient.payme_id` matches no seller.
`400` | `381` | Not enough details for unique recipient identification | Only `recipient.business_code` was sent and it matches no PayMe seller. Add `email` or `phone`.
`400` | `383` | Initiator and recipient are the same | The recipient is the initiator's own account.
`400` | `384` | Recipient account settings problem - please contact Customer Support | The recipient's seller account is inactive.
`400` | `389` | The payment method isn't attached to the payer's account, please attach it or use a different one | `credit-card` or `il-direct-debit`, and the payer has no such payment method attached.
`400` | `390` | The credit card expiration date is lower than the payment's due date, please add another payment method | No attached card is valid on `payment.due_date`.
`400` | `391` | We didn't find any bank debits we can use for that account, please create a new one or select a different payment method | No direct-debit authorization is `Active`.
`400` | `392` | The selected payment method isn't matching the provided token | `buyer_key` isn't one of the payer's attached payment methods of this `payment.method`.
`400` | `393` | The contract amount is over the maximum amount for the selected payment method | A `credit-card` or `il-direct-debit` contract over `5000000`.
`400` | `394` | The selected payment method does not match the provided token | `buyer_key` sent with `funds-transfer`.
`500` | `1` | Required parameter is missing | No seller key: neither the `PayMe-Merchant-Key` header nor `seller_payme_id` in the body. `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 initiator's seller account is inactive.
`500` | `900` | Please provide all required information in JSON format. Make sure to include 'Content-Type: application/json' header | The request isn't JSON.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | The initiator's `seller_payme_id` (MPL). You can send `seller_payme_id` in the JSON body instead. |

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | string | yes | What the payment is for, for example an invoice number. The recipient sees it. |
| `amount` | integer | yes | Amount in minor units (`1000` = 10.00). At least `1`. `credit-card` and `il-direct-debit` contracts: at most `5000000` (error `393`). |
| `currency` | string | yes | The currency, as a 3-letter ISO 4217 code: ILS, USD, EUR, GBP, TRY, CHF, SEK, NOK, CAD, ZAR, JPY, AUD, AED, ARS, BHD, BRL, CNY, INR, KRW, KWD, KZT, MXN, NGN, PLN, RON, RUB, SAR, UAH, PHP, VND or HKD. It must be enabled for both sellers on the contract, otherwise the call returns error `252`. `il-direct-debit` supports only `ILS`. |
| `buyer_key` | string | no | The payment method to charge: a `buyer_key` from `seller_credit_cards` or `seller_bank_authorizations` of [`get-sellers`](/payments/query-apis/post-get-sellers) for the payer. Send it at the top level, not inside `payment`. Only for `credit-card` and `il-direct-debit`; with `funds-transfer` it returns error `394`. If you omit it on a contract that sends a payment, PayMe charges the attached card that is valid on `payment.due_date` and expires last, or the last `Active` direct-debit authorization. |
| `remote_id` | string | no | Your own reference for the contract: letters, digits, `-` and `_`. PayMe doesn't check that it is unique. |
| `callback_url` | string | no | A valid URL that receives a callback on every status change. See [Callbacks](/b2b-payments/contracts#callbacks). |
| `recipient` | object | yes | Who receives the payment (`payment.type` `1`) or is asked to pay (`payment.type` `2`). Send at least one of `payme_id`, `business_code`, `email` or `phone`; PayMe uses them to find the recipient's PayMe seller account. If no seller matches, PayMe still sends the approval request to the `email` or `phone`, and the recipient opens a PayMe account when approving. To target one specific seller, send `payme_id` alone. |
| `recipient.payme_id` | string | no | The recipient's `seller_payme_id` (MPL), or the `seller_payme_id_checksum` from [List previous recipients](/b2b-payments/contracts/get-recipient). When you send it, send no other `recipient` field (validation error otherwise). |
| `recipient.business_code` | integer | no | The recipient's business number. If it is the only identifier you send, it must match a PayMe seller (error `381` otherwise). |
| `recipient.email` | string | no | The recipient's email address. PayMe sends the approval request here and uses it to find the recipient's seller account. |
| `recipient.phone` | string | no | The recipient's mobile number: an Israeli mobile number (e.g. `0500000001`) or an international number with its country code. PayMe sends the approval request here by SMS and uses it to find the recipient's seller account. An invalid number returns error `25`. |
| `recipient.name` | string | no | The recipient's name. Returned by [List previous recipients](/b2b-payments/contracts/get-recipient). |
| `recipient.language` | string | no | The language of the notifications sent to the recipient: `he` or `en`. Default: `he`. If the recipient already has a PayMe seller account, that account's language is used instead. |
| `payment` | object | yes | The payment details. |
| `payment.type` | integer | yes | `1` – the initiator sends a payment to the recipient; `2` – the initiator requests a payment from the recipient. |
| `payment.method` | string | yes | `funds-transfer` – from the payer's PayMe balance; `credit-card` – an attached card; `il-direct-debit` – an attached Israeli direct-debit authorization (`ILS` only). |
| `payment.due_date` | string | yes | When the payment runs, `YYYY-MM-DD HH:MM:SS`. Must be in the future. |
| `payment.recurring` | object | no | Send it to repeat the payment. The contract is recurring only when both fields are sent. |
| `payment.recurring.frequency_type` | integer | no | How often the payment repeats: `1` day, `2` week, `3` month, `4` year, `5` quarter. |
| `payment.recurring.iterations` | integer | no | Number of payments, `1` to `54`. Required when you send `frequency_type`. |

### Request example

```json
{
  "description": "December payment",
  "amount": 500000,
  "currency": "ILS",
  "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567",
  "remote_id": "INV-2026-12",
  "callback_url": "https://www.example.com/callback",
  "recipient": {
    "business_code": 515555555,
    "email": "supplier@example.com",
    "phone": "0500000001",
    "name": "Example Supplies Ltd",
    "language": "en"
  },
  "payment": {
    "type": 1,
    "method": "credit-card",
    "due_date": "2026-12-22 10:00:00"
  }
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/payment-contracts' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  --data-raw '{
  "description": "December payment",
  "amount": 500000,
  "currency": "ILS",
  "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567",
  "remote_id": "INV-2026-12",
  "callback_url": "https://www.example.com/callback",
  "recipient": {
    "business_code": 515555555,
    "email": "supplier@example.com",
    "phone": "0500000001",
    "name": "Example Supplies Ltd",
    "language": "en"
  },
  "payment": {
    "type": 1,
    "method": "credit-card",
    "due_date": "2026-12-22 10:00:00"
  }
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/payment-contracts", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
  body: JSON.stringify({
    "description": "December payment",
    "amount": 500000,
    "currency": "ILS",
    "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567",
    "remote_id": "INV-2026-12",
    "callback_url": "https://www.example.com/callback",
    "recipient": {
      "business_code": 515555555,
      "email": "supplier@example.com",
      "phone": "0500000001",
      "name": "Example Supplies Ltd",
      "language": "en"
    },
    "payment": {
      "type": 1,
      "method": "credit-card",
      "due_date": "2026-12-22 10:00:00"
    }
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/payment-contracts",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    json={
        "description": "December payment",
        "amount": 500000,
        "currency": "ILS",
        "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567",
        "remote_id": "INV-2026-12",
        "callback_url": "https://www.example.com/callback",
        "recipient": {
            "business_code": 515555555,
            "email": "supplier@example.com",
            "phone": "0500000001",
            "name": "Example Supplies Ltd",
            "language": "en",
        },
        "payment": {
            "type": 1,
            "method": "credit-card",
            "due_date": "2026-12-22 10:00:00",
        },
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "description": "December payment",
  "amount": 500000,
  "currency": "ILS",
  "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567",
  "remote_id": "INV-2026-12",
  "callback_url": "https://www.example.com/callback",
  "recipient": {
    "business_code": 515555555,
    "email": "supplier@example.com",
    "phone": "0500000001",
    "name": "Example Supplies Ltd",
    "language": "en"
  },
  "payment": {
    "type": 1,
    "method": "credit-card",
    "due_date": "2026-12-22 10:00:00"
  }
}
BODY;

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

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

echo $response;
```

## Responses

### 201 — The contract was created (or, on a retry within 5 minutes, the existing contract is returned). The contract fields appear at the top level and again under `data`. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |
| `id` | integer | PayMe's numeric ID of the contract. |
| `guid` | string | The contract ID (`CONT…`). Use it in the contract URLs, e.g. `/payment-contracts/{guid}/invoices`. |
| `description` | string | What the payment is for, as sent. |
| `seller_payme_id` | string | The initiator's `seller_payme_id` (MPL). |
| `remote_id` | string | Your reference, as sent. `null` if you didn't send one. |
| `created_date` | string | When the contract was created, `YYYY-MM-DD HH:MM:SS`. |
| `confirmed_by_recipient_date` | string | When the recipient approved, `YYYY-MM-DD HH:MM:SS`. `null` until then. |
| `confirmed_by_initiator_date` | string | When the initiator side was confirmed, `YYYY-MM-DD HH:MM:SS`. `null` until then. |
| `resolution_date` | string | Reserved. Currently always `null`. |
| `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`). |
| `amount` | integer | Amount in minor units (`1000` = 10.00). |
| `currency` | string | ISO 4217 currency code, e.g. `ILS`. |
| `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). |
| `fast_reconciliation` | boolean | PayMe-internal processing flag. `false` for contracts created as described in these pages. |
| `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. |
| `error_note` | string | Free text about the failure, such as the cancellation note or the payment error message. `null` otherwise. |
| `error_text` | string | The name of `error_code`, e.g. `Recipient Rejected`. `null` otherwise. |
| `recipient` | object | The recipient details exactly as you sent them (only the keys you sent appear), plus `local_name` and `intl_name`. |
| `recipient.payme_id` | string | As sent. |
| `recipient.business_code` | integer | As sent: a number, or a string if you sent a string. |
| `recipient.email` | string | As sent. |
| `recipient.phone` | string | As sent. |
| `recipient.name` | string | As sent. |
| `recipient.language` | string | As sent. |
| `recipient.local_name` | string | The recipient seller's registered business name. `""` while the recipient has no PayMe seller account. |
| `recipient.intl_name` | string | The recipient seller's registered business name in English. `""` while the recipient has no PayMe seller account. |
| `payment` | object | The payment details. |
| `payment.type` | integer | `1` – the initiator sends a payment; `2` – the initiator requests a payment. |
| `payment.method` | string | `funds-transfer`, `credit-card` or `il-direct-debit`. |
| `payment.guarantee_type` | integer | Used by PayMe's financing services. Ignore it. |
| `payment.due_date` | string | When the payment runs, `YYYY-MM-DD HH:MM:SS`. |
| `payment.recurring` | object | Repetition of the payment. Both fields are `null` on a one-time contract. |
| `payment.recurring.frequency_type` | integer | `1` day, `2` week, `3` month, `4` year, `5` quarter. |
| `payment.recurring.iterations` | integer | Number of payments. |
| `data` | object | The same contract fields as the top level, repeated. |

```json
{
  "status_code": 0,
  "session": "FhT3aXe7",
  "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": null,
  "confirmed_by_initiator_date": null,
  "resolution_date": null,
  "status": 1,
  "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": "",
    "intl_name": ""
  },
  "payment": {
    "type": 1,
    "method": "credit-card",
    "guarantee_type": null,
    "due_date": "2026-12-22 10:00:00",
    "recurring": {
      "frequency_type": null,
      "iterations": null
    }
  },
  "data": {
    "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": null,
    "confirmed_by_initiator_date": null,
    "resolution_date": null,
    "status": 1,
    "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": "",
      "intl_name": ""
    },
    "payment": {
      "type": 1,
      "method": "credit-card",
      "guarantee_type": null,
      "due_date": "2026-12-22 10:00:00",
      "recurring": {
        "frequency_type": null,
        "iterations": null
      }
    }
  }
}
```

### 422 — Validation error: a required field is missing or a value is invalid. (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. On `422`, every validation message, joined with spaces. |
| `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": "The payment.method field is required.",
  "status_additional_info": "The payment.method field is required.",
  "status_error_code": 20,
  "session": "FhT3aXe7"
}
```

### 400 — The request is valid but can't be carried out. See the error table above. (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. On `422`, every validation message, joined with spaces. |
| `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": "The contract amount is over the maximum amount for the selected payment method",
  "status_additional_info": "Max amount 5000000",
  "status_error_code": 393,
  "session": "FhT3aXe7"
}
```

### 500 — No seller key, an unknown or inactive seller, or a body that isn't JSON. (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. On `422`, every validation message, joined with spaces. |
| `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"
}
```

- [Run a B2B payment contract end to end](https://docs.payme.io/b2b-payments/contracts/contract-lifecycle): B2B contract flow. Header PayMe-Merchant-Key = MPL. payment.type 1 send (initiator pays) or 2 request (recipient pays); the recipient approves in PayMe. Methods: funds-transfer, credit-card, il-direct-debit (ILS only, 320); card/debit max 5000000 (393). Card: tokenize, add-card-to-seller, send buyer_key top level. A repeat create within 5 min returns the same contract. Status 1, 2, 3 (auto), 4; or 5 with error_code 11000-11004 (read error_code); payment-contract-* callbacks. Change: PUT /payment-contracts/{guid}; cancel: .../cancellations (initiator); files: .../invoices. Errors 380-394.

## Prerequisites

- The initiator's PayMe seller account and its seller_payme_id (MPL)
- For card or direct-debit contracts: the payer's payment method attached to its seller account

## Related

- [Contracts](https://docs.payme.io/b2b-payments/contracts)
- [Create a payment contract](https://docs.payme.io/b2b-payments/contracts/post-user)
- [List payment contracts](https://docs.payme.io/b2b-payments/contracts/get-contracts)
- [List previous recipients](https://docs.payme.io/b2b-payments/contracts/get-recipient)
- [Upload contract files](https://docs.payme.io/b2b-payments/contracts/post-contracts-files)
- [List contract files](https://docs.payme.io/b2b-payments/contracts/get-contracts-files)
- [Save a card (token sale)](https://docs.payme.io/payments/tokenization/post-generate-sale-tokenization)
- [Attach a saved card to a seller](https://docs.payme.io/payments/merchants-management/post-add-card-to-seller)
- [List sellers](https://docs.payme.io/payments/query-apis/post-get-sellers)
- [Callbacks](https://docs.payme.io/payments/getting-started/callbacks)
- [Callback types reference](https://docs.payme.io/payments/getting-started/callback-types)
- [Transfer funds between sellers](https://docs.payme.io/b2b-payments/wallets/post-generate-transfer)

# Run a B2B payment contract end to end

A payment contract moves money between two PayMe sellers on a date you set, after the other seller approves it. This guide takes one contract from start to finish: choose the direction, prepare the payment method, create the contract, follow its approval with callbacks, change or cancel it, attach invoices, and handle errors. The concepts are on [B2B payment contracts](https://docs.payme.io/b2b-payments/contracts/overview), and each step links to the reference page with the full field tables.

Every call in this guide:

- goes to `https://sandbox.payme.io/api` while you test, and to `https://live.payme.io/api` in production;
- authenticates with the seller's `seller_payme_id` (MPL) in the `PayMe-Merchant-Key` header. A partner acting for one of its sellers sends that seller's MPL, and can add its own client key in the `PayMe-Partner-Key` header;
- sends JSON (`Content-Type: application/json`), with amounts in minor units (`500000` = 5,000.00).

Keep the MPL on your server. See [Hosts and authentication](https://docs.payme.io/b2b-payments/contracts/overview#hosts-and-authentication).

## Step 1: Choose the direction and the payment method

The seller that creates the contract is the **initiator**. The other seller is the **recipient**, and the recipient always approves the contract. `payment.type` sets who pays:

| `payment.type` | Use it to | Who pays | Who approves |
|---|---|---|---|
| `1` – send | Pay another seller, for example a supplier | The initiator | The recipient |
| `2` – request | Collect a payment from another seller | The recipient | The recipient |

`payment.method` sets where the money comes from:

| `payment.method` | Paid from | Limits |
|---|---|---|
| `funds-transfer` | The payer's PayMe balance | Don't send `buyer_key` (error `394`) |
| `credit-card` | A card attached to the payer's seller account | Up to `5000000` (50,000.00) per contract (error `393`) |
| `il-direct-debit` | An Israeli direct-debit authorization attached to the payer's seller account | `ILS` only (error `320`). Up to `5000000` per contract (error `393`) |

The currency must be enabled for both sellers (error `252`).

The payment requests in this guide use `funds-transfer`. A request paid by card or direct debit depends on a payment method that the recipient sets up for your contracts in PayMe: contact PayMe before you build one.

## Step 2: Prepare the payer's card or direct debit

Do this step only for a contract that sends a payment (`payment.type` `1`) by `credit-card` or `il-direct-debit`. With `funds-transfer`, go to step 3.

**A card:**

1. Tokenize the card with [`generate-sale`](https://docs.payme.io/payments/tokenization/post-generate-sale-tokenization) and `sale_type` `token`. The `sale-complete` callback carries the card's `buyer_key`.
2. Attach the `buyer_key` to the initiator's seller account with [`add-card-to-seller`](https://docs.payme.io/payments/merchants-management/post-add-card-to-seller).
3. Check that the card appears in `seller_credit_cards` of [`get-sellers`](https://docs.payme.io/payments/query-apis/post-get-sellers). It must still be valid on the contract's `payment.due_date` (error `390`).

**A direct-debit authorization:** tokenize the bank account with `"sale_payment_method": "il-direct-debit"`. You don't attach it yourself: once the bank approves it, PayMe attaches it to the seller account, and it appears in `seller_bank_authorizations` of `get-sellers` with `auth_status` `Active`. Until then it can't pay a contract (error `391`).

The requests, with examples, are on [Add a card or direct-debit authorization](https://docs.payme.io/b2b-payments/contracts/overview#add-a-card-or-direct-debit-authorization).

## Step 3: Create the contract

Call [`POST /payment-contracts`](https://docs.payme.io/b2b-payments/contracts/post-user). This contract sends 5,000.00 by card on December 22:

```bash
curl -X POST https://sandbox.payme.io/api/payment-contracts \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: MPLDEMO-MPLDEMO-MPLDEMO-1234567' \
  -d '{
    "description": "December payment",
    "amount": 500000,
    "currency": "ILS",
    "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-1234567",
    "remote_id": "INV-2026-12",
    "callback_url": "https://your-server.example.com/payme/contracts",
    "recipient": {
      "email": "supplier@example.com",
      "phone": "0500000001",
      "name": "Example Supplies Ltd",
      "language": "en"
    },
    "payment": {
      "type": 1,
      "method": "credit-card",
      "due_date": "2026-12-22 10:00:00"
    }
  }'
```

The call returns HTTP `201` and the contract in status `1` (abridged):

```json
{
  "status_code": 0,
  "guid": "CONT1700-000000AA-EXAMPLE1-CONT0001",
  "status": 1,
  "amount": 500000,
  "currency": "ILS",
  "remote_id": "INV-2026-12",
  "error_code": null
}
```

Store `guid` with your order: every later call uses it.

**Send `buyer_key` at the top level** of the body, as above. A `buyer_key` inside `payment` is ignored, and PayMe then picks the card itself: among the attached cards that are valid on `payment.due_date`, the one that expires last. For `il-direct-debit`, PayMe picks the last `Active` authorization. See [Choose the payment method of a contract](https://docs.payme.io/b2b-payments/contracts/overview#choose-the-payment-method-of-a-contract).

**Name the recipient.**

- To pay one specific PayMe seller, send its MPL as `recipient.payme_id`, and no other `recipient` field. For a recipient of your earlier contracts, take its `seller_payme_id_checksum` from [List previous recipients](https://docs.payme.io/b2b-payments/contracts/get-recipient).
- Otherwise send `email` or `phone`, or both. PayMe uses them to find the recipient's PayMe account and to send the approval request. A recipient without a PayMe account opens one while approving. These details can match more than one PayMe account, so prefer `payme_id` when you know it.
- `business_code` alone must match a PayMe seller (error `381`).

**Set the due date** in the future, as `YYYY-MM-DD HH:MM:SS`. This guide follows a one-time contract. To repeat the payment, add `payment.recurring`: see [Create a payment contract](https://docs.payme.io/b2b-payments/contracts/post-user).

**Retrying a create is safe for 5 minutes.** A request that repeats the initiator, recipient, `amount`, `currency`, `payment.due_date` and `payment.type` of a contract created in the last 5 minutes, and not failed, returns that contract with the same `guid`. It doesn't create a second contract or send a second `payment-contract-created` callback. After 5 minutes, the same request creates a new contract.

When the recipient has no PayMe account yet, PayMe can't tell two such recipients apart. A second contract to another new recipient, with the same amount, currency, due date and type within 5 minutes, returns the first contract. Compare the `recipient` in the response with the one you sent.

To request a payment instead, send `payment.type` `2`. For example, to collect 1,200.00 from another seller's PayMe balance:

```json
{
  "description": "Invoice 1002",
  "amount": 120000,
  "currency": "ILS",
  "remote_id": "INV-1002",
  "callback_url": "https://your-server.example.com/payme/contracts",
  "recipient": {
    "payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-7654321"
  },
  "payment": {
    "type": 2,
    "method": "funds-transfer",
    "due_date": "2026-12-31 10:00:00"
  }
}
```

## Step 4: Follow the approval and the payment

After you create the contract, PayMe asks the recipient to approve it, and the recipient approves in PayMe. Each change of status sends a callback to the contract's `callback_url`:

| What happens | `status` | `error_code` | `notify_type` |
|---|---|---|---|
| You created the contract | `1` | | `payment-contract-created` |
| The recipient approves | `2`, then `3` | | `payment-contract-recipient-approved`, then `payment-contract-initiator-approved` |
| The recipient rejects | `5` | `11000` | `payment-contract-recipient-rejected` |
| Nobody approved in time | `5` | `11002` or `11003` | `payment-contract-confirmation-timeout` or `payment-contract-payment-failed` |
| You cancel the contract (step 6) | `5` | `11001` | `payment-contract-canceled` |
| The due date passed and the payment ran | `4` | | `payment-contract-payment-completed` |
| The payment failed | `5` | `11004` | `payment-contract-payment-failed` |

- **Approval.** Status `2` doesn't last: when the recipient approves, PayMe confirms the initiator side at once, so the contract moves on to `3` and waits for the due date. You receive both callbacks.
- **Payment.** PayMe runs an approved contract once `payment.due_date` has passed. A completed contract is final.
- **Failure.** Status `5` always carries `error_code` and `error_text`. Read `error_code` to know why a contract failed, not `notify_type`: a contract that wasn't approved in time can arrive as `payment-contract-payment-failed` too. On `11004`, `error_note` holds the payment error as free text. The codes are on [Errors](https://docs.payme.io/b2b-payments/contracts/overview#errors).
- **No approval.** A contract that isn't approved in time is cancelled automatically. Don't rely on a fixed approval window in your own flow: act on the callback.
- [B2B payment contracts](https://docs.payme.io/b2b-payments/contracts/overview#callbacks) also lists `payment-contract-initiator-rejected`. Handle it like any status `5` callback: read `error_code`.

### Handle the callbacks

Each callback is a `POST` with a form-encoded body (`application/x-www-form-urlencoded`, not JSON). It holds `notify_type` and every field of the contract, the same fields as the create response.

- Reply `200` within 5 seconds, then do the slow work. Delivery, retries and ordering work as for sale callbacks: see [Callbacks](https://docs.payme.io/payments/getting-started/callbacks#delivery-retries-duplicates-and-ordering).
- Callbacks can arrive more than once and out of order. Act on `status`, and don't let a late callback overwrite a status `4` or `5` you already recorded.
- Partners verify `payme_signature` with the contract formula on [B2B payment contracts](https://docs.payme.io/b2b-payments/contracts/overview#callbacks). A seller without a partner client key re-reads the contract instead (below).
- Only the initiator's `callback_url` receives callbacks. The recipient side follows its contracts with [List payment contracts](https://docs.payme.io/b2b-payments/contracts/get-contracts) and `recipient=true`.

### Read a contract

Read one contract with `GET /payment-contracts/{guid}`. Either seller on the contract can call it:

```bash
curl https://sandbox.payme.io/api/payment-contracts/CONT1700-000000AA-EXAMPLE1-CONT0001 \
  -H 'PayMe-Merchant-Key: MPLDEMO-MPLDEMO-MPLDEMO-1234567'
```

It returns the contract fields at the top level and again under `data`, plus `status_code`. A seller that isn't on the contract gets error `380`.

To reconcile many contracts, page through [List payment contracts](https://docs.payme.io/b2b-payments/contracts/get-contracts), filtered by `status`, `remote_id` or the other filters on that page.

## Step 5: Change a contract

Call `PUT /payment-contracts/{guid}` with the fields to change. Either seller on the contract can call it; another seller gets error `385`. Change a contract before its due date.

You can change:

- `description`;
- the card or direct-debit authorization that pays: send its `buyer_key` together with `payment.method`. The same rules as on create apply (errors `389` to `394`).

For example, to pay with another attached card:

```bash
curl -X PUT https://sandbox.payme.io/api/payment-contracts/CONT1700-000000AA-EXAMPLE1-CONT0001 \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: MPLDEMO-MPLDEMO-MPLDEMO-1234567' \
  -d '{
    "buyer_key": "BUYERDEMO-BUYERDEMO-BUYERDEMO-7654321",
    "payment": {
      "method": "credit-card"
    }
  }'
```

The response is the updated contract, with `status_code` `0`.

You can't change `amount`, `currency`, `payment.type`, `payment.due_date`, `payment.recurring`, `remote_id`, `callback_url`, or the recipient's `payme_id`, `business_code`, `email`, `phone` or `language`: the call fails with HTTP `422` and error `20`. To change any of them, cancel the contract and create a new one.

## Step 6: Cancel a contract

Only the initiator can cancel. Call `PUT /payment-contracts/{guid}/cancellations` with a JSON body. `error_note` is your reason, and PayMe stores it on the contract:

```bash
curl -X PUT https://sandbox.payme.io/api/payment-contracts/CONT1700-000000AA-EXAMPLE1-CONT0001/cancellations \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: MPLDEMO-MPLDEMO-MPLDEMO-1234567' \
  -d '{"error_note": "Order cancelled"}'
```

- The contract moves to status `5` with `error_code` `11001` (`Initiator Canceled`), and PayMe sends `payment-contract-canceled`. The response is the contract, at the top level and under `data`.
- Send a body: a request without JSON fails with error `900`, and an empty one with `901`.
- A completed or failed contract can't be cancelled (error `382`).
- The recipient can't cancel through the API. Before approving, the recipient can reject the contract in PayMe instead (`error_code` `11000`).

## Step 7: Attach invoices and other files

Either seller on the contract can attach files to it, such as an invoice or a receipt. Send the content Base64-encoded with [Upload contract files](https://docs.payme.io/b2b-payments/contracts/post-contracts-files):

```bash
curl -X POST https://sandbox.payme.io/api/payment-contracts/CONT1700-000000AA-EXAMPLE1-CONT0001/invoices \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: MPLDEMO-MPLDEMO-MPLDEMO-1234567' \
  -d '{
    "invoices": [
      {
        "name": "invoice-1001.pdf",
        "type": "Invoice Receipt",
        "base64": "JVBERi0xLjQK",
        "mime_type": "application/pdf"
      }
    ]
  }'
```

The response lists the files under `Invoices` (capital `I`), each with its `id` (`INV…`) and a `url`. Store the `id`.

- On a one-time contract, one request can carry one file of each `type` (error `386`). File names must be unique within a request (error `387`).
- Both sellers see every file: [List contract files](https://docs.payme.io/b2b-payments/contracts/get-contracts-files).
- Only the seller that uploaded a file can [replace](https://docs.payme.io/b2b-payments/contracts/put-contracts-files) it, with the same `type` (error `388`), or [delete](https://docs.payme.io/b2b-payments/contracts/delete-contracts-files) it. Another seller gets error `385`.
- A delete also needs a JSON body that isn't empty, for example `{"confirm": true}`.

## Errors and what to do

Contract calls return `status_code` `1`, with the code in `status_error_code` and the message in `status_error_details`. Check `status_code`, not only the HTTP status. These are the contract codes:

| Code | When | What to do |
|---|---|---|
| `380` | No contract with this `guid` involves your seller account. Also returned when a seller that isn't the initiator tries to cancel | Check the `guid` and the MPL in `PayMe-Merchant-Key` |
| `381` | Only `recipient.business_code` was sent and it matches no PayMe seller | Add the recipient's `email` or `phone` |
| `382` | The action isn't allowed in the contract's current status, for example cancelling a completed contract | Read the contract and act on its `status` |
| `383` | The recipient is the initiator's own account | Name another seller |
| `384` | The recipient's seller account is inactive | The recipient contacts PayMe support |
| `385` | Your seller account isn't a side of this contract, or didn't upload this file | Call with the MPL of a seller on the contract, or of the file's uploader |
| `386` | Two files of the same `type`, or an unknown `type`, in one upload | Send one file of each type per request |
| `387` | Two files with the same `name` in one upload | Rename one of them |
| `388` | A replacement file has a different `type` | Keep the file's `type`, or upload a new file |
| `389` | The payer has no card or direct-debit authorization of this method attached | Do [step 2](#step-2-prepare-the-payers-card-or-direct-debit) first |
| `390` | No attached card is valid on `payment.due_date` | Attach a card that is valid on the due date, or move the date in a new contract |
| `391` | No direct-debit authorization is `Active` | Wait for the bank's approval, or use another method |
| `392` | `buyer_key` isn't one of the payer's attached payment methods | Take the `buyer_key` from `get-sellers` for the payer |
| `393` | A `credit-card` or `il-direct-debit` contract over `5000000` | Lower the amount, or use `funds-transfer` |
| `394` | `buyer_key` sent with `funds-transfer` | Remove `buyer_key` |

Other codes you may meet: `1` (no seller key), `251` (unknown seller key), `163` (inactive seller), `252` (currency not enabled for one of the sellers), `25` (invalid `recipient.phone`), `20` (validation, HTTP `422`; `status_additional_info` lists every message) and `900`/`901` (the body isn't valid JSON). The full tables are on [Create a payment contract](https://docs.payme.io/b2b-payments/contracts/post-user) and [B2B payment contracts](https://docs.payme.io/b2b-payments/contracts/overview#errors).

## Before you go live

- [ ] Calls go to `https://live.payme.io/api` with production MPLs, and the MPLs stay on your server.
- [ ] For card and direct-debit contracts, the payer's payment method is attached in production, and a card is valid on the due date.
- [ ] `callback_url` is a public HTTPS address, and your handler replies `200` within 5 seconds.
- [ ] Partners verify `payme_signature`. Sellers without a partner client key re-read the contract with `GET /payment-contracts/{guid}`.
- [ ] You store each `guid` and reconcile with [List payment contracts](https://docs.payme.io/b2b-payments/contracts/get-contracts), because a callback is dropped after its last attempt.

- [List payment contracts](https://docs.payme.io/b2b-payments/contracts/get-contracts): GET /payment-contracts — List payment contracts

# List payment contracts

- 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"
}
```

- [List contract files](https://docs.payme.io/b2b-payments/contracts/get-contracts-files): GET /payment-contracts/{payment_contract_guid}/invoices — List contract files

# List contract files

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

## Credentials

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

Lists the files (invoices, receipts and other documents) attached to a contract. Both sellers on the contract see every file, whoever uploaded it. Authenticate with your MPL in the `PayMe-Merchant-Key` header; only the two sellers on the contract can call it (error `385` otherwise).

To list one type of file, add `type`, e.g. `?type=Invoice%20Receipt`. To get one file, call `GET /payment-contracts/{payment_contract_guid}/invoices/{invoice_guid}`: it returns that file's `name`, `mime_type`, `type`, `url` and `id` at the top level (not in an array), or error `757` if the contract has no such file.

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`400` | `251` | Seller was not found | The `PayMe-Merchant-Key` header is missing. `status_additional_info` is the header name. 
`400` | `385` | Action not allowed - please contact Customer Support | This seller is neither side of the contract. `status_additional_info` is the seller key. 
`400` | `757` | Invoice not found | You asked for one file and the contract has no file with that ID. 
`422` | `20` | (a validation message) | `type` is not a known file type. `status_additional_info` lists what failed. 
`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. 
`500` | `380` | Payment contract not found | No contract has this GUID. `status_additional_info` is the GUID. 



## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | Your `seller_payme_id` (MPL). You must be one of the two sellers on the contract. |
| `payment_contract_guid` | path | string | yes | The contract's `guid`, as returned when the contract was created, e.g. `CONT1700-000000AA-EXAMPLE1-CONT0001`. It already starts with `CONT`; don't add another prefix. |
| `type` | query | string | no | Only files of this type: `Invoice`, `Invoice Receipt`, `Receipt`, `Invoice Refund`, `Receipt Donation`, `Order`, `Delivery`, `Return`, `Offer` or `PurchaseOrder`. URL-encode the space (`Invoice%20Receipt`). |

## Code samples

### curl

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

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices", {
  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/<payment_contract_guid>/invoices",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices');
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 — The contract's files. An empty array if none is attached. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |
| `invoices` | array | The files attached to the contract. |
| `invoices[].name` | string | File name, as uploaded. |
| `invoices[].mime_type` | string | The file's MIME type, e.g. `application/pdf`. |
| `invoices[].type` | string | The file type. |
| `invoices[].url` | string | Link to the file. |
| `invoices[].id` | string | The file ID (`INV…`). Use it as `invoice_guid` to replace or delete the file. |

```json
{
  "status_code": 0,
  "session": "FhT3aXe7",
  "invoices": [
    {
      "name": "invoice-1001.pdf",
      "mime_type": "application/pdf",
      "type": "Invoice Receipt",
      "url": "https://reparser2.paymeservice.com/external/files/3e8ce1bb-c6ff-4e05-94df-f24f30928180",
      "id": "INV17000-000000AA-EXAMPLE1-FILE0001"
    }
  ]
}
```

### 400 — Bad Request (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "PayMe-Merchant-Key",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```

### 422 — Unprocessable Entity (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "The selected type is invalid.",
  "status_additional_info": "The selected type is invalid.",
  "status_error_code": 20,
  "session": "FhT3aXe7"
}
```

### 500 — Internal Server Error (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```

- [Upload contract files](https://docs.payme.io/b2b-payments/contracts/post-contracts-files): POST /payment-contracts/{payment_contract_guid}/invoices — Upload contract files

# Upload contract files

- Sandbox: `POST https://sandbox.payme.io/api/payment-contracts/{payment_contract_guid}/invoices`
- Production: `POST https://live.payme.io/api/payment-contracts/{payment_contract_guid}/invoices`

## Credentials

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

Attaches one or more files (an invoice, a receipt or another document) to a contract. Either seller on the contract can upload. Only the seller who uploaded a file can later replace or delete it. Send the file content Base64-encoded in JSON, with `Content-Type: application/json` and your MPL in the `PayMe-Merchant-Key` header.

On a one-time contract, one request can carry at most one file of each `type` (error `386`). A later request may add another file of the same type. File names must be unique within a request (error `387`).

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`400` | `251` | Seller was not found | The `PayMe-Merchant-Key` header is missing. `status_additional_info` is the header name. 
`400` | `385` | Action not allowed - please contact Customer Support | This seller is neither side of the contract. `status_additional_info` is the seller key. 
`400` | `386` | Uploading multiple files not allowed - please contact Customer Support | On a one-time contract, the request has two files of the same `type`, or a `type` that isn't in the list. 
`422` | `20` | (a validation message) | `invoices`, or a `name`, `type`, `base64` or `mime_type` inside it, is missing. `status_additional_info` lists what failed. 
`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. 
`500` | `380` | Payment contract not found | No contract has this GUID. `status_additional_info` is the GUID. 
`500` | `387` | Uploading multiple files with same name not allowed | Two files in the request have the same name. 
`500` | `900` | Please provide all required information in JSON format. Make sure to include 'Content-Type: application/json' header | The request is not JSON. 
`500` | `901` | Please verify that the JSON provided is valid | The JSON body is empty or invalid. 



## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | Your `seller_payme_id` (MPL). You must be one of the two sellers on the contract. |
| `payment_contract_guid` | path | string | yes | The contract's `guid`, as returned when the contract was created, e.g. `CONT1700-000000AA-EXAMPLE1-CONT0001`. It already starts with `CONT`; don't add another prefix. |

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `invoices` | array | yes | The files to attach. |
| `invoices[].name` | string | yes | File name, e.g. `invoice-1001.png`. Must be unique within the request (error `387`). |
| `invoices[].type` | string | yes | The file type: `Invoice`, `Invoice Receipt`, `Invoice Transaction`, `Receipt`, `Invoice Refund`, `Receipt Donation`, `Order`, `Delivery`, `Return`, `Offer` or `PurchaseOrder`. On a one-time contract, another value returns error `386`. |
| `invoices[].base64` | string | yes | The file content, Base64-encoded. |
| `invoices[].mime_type` | string | yes | The file's MIME type, e.g. `application/pdf` or `image/png`. |

### Request example

```json
{
  "invoices": [
    {
      "name": "invoice-1001.png",
      "type": "Invoice Receipt",
      "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
      "mime_type": "image/png"
    }
  ]
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  --data-raw '{
  "invoices": [
    {
      "name": "invoice-1001.png",
      "type": "Invoice Receipt",
      "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
      "mime_type": "image/png"
    }
  ]
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
  body: JSON.stringify({
    "invoices": [
      {
        "name": "invoice-1001.png",
        "type": "Invoice Receipt",
        "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
        "mime_type": "image/png"
      }
    ]
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    json={
        "invoices": [
            {
                "name": "invoice-1001.png",
                "type": "Invoice Receipt",
                "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
                "mime_type": "image/png",
            },
        ],
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "invoices": [
    {
      "name": "invoice-1001.png",
      "type": "Invoice Receipt",
      "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
      "mime_type": "image/png"
    }
  ]
}
BODY;

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

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

echo $response;
```

## Responses

### 200 — The files were attached. Note the capital `I` in `Invoices`: the list call returns `invoices`. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |
| `Invoices` | array | The files just attached. |
| `Invoices[].name` | string | File name, as uploaded. |
| `Invoices[].mime_type` | string | The file's MIME type, e.g. `application/pdf`. |
| `Invoices[].type` | string | The file type. |
| `Invoices[].url` | string | Link to the file. |
| `Invoices[].id` | string | The file ID (`INV…`). Use it as `invoice_guid` to replace or delete the file. |

```json
{
  "status_code": 0,
  "session": "FhT3aXe7",
  "Invoices": [
    {
      "name": "invoice-1001.png",
      "mime_type": "image/png",
      "type": "Invoice Receipt",
      "url": "https://reparser2.paymeservice.com/external/files/3e8ce1bb-c6ff-4e05-94df-f24f30928180",
      "id": "INV17000-000000AA-EXAMPLE1-FILE0001"
    }
  ]
}
```

### 400 — Bad Request (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "PayMe-Merchant-Key",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```

### 422 — Unprocessable Entity (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "The invoices.0.base64 field is required.",
  "status_additional_info": "The invoices.0.base64 field is required.",
  "status_error_code": 20,
  "session": "FhT3aXe7"
}
```

### 500 — Internal Server Error (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```

- [Replace a contract file](https://docs.payme.io/b2b-payments/contracts/put-contracts-files): PUT /payment-contracts/{payment_contract_guid}/invoices/{invoice_guid} — Replace a contract file

# Replace a contract file

- Sandbox: `PUT https://sandbox.payme.io/api/payment-contracts/{payment_contract_guid}/invoices/{invoice_guid}`
- Production: `PUT https://live.payme.io/api/payment-contracts/{payment_contract_guid}/invoices/{invoice_guid}`

## Credentials

- Header `PayMe-Merchant-Key` (required): Your `seller_payme_id` (MPL). You must be the seller that uploaded the file.

Replaces the content of a file you uploaded to a contract. The file keeps its `id` and its `type`: send the `type` it already has (error `388` otherwise). Only the seller who uploaded the file can replace it. Send JSON with `Content-Type: application/json` and your MPL in the `PayMe-Merchant-Key` header.

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`400` | `251` | Seller was not found | The `PayMe-Merchant-Key` header is missing. `status_additional_info` is the header name. 
`400` | `385` | Action not allowed - please contact Customer Support | This seller is neither side of the contract. `status_additional_info` is the seller key. 
`400` | `385` | Action not allowed - please contact Customer Support | This seller may not change this file. 
`400` | `388` | File type has to be the same | The new `type` differs from the file's type. 
`400` | `757` | Invoice not found | The contract has no file with that ID. 
`422` | `20` | (a validation message) | `type`, `base64` or `mime_type` is missing. `status_additional_info` lists what failed. 
`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. 
`500` | `380` | Payment contract not found | No contract has this GUID. `status_additional_info` is the GUID. 
`500` | `900` | Please provide all required information in JSON format. Make sure to include 'Content-Type: application/json' header | The request is not JSON. 
`500` | `901` | Please verify that the JSON provided is valid | The JSON body is empty or invalid. 



## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | Your `seller_payme_id` (MPL). You must be the seller that uploaded the file. |
| `payment_contract_guid` | path | string | yes | The contract's `guid`, as returned when the contract was created, e.g. `CONT1700-000000AA-EXAMPLE1-CONT0001`. It already starts with `CONT`; don't add another prefix. |
| `invoice_guid` | path | string | yes | The file's `id` (`INV…`), as returned by [Upload contract files](/b2b-payments/contracts/post-contracts-files) or [List contract files](/b2b-payments/contracts/get-contracts-files). |

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no | New file name. Default: the current name. |
| `type` | string | yes | The file's current type. A different type returns error `388`. |
| `base64` | string | yes | The new file content, Base64-encoded. |
| `mime_type` | string | yes | The new file's MIME type, e.g. `application/pdf` or `image/png`. |

### Request example

```json
{
  "name": "invoice-1001.png",
  "type": "Invoice Receipt",
  "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
  "mime_type": "image/png"
}
```

## Code samples

### curl

```bash
curl -X PUT 'https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices/<invoice_guid>' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  --data-raw '{
  "name": "invoice-1001.png",
  "type": "Invoice Receipt",
  "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
  "mime_type": "image/png"
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices/<invoice_guid>", {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
  body: JSON.stringify({
    "name": "invoice-1001.png",
    "type": "Invoice Receipt",
    "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
    "mime_type": "image/png"
  }),
});

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

### Python

```python
import requests

response = requests.put(
    "https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices/<invoice_guid>",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    json={
        "name": "invoice-1001.png",
        "type": "Invoice Receipt",
        "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
        "mime_type": "image/png",
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "name": "invoice-1001.png",
  "type": "Invoice Receipt",
  "base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAARdQTFRFAAAAAAAAAAAAAAAAAQEBDAwMHBwcHx8fCwsLAwMDGRkZHh4eBAQEICAgtra2vb29pKSksLCwODg4FBQUh4eHtLS0m5ubISEh3NzciIiIERERwsLCnp6eAgICjIyMwMDAJycnDg4OBQUFEBAQ0NDQe3t7ycnJeXl5KCgo3d3daWlpCQkJDw8PzMzMmpqarKysyMjIOjo6kZGR9/f3sbGxnZ2dPDw8z8/Pfn5+FxcXjo6OsrKybm5u5ubmExMTBgYG1NTUiYmJCgoKTk5O39/fbGxs7OzsVFRUGhoa2tra9PT00dHRMTExzs7OhoaGhYWFLCwsIyMjuLi4xcXFUlJSRUVFvr6+2dnZoaGhFhYWBwcHFRUV////p5PkYgAAAAN0Uk5Tnvn4e+Nx/gAAAAFiS0dEXOrYAJcAAAAJcEhZcwAAAEgAAABIAEbJaz4AAACnSURBVBjTY2BgZEYCjAwMTMwogImBGQ0ABVhY2dg5gExOLm4esAAvH7+AoBCzsIiomDhYgEtCUkpaRlZOXkFRCSygrKIqrqauoamlqA0xQ0dXT9/A0MjYxNQMIqBsbmFpZW1ja2hnDxGwc3B0cnZxdXNnZmEBC3h4esmJefv4uvj5B4AFAoP0zINDmEPDwiMiwQJR0UrROkDFHNFREDPQnI7hOXTvAwCtbBUc7QjTawAAACV0RVh0ZGF0ZTpjcmVhdGUAMjAxOS0wMS0yMFQwNjo1NTozNiswMDowMA0Ih5IAAAAldEVYdGRhdGU6bW9kaWZ5ADIwMTktMDEtMjBUMDY6NTU6MzYrMDA6MDB8VT8uAAAARnRFWHRzb2Z0d2FyZQBJbWFnZU1hZ2ljayA2LjcuOC05IDIwMTQtMDUtMTIgUTE2IGh0dHA6Ly93d3cuaW1hZ2VtYWdpY2sub3Jn3IbtAAAAABh0RVh0VGh1bWI6OkRvY3VtZW50OjpQYWdlcwAxp/+7LwAAABh0RVh0VGh1bWI6OkltYWdlOjpoZWlnaHQAMTkyDwByhQAAABd0RVh0VGh1bWI6OkltYWdlOjpXaWR0aAAxOTLTrCEIAAAAGXRFWHRUaHVtYjo6TWltZXR5cGUAaW1hZ2UvcG5nP7JWTgAAABd0RVh0VGh1bWI6Ok1UaW1lADE1NDc5NjczMzaP/6esAAAAD3RFWHRUaHVtYjo6U2l6ZQAwQkKUoj7sAAAAVnRFWHRUaHVtYjo6VVJJAGZpbGU6Ly8vbW50bG9nL2Zhdmljb25zLzIwMTktMDEtMjAvMTVjOGNmYTk5NjBmYmJjOWUyY2NjNGI4MTY2YTI3NTQuaWNvLnBuZ0jyrXwAAAAASUVORK5CYII=",
  "mime_type": "image/png"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices/<invoice_guid>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

echo $response;
```

## Responses

### 200 — The file was replaced. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |

```json
{
  "status_code": 0,
  "session": "FhT3aXe7"
}
```

### 400 — Bad Request (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "PayMe-Merchant-Key",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```

### 422 — Unprocessable Entity (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "The base64 field is required.",
  "status_additional_info": "The base64 field is required.",
  "status_error_code": 20,
  "session": "FhT3aXe7"
}
```

### 500 — Internal Server Error (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```

- [Delete a contract file](https://docs.payme.io/b2b-payments/contracts/delete-contracts-files): DELETE /payment-contracts/{payment_contract_guid}/invoices/{invoice_guid} — Delete a contract file

# Delete a contract file

- Sandbox: `DELETE https://sandbox.payme.io/api/payment-contracts/{payment_contract_guid}/invoices/{invoice_guid}`
- Production: `DELETE https://live.payme.io/api/payment-contracts/{payment_contract_guid}/invoices/{invoice_guid}`

## Credentials

- Header `PayMe-Merchant-Key` (required): Your `seller_payme_id` (MPL). You must be the seller that uploaded the file.

Deletes a file you uploaded to a contract. Only the seller who uploaded the file can delete it (error `385`).

Send `Content-Type: application/json` and a JSON body that isn't empty, for example `{"confirm": true}`. A DELETE without a JSON body fails with error `900` or `901`.

If the contract has no file with this `invoice_guid`, the call returns success (`status_code` `0`) and deletes nothing.

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`400` | `251` | Seller was not found | The `PayMe-Merchant-Key` header is missing. `status_additional_info` is the header name. 
`400` | `385` | Action not allowed - please contact Customer Support | This seller is neither side of the contract. `status_additional_info` is the seller key. 
`400` | `385` | Action not allowed - please contact Customer Support | This seller may not delete this file. 
`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. 
`500` | `380` | Payment contract not found | No contract has this GUID. `status_additional_info` is the GUID. 
`500` | `900` | Please provide all required information in JSON format. Make sure to include 'Content-Type: application/json' header | The request is not JSON. 
`500` | `901` | Please verify that the JSON provided is valid | The JSON body is empty or invalid. 



## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `PayMe-Merchant-Key` | header | string | yes | Your `seller_payme_id` (MPL). You must be the seller that uploaded the file. |
| `payment_contract_guid` | path | string | yes | The contract's `guid`, as returned when the contract was created, e.g. `CONT1700-000000AA-EXAMPLE1-CONT0001`. It already starts with `CONT`; don't add another prefix. |
| `invoice_guid` | path | string | yes | The file's `id` (`INV…`), as returned by [Upload contract files](/b2b-payments/contracts/post-contracts-files) or [List contract files](/b2b-payments/contracts/get-contracts-files). |

## Request body

Content type: `application/json`

Required: any JSON object that isn't empty, e.g. `{"confirm": true}`. PayMe doesn't read its content.

### Request example

```json
{
  "confirm": true
}
```

## Code samples

### curl

```bash
curl -X DELETE 'https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices/<invoice_guid>' \
  -H 'Content-Type: application/json' \
  -H 'PayMe-Merchant-Key: <PayMe-Merchant-Key>' \
  --data-raw '{
  "confirm": true
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices/<invoice_guid>", {
  method: "DELETE",
  headers: {
    "Content-Type": "application/json",
    "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
  },
  body: JSON.stringify({
    "confirm": true
  }),
});

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

### Python

```python
import requests

response = requests.delete(
    "https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices/<invoice_guid>",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
    json={
        "confirm": True,
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "confirm": true
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/payment-contracts/<payment_contract_guid>/invoices/<invoice_guid>');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'DELETE',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'PayMe-Merchant-Key: <PayMe-Merchant-Key>',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

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

echo $response;
```

## Responses

### 200 — The file was deleted, or the contract has no file with this `invoice_guid`. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |

```json
{
  "status_code": 0,
  "session": "FhT3aXe7"
}
```

### 400 — Bad Request (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "PayMe-Merchant-Key",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```

### 500 — Internal Server Error (error)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | number | Status code 1 (for failure) |
| `status_error_details` | string | What caused the error |
| `status_additional_info` | string | The parameters related to the error |
| `status_error_code` | number | Status error code |
| `session` | string | PayMe session ID. |

```json
{
  "status_code": 1,
  "status_error_details": "Seller was not found",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 251,
  "session": "FhT3aXe7"
}
```

- [List previous recipients](https://docs.payme.io/b2b-payments/contracts/get-recipient): GET /payment-contracts/recipients — List previous recipients

# List previous recipients

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

## Credentials

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

Lists the recipients of this seller's earlier contracts that are registered PayMe sellers, so you can create a new contract for them without typing their details again. Authenticate with the initiator's MPL in the `PayMe-Merchant-Key` header.

- PayMe returns one entry per recipient seller account linked to any of your contracts, whatever the contract's status, as long as that account is active.
- `name`, `phone`, `email` and `business_code` are the details you sent on your most recent contract with that recipient that included an `email`. They are not the recipient's registered details. A recipient you never sent an `email` for isn't listed.
- To pay a listed recipient, send its `seller_payme_id_checksum` as `recipient.payme_id` in [Create a payment contract](/b2b-payments/contracts/post-user), with no other `recipient` field.
- The result isn't paginated: `page` is always `1`, and `items_per_page` and `items_total` both equal the number of items.

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`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 initiator's `seller_payme_id` (MPL). |

## Code samples

### curl

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

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/payment-contracts/recipients", {
  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/recipients",
    headers={
        "PayMe-Merchant-Key": "<PayMe-Merchant-Key>",
    },
)

print(response.text)
```

### PHP

```php
<?php

$ch = curl_init('https://sandbox.payme.io/api/payment-contracts/recipients');
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 — Your previous recipients. An empty `items` array if there are none. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` on success. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |
| `page` | integer | Always `1`. |
| `items_per_page` | integer | The number of items. |
| `items_total` | integer | The number of items. |
| `items` | array | One entry per recipient seller account. |
| `items[].name` | string | The recipient name you sent. `null` if you didn't send one. |
| `items[].phone` | string | The phone number you sent. `null` if you didn't send one. |
| `items[].business_code` | integer | The business number you sent, as sent: a number, or a string if you sent a string. `null` if you didn't send one. |
| `items[].email` | string | The email address you sent. |
| `items[].seller_payme_id_checksum` | string | An encrypted reference to the recipient's seller account. Send it as `recipient.payme_id` when you create a contract. Treat it as opaque: it differs on every call, and every value works. |

```json
{
  "status_code": 0,
  "session": "FhT3aXe7",
  "page": 1,
  "items_per_page": 2,
  "items_total": 2,
  "items": [
    {
      "name": "Example Supplies Ltd",
      "phone": "0500000001",
      "business_code": 515555555,
      "email": "supplier@example.com",
      "seller_payme_id_checksum": "eyJpdiI6IkV4YW1wbGVJVjAwMDAwMDAwMDAwPT0iLCJ2YWx1ZSI6IkV4YW1wbGUxIn0="
    },
    {
      "name": null,
      "phone": null,
      "business_code": 516666666,
      "email": "billing@example.com",
      "seller_payme_id_checksum": "eyJpdiI6IkV4YW1wbGVJVjExMTExMTExMTExPT0iLCJ2YWx1ZSI6IkV4YW1wbGUyIn0="
    }
  ]
}
```

### 500 — A missing, unknown or inactive seller key. (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"
}
```


## Wallets

- [Transfer funds between sellers](https://docs.payme.io/b2b-payments/wallets/post-generate-transfer): POST /sales — Transfer funds between sellers

# Transfer funds between sellers

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

## Credentials

- Request body field `seller_payme_id` (required): The MPL of the seller that receives the funds. It also authenticates the call.
- Request body field `payme_client_key` (optional): Partners: your client key. Both sellers must belong to this partner.

Moves funds from one seller's PayMe balance (`payment.origin_seller_id`) to another seller's (`seller_payme_id`). PayMe records the transfer as a completed sale on the receiving seller, with `sale_payment_method` `funds-transfer`. Amounts are in minor units (`1000` = 10.00).

- **Authentication:** `seller_payme_id`, the receiving seller's MPL, authenticates the call. Partners also send `payme_client_key`.
- **Same partner, different accounts:** both sellers must belong to the same partner, and they must be two different accounts (error `20`).
- **Services:** the origin seller needs the `funds-transfer` service and the receiving seller the `funds-transfer Destination` service (error `720`). To enable them, ask <partners@payme.io> and give both MPLs.
- **Validated origin:** the origin seller's account must be validated (error `109`).
- **A failed transfer still returns HTTP `200`**, with `status_code` `1`, `payme_status` `error` and the reason in `status_error_code` and `status_error_details`. Check `status_code`, not only the HTTP status.

### Errors

HTTP status | Error code | Message | When
---|---|---|---
`500` | `1` | Required parameter is missing | `seller_payme_id` or `payment.origin_seller_id` is missing. `status_additional_info` names it.
`400` | `353` | Invalid description | `product_name` is missing.
`500` | `352` | Invalid price, out of min-max bounds | `sale_price` is missing or not a number.
`400` | `252` | Currency is not allowed for this seller | `currency` isn't enabled for the receiving seller.
`500` | `20` | Validation error | The two sellers are the same account (`Funds must be transferred between different accounts`), or they belong to different partners (`Merchant-Seller inconsistency`).
`500` | `720` | The service was not activated | A seller lacks the funds-transfer service. `status_additional_info` is `funds-transfer` (origin seller) or `funds-transfer Destination` (receiving seller).
`400` | `109` | Seller not validated | The origin seller's account isn't validated.
`500` | `251` | Seller was not found | A seller key is unknown.

## Parameters

This endpoint takes no path, query or header parameters.

## Request body

Content type: `application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `seller_payme_id` | string | yes | The MPL of the seller that receives the funds. It also authenticates the call. |
| `payme_client_key` | string | no | Partners: your client key. Both sellers must belong to this partner. |
| `sale_price` | integer | yes | The amount to transfer, in minor units (`1000` = 10.00). |
| `currency` | string | yes | ISO 4217 currency code, e.g. `ILS`. It must be enabled for the receiving seller (error `252`). |
| `product_name` | string | yes | What the transfer is for. It becomes the sale's description (error `353` if missing). |
| `payment` | object | yes | The transfer details. |
| `payment.method` | string | yes | Must be `funds-transfer`. Without it, PayMe doesn't make a transfer. |
| `payment.origin_seller_id` | string | yes | The MPL of the seller whose balance is debited. It must differ from `seller_payme_id`. |

### Request example

```json
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-7654321",
  "sale_price": 15000,
  "currency": "ILS",
  "product_name": "Monthly settlement",
  "payment": {
    "method": "funds-transfer",
    "origin_seller_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567"
  }
}
```

## Code samples

### curl

```bash
curl -X POST 'https://sandbox.payme.io/api/sales' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-7654321",
  "sale_price": 15000,
  "currency": "ILS",
  "product_name": "Monthly settlement",
  "payment": {
    "method": "funds-transfer",
    "origin_seller_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567"
  }
}'
```

### Node.js

```javascript
const response = await fetch("https://sandbox.payme.io/api/sales", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-7654321",
    "sale_price": 15000,
    "currency": "ILS",
    "product_name": "Monthly settlement",
    "payment": {
      "method": "funds-transfer",
      "origin_seller_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567"
    }
  }),
});

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

### Python

```python
import requests

response = requests.post(
    "https://sandbox.payme.io/api/sales",
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-7654321",
        "sale_price": 15000,
        "currency": "ILS",
        "product_name": "Monthly settlement",
        "payment": {
            "method": "funds-transfer",
            "origin_seller_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        },
    },
)

print(response.text)
```

### PHP

```php
<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-7654321",
  "sale_price": 15000,
  "currency": "ILS",
  "product_name": "Monthly settlement",
  "payment": {
    "method": "funds-transfer",
    "origin_seller_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567"
  }
}
BODY;

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

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

echo $response;
```

## Responses

### 200 — The transfer result, as a sale on the receiving seller. The response also carries the other fields of a sale response, such as `buyer_*`, `payme_transaction_card_brand` and `installments`. They describe card sales; don't rely on them for a transfer. (success)

| Field | Type | Description |
| --- | --- | --- |
| `status_code` | integer | `0` – the transfer succeeded; `1` – it failed (see `status_error_code`). |
| `payme_status` | string | `success` or `error`. |
| `status_error_code` | integer | `0` on success; the error code otherwise. |
| `status_error_details` | string | The error message. Only when the transfer failed. |
| `payme_sale_id` | string | The sale created on the receiving seller (`SALE…`). |
| `payme_sale_code` | integer | The sale's numeric ID. |
| `sale_created` | string | When the sale was created, `YYYY-MM-DD HH:MM:SS`. |
| `sale_status` | string | `completed` when the transfer succeeded. |
| `payme_sale_status` | string | Same as `sale_status`. |
| `sale_payment_method` | string | `funds-transfer`. |
| `currency` | string | The currency, as sent. |
| `price` | integer | The amount transferred, in minor units. |
| `sale_description` | string | Your `product_name`. |
| `payme_signature` | string | The sale signature. See [Verifying a callback](/payments/getting-started/callbacks#verifying-a-callback-payme_signature). |
| `payme_transaction_id` | string | The transaction on the receiving seller (`TRAN…`). |
| `payme_transaction_total` | integer | The transaction amount, in minor units. |
| `sale_paid_date` | string | When the transfer ran, `YYYY-MM-DD HH:MM:SS`. |
| `sale_release_date` | string | The release date of the funds to the receiving seller, `YYYY-MM-DD HH:MM:SS`. |
| `session` | string | PayMe session ID. Quote it when you contact PayMe support. |

```json
{
  "status_code": 0,
  "payme_status": "success",
  "status_error_code": 0,
  "payme_sale_id": "SALE1700-000000AA-EXAMPLE1-SALE0001",
  "payme_sale_code": 8965519,
  "sale_created": "2026-11-09 16:28:08",
  "sale_status": "completed",
  "payme_sale_status": "completed",
  "sale_payment_method": "funds-transfer",
  "currency": "ILS",
  "price": 15000,
  "sale_description": "Monthly settlement",
  "payme_signature": "9c1d6f0e2b7a4c3d8e5f6a7b8c9d0e1f",
  "payme_transaction_id": "TRAN1700-000000AA-EXAMPLE1-TXN00001",
  "payme_transaction_total": 15000,
  "sale_paid_date": "2026-11-09 16:28:08",
  "sale_release_date": "2026-11-09 16:28:09",
  "session": "FhT3aXe7"
}
```

### 400 — A missing `product_name`, a currency the receiving seller can't use, or an origin seller that isn't validated. (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": "Invalid description",
  "status_additional_info": "product_name",
  "status_error_code": 353,
  "session": "FhT3aXe7"
}
```

### 500 — A missing field or key, sellers that can't transfer to each other, or a service that isn't enabled. (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": "The service was not activated",
  "status_additional_info": "funds-transfer",
  "status_error_code": 720,
  "session": "FhT3aXe7"
}
```