Callbacks

Related

• Callback types reference
• Sale Statuses
• List sales
• Idempotency and Retries
• Quickstart

A callback (PayMe also calls it an "IPN") is a request PayMe's server sends to yours when something happens to a sale, a subscription or a seller.

In short: reply quickly with HTTP 200, expect repeats and out-of-order delivery, verify payme_signature, and confirm the sale's status and amount with POST /get-sales before you fulfil an order.

Format

• Method and encoding: POST with an x-www-form-urlencoded body — not JSON.
• Destination: the sale_callback_url you sent. If you omit it, PayMe uses your partner's default callback URL, if your partner has one; a seller has no dashboard setting for it, so always send sale_callback_url (and sub_callback_url for subscriptions). One sale can notify two URLs: the sale's callback URL and the partner's sale callback URL (one delivery per host).
• The language field of the request sets the language of the callback.

Callback URL rules

• http:// and https:// are both accepted. Use HTTPS.
• Non-standard ports are allowed (for example :8443).
• Rejected, with error 21 for the whole call: localhost and other hosts without a dot, IP addresses in private or loopback ranges, all IPv6 addresses, and hosts whose top-level domain isn't letters only. Ports must be 2–5 digits.
• PayMe doesn't resolve the host, so a valid-looking name is accepted even if it doesn't exist. sale_return_url follows the same rules.

The callback is separate from the return URL redirect. The return URL is a browser GET that takes the buyer to your result page; the callback is server-to-server.

Sale notification types (notify_type)

Every notify_type PayMe sends, with when it fires and its key fields, is listed on Callback types reference.

• sale-failure is sent once per failed attempt, not once per sale. A buyer can retry on the payment page; each failure sends another sale-failure with a different payme_transaction_id. They stop once the sale completes. So failed isn't final: the sale can still move to completed, or authorized for a capture sale.
• Refund callbacks: payme_transaction_total is the amount of this refund, price is the original sale price, sale_refund_buffer is the amount still refundable, and payme_transaction_id / payme_signature refer to the refund transaction.

After a partial refund sale_status is partial-refund. A sale fully refunded in parts stays partial-refund and never moves to refunded, so track the refunded total yourself.

Sale callback payload

Fields with no value are left out of the body.

Other callbacks

Subscriptions

Sent to sub_callback_url; if it is empty, to your partner's default callback URL (merchant_callback_url), if one is set. Subscription callbacks carry no payme_signature.

The payload includes sub_payme_id, sub_status, sub_price, iteration counters and buyer fields (card mask, name, email, phone and ID; never the buyer_key). The iteration counters count successful charges only. Each successful iteration also creates a sale, which sends its own sale-complete or sale-failure. Handlers must be idempotent: re-query get-subscriptions before acting. Charge retries (once a day, up to 7 attempts) are described on Recurring Payments.

sub_callback_url is sent on every successful charge while the subscription is active and on every failed attempt that leads to a retry.

Subscription callback payload

Israeli direct debit

• sale-paid when the debit is submitted. Take the token (buyer_key) from sale-il-direct-debit-update or get-sales, not from sale-paid.
• When the bank authorization status changes: sale-complete or sale-failure, then sale-il-direct-debit-update with authorization_status and authorization_error_code. The authorization_status values are listed on Errors (section "Israeli direct debit").

An Israeli direct-debit payment sends sale-paid when submitted, then sale-complete about 8 days later, or sale-failure if the bank returns the debit before that.

Sellers (partners)

Sent to the partner's callback URL with all seller_* and fee_* fields: seller-create (adds seller_public_key), seller-update, seller-approve. Related partner notifications: withdrawal-complete, charge-complete, and point-of-sale-action-* (for example after a POS device is paired).

Seller callback payload

Bank transfer

A bank transfer reaching PAID is reported with a callback.

There is no bank-transfer-specific notify_type: the standard sale callbacks apply (sale-complete when the transfer is paid, sale-failure otherwise).

B2B payment contracts

Documented with the B2B Payments API: Contracts: getting started → Callbacks.

Verifying a callback (payme_signature)

How it is computed

Partners, who hold payme_client_key, verify callbacks with this formula; a seller without a partner key re-queries the sale instead (see below).

payme_signature is the lowercase hexadecimal MD5 hash of four values joined with no separator, in this order:

1. payme_client_key (the partner key)
2. the client password issued together with the client key: the partner's merchant_password (called payme_merchant_secret in older PayMe documentation)
3. payme_transaction_id (from the payload)
4. payme_sale_id (from the payload)

It is a plain MD5 hash, not an HMAC.

The signature always uses your primary client key. If PayMe is moving you to a new client key, your API calls can already use the new key, but the signature stays on the primary key until PayMe completes the switch.

Worked example (fake values):

Joined string: demo_partner_KEY12345demoPassw0rdTRAN1700-000000AA-EXAMPLE1-TXN00001SALE1700-000000AA-EXAMPLE1-SALE0001

payme_signature = f8ffc5bb45fe6c3ad326c439f1a21c28

import hashlib, hmac

def payme_signature_ok(form, client_key, client_password):
    expected = hashlib.md5(
        (client_key + client_password
         + form["payme_transaction_id"] + form["payme_sale_id"]).encode()
    ).hexdigest()
    return hmac.compare_digest(expected, form.get("payme_signature", ""))

The client password is issued together with your partner credentials by PayMe Partners (partners@payme.io). A merchant that has no payme_client_key cannot compute the signature: verify the sale instead with POST /get-sales or POST /get-transactions, which is also the check PayMe support recommends.

Where the same signature appears

The same formula is used in sale callbacks, the return-URL redirect (including when payme_status=error), and the capture-sale and refund-sale responses. In each case payme_transaction_id is the transaction in that payload — the payment, the capture or the refund.

Exceptions:

• Seller callbacks and withdrawal-complete have no signature. Ignore the body and re-read with get-sellers or get-withdrawals.
• Subscription callbacks have no signature. The subscription return URL is signed: the MD5 of the client key, the client password, the URL's transaction_id (PayMe's transaction ID; this URL has no payme_transaction_id) and sub_payme_id.
• verify_only refunds return payme_signature: null.
• B2B payment contracts use a shorter formula: the MD5 of the client key, the client password and the contract's guid. See B2B Payments.

Confirm the sale before you fulfil

A valid signature tells you the callback refers to a real PayMe sale and transaction. Treat the status and amount in a callback as a notification, not as proof of payment.

Safe practice: before you fulfil an order, call POST /get-sales with sale_payme_id and check sale_status and sale_price against your order. POST /get-transactions works too, and shows each charge and refund as a row, which is why the AI Toolkit steps use it.

Find the order by the payme_sale_id you stored when you created the sale, and match it on your own order ID as well as the amount. Otherwise a real, cheap sale's ID could be replayed in a forged callback against an expensive order. If you confirm with get-transactions instead, send transaction_type: 40 for a sale that is authorized and not yet captured: the default query doesn't return it.

PayMe does not publish a fixed list of callback source addresses, so do not allow-list by IP. Authenticate callbacks by their signature and confirm the sale with get-sales.

Delivery, retries, duplicates and ordering

What counts as delivered

• Any status below 400 counts as delivered. The response body is ignored.
• Each attempt times out after 5 seconds. Reply 200 immediately and do the slow work (emails, fulfilment) afterwards.

Retries

• PayMe makes up to 3 attempts: the first, a retry about 30 seconds later, and a last retry about 60 seconds after that.
• A 4xx or 5xx response, a timeout, or a connection error triggers a retry.
• After the last attempt the callback is dropped. It cannot be replayed through the API.
• If your host keeps returning 5xx, 408 or 429 responses, timing out or refusing connections, PayMe pauses deliveries to that host for a short time. Callbacks during the pause are not delivered or retried.
• A pause is triggered by 5xx responses, 429, 408, timeouts and connection errors on your host; an ordinary 4xx (for example a signature or authentication rejection by your code) never causes one. It lifts by itself once your endpoint answers. You can't reset it yourself; if you need it cleared at once, contact PayMe support with the callback host. There is no test ping. Acknowledge first (cold starts included) and process in the background.
• Order is not guaranteed: act on notify_type and the sale status, not on the order of arrival.

Do not rely on callbacks alone. Reconcile with POST /get-sales.

Duplicates

The same callback can arrive more than once — typically when your endpoint processes it but replies after the 5-second timeout. There is no event ID. De-duplicate on notify_type + payme_sale_id + payme_transaction_id; each refund, capture and failed attempt has its own payme_transaction_id.

Ordering

Callbacks are not guaranteed to arrive in order: they are sent by parallel workers with retry delays, so a refund can arrive before a sale-complete that is still being retried, and there is no sequence number or event timestamp. Never let a later-arriving callback overwrite a final state you already recorded, and query the sale when in doubt.

Handling checklist

1. Parse the body as form data and reply 200 within 5 seconds.
2. If you are a partner, verify payme_signature (sale callbacks).
3. Ignore it if you already processed this notify_type + payme_sale_id + payme_transaction_id.
4. Before fulfilling, confirm sale_status and sale_price with POST /get-sales.
5. Run a periodic reconciliation with get-sales, because callbacks can be dropped after 3 attempts.