Run a B2B payment contract end to end

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
• Create a payment contract
• List payment contracts
• List previous recipients
• Upload contract files
• List contract files
• Save a card (token sale)
• Attach a saved card to a seller
• List sellers
• Callbacks
• Callback types reference
• Transfer funds between sellers

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, 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.

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.method sets where the money comes from:

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 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.
3. Check that the card appears in seller_credit_cards of 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.

Step 3: Create the contract

Call POST /payment-contracts. This contract sends 5,000.00 by card on December 22:

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):

{
  "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.

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.
• 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.

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:

{
  "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:

• 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.
• 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 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.
• 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. 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 and recipient=true.

Read a contract

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

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, 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:

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:

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:

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.
• Only the seller that uploaded a file can replace it, with the same type (error 388), or delete 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:

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 and B2B payment contracts.

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, because a callback is dropped after its last attempt.