Create a subscription

• Sandbox: POST https://sandbox.payme.io/api/generate-subscription
• Production: POST https://live.payme.io/api/generate-subscription

Credentials

• Request body field seller_payme_id (required): The seller's MPL. Must be in the JSON body on this endpoint.
• Request body field payme_client_key (optional): Partners only: your partner key. You can send it in the PayMe-Partner-Key header instead. A seller authenticates with seller_payme_id alone.

Overview

Creates a subscription that charges the buyer once per iteration. A new subscription is in status 1 (Initial), and the response returns sub_url, the hosted page where the buyer enters a card. To skip that page, send a permanent buyer_key: the card is attached at once and the subscription is created in status 2 (Active).

• Each iteration is charged separately: for 50.00 a month over 12 months, each month is charged 50.00.
• Nothing is charged in this call, even with buyer_key. A background job that runs once a minute makes every charge, including the first: it runs within about a minute after sub_start_date (default: today) once a card is attached.
• If the card check fails when the buyer pays on sub_url, the subscription moves to status 4 (Failed) and PayMe sends sub-failure. It isn't canceled and isn't retried: the buyer can pay again.
• 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, move to status 5 (Canceled) and send sub-cancel instead.
• The response and the callbacks never contain the buyer_key. Read it with Get buyer key and sub_payme_id.
• subscription_id isn't unique: sending the same value twice creates two subscriptions.

To share one payment link with many buyers, send sub_type 10 (template). Each buyer who pays it gets their own subscription.

Lifecycle, retries, callbacks and price changes: Subscriptions overview and Saved cards & recurring.

Authentication

Send seller_payme_id (the seller's MPL) in the JSON body: on this endpoint the PayMe-Merchant-Key header alone isn't enough. Partners also send payme_client_key, in the body or the PayMe-Partner-Key header.

Errors

Errors return status_code 1 with HTTP 500 unless the table says otherwise.

Parameters

This endpoint takes no path, query or header parameters.

Request body

Content type: application/json

Request example

{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sub_price": 5000,
  "sub_currency": "ILS",
  "sub_description": "Monthly plan",
  "sub_iteration_type": 3,
  "sub_iterations": 12,
  "sub_start_date": "01/12/2026",
  "subscription_id": "order-1001",
  "sub_callback_url": "https://www.example.com/payment/callback",
  "sub_return_url": "https://www.example.com/payment/success",
  "language": "en"
}

Code samples

curl

curl -X POST 'https://sandbox.payme.io/api/generate-subscription' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sub_price": 5000,
  "sub_currency": "ILS",
  "sub_description": "Monthly plan",
  "sub_iteration_type": 3,
  "sub_iterations": 12,
  "sub_start_date": "01/12/2026",
  "subscription_id": "order-1001",
  "sub_callback_url": "https://www.example.com/payment/callback",
  "sub_return_url": "https://www.example.com/payment/success",
  "language": "en"
}'

Node.js

const response = await fetch("https://sandbox.payme.io/api/generate-subscription", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
    "sub_price": 5000,
    "sub_currency": "ILS",
    "sub_description": "Monthly plan",
    "sub_iteration_type": 3,
    "sub_iterations": 12,
    "sub_start_date": "01/12/2026",
    "subscription_id": "order-1001",
    "sub_callback_url": "https://www.example.com/payment/callback",
    "sub_return_url": "https://www.example.com/payment/success",
    "language": "en"
  }),
});

console.log(await response.text());

Python

import requests

response = requests.post(
    "https://sandbox.payme.io/api/generate-subscription",
    json={
        "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
        "sub_price": 5000,
        "sub_currency": "ILS",
        "sub_description": "Monthly plan",
        "sub_iteration_type": 3,
        "sub_iterations": 12,
        "sub_start_date": "01/12/2026",
        "subscription_id": "order-1001",
        "sub_callback_url": "https://www.example.com/payment/callback",
        "sub_return_url": "https://www.example.com/payment/success",
        "language": "en",
    },
)

print(response.text)

PHP

<?php

$body = <<<'BODY'
{
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "sub_price": 5000,
  "sub_currency": "ILS",
  "sub_description": "Monthly plan",
  "sub_iteration_type": 3,
  "sub_iterations": 12,
  "sub_start_date": "01/12/2026",
  "subscription_id": "order-1001",
  "sub_callback_url": "https://www.example.com/payment/callback",
  "sub_return_url": "https://www.example.com/payment/success",
  "language": "en"
}
BODY;

$ch = curl_init('https://sandbox.payme.io/api/generate-subscription');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);

$response = curl_exec($ch);
curl_close($ch);

echo $response;

Responses

200 — The subscription was created. (success)

{
  "sub_url": "https://sandbox.payme.io/subscription/generate/SUB16885-68336QPL-UQSSS1CC-SYKXI53N",
  "status_code": 0,
  "payme_status": "success",
  "status_error_code": 0,
  "seller_payme_id": "MPLDEMO-MPLDEMO-MPLDEMO-1234567",
  "seller_id": null,
  "sub_payme_id": "SUB16885-68336QPL-UQSSS1CC-SYKXI53N",
  "sub_payme_code": 477004,
  "subscription_id": "order-1001",
  "sub_created": "2026-11-09 10:15:00",
  "sub_start_date": "2026-12-01 00:00:00",
  "sub_prev_date": null,
  "sub_next_date": "2026-12-01 00:00:00",
  "sub_status": 1,
  "sub_iteration_type": 3,
  "sub_currency": "ILS",
  "sub_price": 5000,
  "sub_description": "Monthly plan",
  "sub_iterations": 12,
  "sub_iterations_completed": 0,
  "sub_iterations_skipped": 0,
  "sub_iterations_left": 12,
  "sub_paid": false,
  "sub_error_text": null
}

500 — The request was refused. See the error table. (error)

{
  "status_code": 1,
  "status_error_details": "Required parameter is missing",
  "status_additional_info": "seller_payme_id",
  "status_error_code": 1,
  "session": "FhT3aXe7"
}