Contracts

How B2B payment contracts work: adding a card or direct-debit authorization to the payer's account, creating a contract and choosing its payment method, authentication, the contract lifecycle, callbacks and error codes.

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.

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.

Before you start

1. The initiator needs a PayMe seller account and its seller_payme_id (MPL). Partners create one with 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.

Add a card or direct-debit authorization

Tokenize the card or the bank account with generate-sale and sale_type token. The callback carries a buyer_key that identifies this payment method. Save it.

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.
• 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. Attached cards are listed in seller_credit_cards of get-sellers.

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 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 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 for the keys themselves.

To move funds between two sellers' balances right away, without a contract, use Transfer funds between sellers.

Contract lifecycle

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

Verify payme_signature. Contracts use a shorter formula than sale callbacks: 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:

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:

Guides

• Run a B2B payment contract end to end: 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.

Endpoints

• Create a payment contract: POST /payment-contracts
• List payment contracts: GET /payment-contracts
• List contract files: GET /payment-contracts/{payment_contract_guid}/invoices
• Upload contract files: POST /payment-contracts/{payment_contract_guid}/invoices
• Replace a contract file: PUT /payment-contracts/{payment_contract_guid}/invoices/{invoice_guid}
• Delete a contract file: DELETE /payment-contracts/{payment_contract_guid}/invoices/{invoice_guid}
• List previous recipients: GET /payment-contracts/recipients