Callback types reference
Related
- Callbacks
- Understand the sale lifecycle
- List sales
- List subscriptions
- List sellers
- List withdrawals
- Withdrawals
- Take in-person payments with a POS device
- 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.
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. 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, 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 |
How each callback moves the sale's status is on Understand the sale lifecycle.
Subscriptions
Sent to the subscription callback URL. Not signed: re-read the subscription with get-subscriptions before you act. The body is the 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 and Recurring Payments.
Sellers
For partners. Sent to the partner callback URL. Not signed: re-read the seller with get-sellers before you act. The body has all the seller_* and fee_* fields of the 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.
Seller balance
For partners. Sent to the partner callback URL. Not signed: re-read with get-withdrawals or 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 |
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.
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.