# Subscriptions

Reference pages: [Subscriptions](/payments/subscriptions), [Generate](/payments/subscriptions/post-generate-subscription), [List Subscriptions](/payments/query-apis/post-get-subscriptions), [Subscription Statuses](/payments/codes-statuses/subscription-statuses), [Recurring Payments](/payments/saved-cards-recurring).

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](/agents/steps/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](/payments/codes-statuses/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](/payments/saved-cards-recurring).

Pause is reversible, and cancel is final, so confirm with the person before cancelling. The actions are [Cancel](/payments/subscriptions/postcancel-subscription), [Pause](/payments/subscriptions/post-pause-subscription), [Resume](/payments/subscriptions/patch-subscriptions-sub-payme-id-resume) and [Update Price](/payments/subscriptions/patch-subscriptions-sub-id-set-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](/integration-kit/index.json) pin these rules.