Subscriptions

Reference pages: Subscriptions, Generate, List Subscriptions, Subscription Statuses, Recurring Payments.

Both roles follow the same rules. A partner works with the seller's MPL. A direct seller uses its own.

Creating

• sub_price is one iteration, in minor units. sub_start_date is dd/mm/yyyy. A monthly subscription must start on day 1 to 28, so when defaulting to today, move the 29th to 31st to the 1st of the next month.
• Without a token, the response has sub_url, a hosted page where the buyer enters a card. The status stays initial until they pay.
• With a buyer_key, no page is needed. The token must be permanent: see Saved Cards.
• PayMe runs the schedule. There's no "charge the next iteration" call, so don't build one (SAL-03).
• Never use pay-subscription with raw card fields unless you are PCI DSS certified (TOK-03), and treat sub_payme_id as sensitive (SEC-05).

Callbacks are a trigger

Subscription callbacks carry no signature (CB-04). A signature appears only on the subscription return URL.

1. Find the subscription by the sub_payme_id you stored. No match: record it and change nothing.
2. Call get-subscriptions with sub_payme_id and the seller's MPL as seller_payme_id, in the JSON body (TRN-05). A direct seller's MPL alone returned that seller's subscriptions in the sandbox.
3. Discard the answer and alert if any row names another seller. Keep the row with your ID, and check its currency.
4. Normalise sub_status: it is a number from the query and a string on a callback. Record an unknown value, and act on nothing.
5. Answer below 400 (CB-06).

Grant service from PayMe's numbers

Grant one period for each increase in sub_iterations_completed you haven't already granted, not per notification. That stays right however many callbacks arrive, in whatever order, and when one is lost. An absent value is unknown, never zero. Re-check active subscriptions on a schedule, for example daily and the day after each expected charge.

Statuses

Use Subscription Statuses. The one to get right is 7, failed and pending automatic retry: don't chase the buyer about it, because PayMe will try again. Retries are described on Recurring Payments.

Pause is reversible, and cancel is final, so confirm with the person before cancelling. The actions are Cancel, Pause, Resume and Update Price. Resume and Update Price use a different request shape from the rest: follow their reference pages.

reference/subscription-verification.ts and test-vectors/subscription-verification.json in the integration kit pin these rules.