# Callback types reference

Building with an AI agent? Start at https://docs.payme.io/agents.md

## Related

- [Callbacks](/payments/getting-started/callbacks)
- [Understand the sale lifecycle](/payments/codes-statuses/sale-lifecycle)
- [List sales](/payments/query-apis/post-get-sales)
- [List subscriptions](/payments/query-apis/post-get-subscriptions)
- [List sellers](/payments/query-apis/post-get-sellers)
- [List withdrawals](/payments/query-apis/post-get-withdrawals)
- [Withdrawals](/marketplaces-and-platforms/fees-and-payouts/withdrawals)
- [Take in-person payments with a POS device](/accepting-payments/checkout-and-in-person/point-of-sale)
- [Contracts](/b2b-payments/contracts)

This page lists every `notify_type` PayMe sends to your servers: who receives it, when it fires, its key fields, and whether it is signed. How callbacks are delivered (a form-encoded `POST`, the 5-second timeout, retries, duplicates and the signature formula) is on [Callbacks](/payments/getting-started/callbacks).

## How to read this page

**Where it goes.** Each group below names its destination:

| Destination | What it is |
|---|---|
| Sale callback URL | The sale's `sale_callback_url`. If you left it out, your partner's default callback URL. If your partner also has a separate sale callback URL, that URL gets a copy; PayMe sends one delivery per host. |
| Subscription callback URL | The subscription's `sub_callback_url`. If you left it out, your partner's callback URL at the time the subscription was created. |
| Partner callback URL | Your partner's callback URL, set by PayMe. If your partner account has none, these callbacks aren't sent. |
| Contract callback URL | The B2B payment contract's `callback_url`. |

**Signed.** A signed callback carries `payme_signature`, which a partner verifies with the formula on [Callbacks](/payments/getting-started/callbacks#verifying-a-callback-payme_signature). For an unsigned callback, re-read the object with its query call before you act on it.

**Body.** Every callback carries `notify_type`. Fields with no value are left out.



## Sales

Sent to the sale callback URL. Signed, except `sale-create`. The body has the fields of the [sale callback payload](/payments/getting-started/callbacks#sale-callback-payload), plus the key fields below.

| `notify_type` | When it fires | Key fields |
|---|---|---|
| `sale-create` | Right after `generate-sale`, only when you sent `sale_send_creation_callback: true` | `sale_url`. No payment fields yet, and no `payme_signature` |
| `sale-complete` | The sale was paid, or an authorization was captured. A token sale (`sale_type: token`) sends it when the card is saved | `sale_status` `completed`. `buyer_key` and `buyer_status` when the card was saved. `is_token_sale` `1` on a token sale. `sale_invoice_url` when the invoicing service issued a document |
| `sale-authorized` | An `authorize` sale was authorized | `sale_status` `authorized`. `buyer_key` when the card was saved |
| `sale-failure` | A payment or capture attempt failed. Sent once per failed attempt | `status_code` `1`, `payme_status` `error`, `status_error_code`, `status_error_details`. Each attempt has its own `payme_transaction_id` |
| `refund` | A refund, a partial refund, or a full or partial void of an authorization succeeded | `payme_transaction_total` (the amount of this refund or void), `sale_refund_buffer` (the amount still refundable), `sale_status`, `refunded_from_creditcard`. `payme_transaction_id` and `payme_signature` refer to the refund transaction |
| `sale-chargeback` | The card issuer charged the payment back, in full or in part | `sale_status` `chargeback` or `partial-chargeback`. `inquiry_number` and `inquiry_code` (the references of the chargeback inquiry), `card_last_four_digits`, `vas_3ds_exists` (`1` when the seller has the 3D Secure service) |
| `sale-chargeback-refund` | A chargeback was reversed in the seller's favor | `sale_status`: `completed` once every chargeback on the sale is reversed |
| `sale-paid` | Israeli direct debit: the debit was submitted to the bank | Take the token (`buyer_key`) from `sale-il-direct-debit-update` or `get-sales`, not from this callback |
| `sale-il-direct-debit-update` | Israeli direct debit: the bank authorization of a direct-debit token changed. Sent right after the `sale-complete` or `sale-failure` for that token | `authorization_status`, `authorization_error_code`, `buyer_key`, `buyer_name`. The `authorization_status` values are on [Errors](/payments/getting-started/errors#israeli-direct-debit) |

How each callback moves the sale's status is on [Understand the sale lifecycle](/payments/codes-statuses/sale-lifecycle).



## Subscriptions

Sent to the subscription callback URL. **Not signed**: re-read the subscription with [`get-subscriptions`](/payments/query-apis/post-get-subscriptions) before you act. The body is the [subscription callback payload](/payments/getting-started/callbacks#subscription-callback-payload): `sub_payme_id`, `sub_status`, `sub_price`, the iteration counters and the buyer fields, never the `buyer_key`.

| `notify_type` | When it fires |
|---|---|
| `sub-create` | The subscription was created |
| `sub-active` | The subscription became active |
| `sub-iteration-success` | A charge succeeded: the first, a regular one, or one after a retry. Adds `payme_sale_id` and `payme_sale_code` of the charge's sale |
| `sub-iteration-skipped` | A billing iteration was skipped |
| `sub-failure` | A charge failed. Carries `sub_error_text` |
| `sub-pause` | The subscription was paused |
| `sub-cancel` | The subscription was canceled, by hand or after the last failed retry |
| `sub-complete` | The subscription completed |

Each charge also creates a sale, which sends its own `sale-complete` or `sale-failure`. Retry rules and statuses are on [Callbacks](/payments/getting-started/callbacks#subscriptions) and [Recurring Payments](/payments/saved-cards-recurring).



## Sellers

For partners. Sent to the partner callback URL. **Not signed**: re-read the seller with [`get-sellers`](/payments/query-apis/post-get-sellers) before you act. The body has all the `seller_*` and `fee_*` fields of the [seller callback payload](/payments/getting-started/callbacks#seller-callback-payload).

| `notify_type` | When it fires | Key fields |
|---|---|---|
| `seller-create` | A seller was created under your partner account | `seller_public_key`: the seller's public key, for Hosted Fields and other browser calls, with `uuid` (the key itself), `description` and `is_active` |
| `seller-update` | A seller's details or status changed: for example through `update-seller`, in the dashboard, or when PayMe approves the seller or withdraws the approval | `seller_active`, `seller_approved` |
| `seller-approve` | PayMe approved the seller | `seller_approved` `1`, `partner_name` |
| `point-of-sale-action-pair-update` | A POS device was paired with the seller | `pos_id` (the device ID you use with `pos` payments), `pos_name` |
| `point-of-sale-action-authenticate-update` | The paired POS device was authenticated with its 6-digit code and is now active | `pos_id`, `pos_name` |

The POS flow is on [Point of sale](/accepting-payments/checkout-and-in-person/point-of-sale).



## Seller balance

For partners. Sent to the partner callback URL. **Not signed**: re-read with [`get-withdrawals`](/payments/query-apis/post-get-withdrawals) or [`get-transactions`](/payments/query-apis/post-get-transactions) before you act. Both use the same `tran_*` fields:

| `notify_type` | When it fires | Key fields |
|---|---|---|
| `withdrawal-complete` | A withdrawal from the seller's balance was recorded. It is sent before the bank transfer arrives | `tran_payme_code` (the same number as `withdrawal_payme_code` in `get-withdrawals`), `tran_total`, `tran_currency`, `tran_type` `40`, `tran_created`. The full table is on [Withdrawals](/marketplaces-and-platforms/fees-and-payouts/withdrawals#callback) |
| `charge-complete` | PayMe debited or credited the seller's balance with a separate charge, for example a chargeback fee or a manual adjustment | `tran_total` in minor units: positive when PayMe takes money from the balance, negative when it credits it. `tran_currency`, `tran_description` (free text), `tran_type` (PayMe's charge type code), `tran_created`, `sale_payme_code` (the related sale, when there is one) |

Both also carry `seller_payme_id`, `seller_id`, `payme_status` `success`, `status_code` `0` and `status_error_code` `0`.



## B2B payment contracts

Sent to the contract callback URL whenever a contract's status changes: nine `payment-contract-*` types, from `payment-contract-created` to `payment-contract-payment-completed`. They are signed with a shorter formula than sale callbacks. The types and the signature are on [B2B payment contracts](/b2b-payments/contracts#callbacks).



## Types you won't receive

PayMe also uses other `notify_type` values for its own systems. They go to PayMe's internal endpoints, never to your callback URLs, so don't wait for a type that isn't on this page.