Subscriptions

Recurring payments with subscriptions: the lifecycle, statuses, pausing, template subscriptions, callbacks and iteration types.

A subscription charges a buyer on a fixed schedule. Each iteration is charged separately: unlike an installment sale, nothing is authorized up front. For 100.00 a month over 10 months, each month is charged 100.00, not 1,000.00 at once.

How charging, retries, callbacks and saved cards work in detail: Saved cards & recurring.

Endpoints

Lifecycle

  1. Create the subscription. It starts in status 1 (Initial) and returns sub_url, the hosted page where the buyer enters a card. Or send a permanent buyer_key to attach a saved card at once.
  2. When a card is attached, the status becomes 2 (Active) and PayMe sends sub-active.
  3. A background job charges each iteration when its date arrives; the first charge runs within about a minute after sub_start_date. Each successful charge creates a sale and sends sub-iteration-success.
  4. If the card check fails when the buyer pays, the status becomes 4 (Failed) and PayMe sends sub-failure. The subscription isn't canceled: the buyer can pay again.
  5. A failed scheduled charge moves the subscription to status 7 and is retried once a day, up to 7 attempts in total. A daily subscription, and the seventh consecutive failure, are canceled instead (status 5, sub-cancel).
  6. After the last iteration, the status becomes 6 (Completed) and PayMe sends sub-complete.

Pausing

While a subscription is paused (status 3), nothing is charged. Each iteration whose date passes is skipped: it counts in sub_iterations_skipped, reduces sub_iterations_left, and sends sub-iteration-skipped. Resuming doesn't charge skipped iterations and sends no callback. If every remaining iteration is skipped, the subscription becomes 6 (Completed) while still paused.

Automatic cancellation and blocked sellers

No charges run while the seller's account is blocked. PayMe cancels a subscription automatically after the last failed charge attempt. It also cancels the active subscriptions, and those waiting for a retry, of a seller whose account has been blocked for more than 30 days.

Template subscriptions

A template (sub_type 10), also called a "Multilink subscription", is one shareable payment link for many buyers. You can post it on a social network, for example. Each buyer who pays it gets their own subscription with its own sub_payme_id (sub_type 2). Send the number 10; the text template is rejected.

sub_type Meaning
1 Regular subscription (the default).
2 A subscription created when a buyer paid a template. You don't send this value.
10 Template. Its link doesn't expire.

Iteration types

ID Interval
1 Daily
2 Weekly
3 Monthly. The start day must be between 1 and 28.
4 Yearly
5 Quarterly

Statuses

ID Status
1 Initial: waiting for the buyer to pay.
2 Active: a card is attached and charges run on schedule.
3 Paused: no charges; iterations whose date passes are skipped.
4 Failed: the card check failed when the buyer paid. No automatic retry; the buyer can pay again.
5 Canceled: by the seller, or automatically after the last failed attempt.
6 Completed: all iterations were charged or skipped.
7 Failed, retry pending: a scheduled charge failed and is retried the next day.

Callbacks

PayMe sends callbacks to sub_callback_url, or to your partner's default callback URL if you didn't send one. They are POST requests of type x-www-form-urlencoded. The fields are listed on Callbacks → Subscriptions.

notify_type When
sub-create The subscription was created.
sub-active A card was attached and the subscription is active. The first charge follows within about a minute after sub_start_date.
sub-iteration-success A scheduled charge succeeded.
sub-failure A charge failed: the card check when the buyer paid (status 4), or a scheduled charge that will be retried (status 7).
sub-pause The subscription was paused.
sub-iteration-skipped An iteration date passed while the subscription was paused. The iteration is skipped and never charged.
sub-complete The last iteration was charged or skipped.
sub-cancel The subscription was canceled, by the seller or automatically.

Saved cards

To charge a saved card instead of sending the buyer to sub_url, pass a permanent buyer_key to Create a subscription. How to get one: Saved cards & recurring.

Endpoints