Initialize recurring

POST /v1/payments/recurring/init/{terminal_friendly_id} Initializing a recurring agreement creates a billing series and processes the first payment. SmartRetry returns a recurring_id that identifies the series for all subsequent operations - store it alongside your subscription record.

Once a recurring series is cancelled, it cannot be reactivated. Create a new agreement if you need to resume billing.

Safe retries for this POST endpoint use the Idempotency-Key header. Reuse the same key only when retrying the exact same request body. See Idempotency.

curl --request POST \
  --url https://terminal.smartretry.com/v1/payments/recurring/init/ABC123 \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: recurring-init-20260401-001' \
  --data '{
    "amount": 19.99,
    "currency": "USD",
    "recurring": {
      "managed_by": "our_platform",
      "first_payment_date": "2026-04-01",
      "recurring_date_type": "monthly",
      "time_interval": 1,
      "number_of_payments": 12
    },
    "payer": {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com"
    },
    "payment_instrument": {
      "card_number": "4111111111111111",
      "expiry_month": 12,
      "expiry_year": 2028,
      "payment_method": "cards"
    }
  }'

import requests

response = requests.post(
    "https://terminal.smartretry.com/v1/payments/recurring/init/ABC123",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "YOUR_API_KEY",
        "Idempotency-Key": "recurring-init-20260401-001"
    },
    json={
        "amount": 19.99,
        "currency": "USD",
        "recurring": {
            "managed_by": "our_platform",
            "first_payment_date": "2026-04-01",
            "recurring_date_type": "monthly",
            "time_interval": 1,
            "number_of_payments": 12
        },
        "payer": {
            "first_name": "Jane",
            "last_name": "Smith",
            "email": "jane.smith@example.com"
        },
        "payment_instrument": {
            "card_number": "4111111111111111",
            "expiry_month": 12,
            "expiry_year": 2028,
            "payment_method": "cards"
        }
    }
)

print(response.json())

const response = await fetch(
  "https://terminal.smartretry.com/v1/payments/recurring/init/ABC123",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": "YOUR_API_KEY",
      "Idempotency-Key": "recurring-init-20260401-001"
    },
    body: JSON.stringify({
      amount: 19.99,
      currency: "USD",
      recurring: {
        managed_by: "our_platform",
        first_payment_date: "2026-04-01",
        recurring_date_type: "monthly",
        time_interval: 1,
        number_of_payments: 12
      },
      payer: {
        first_name: "Jane",
        last_name: "Smith",
        email: "jane.smith@example.com"
      },
      payment_instrument: {
        card_number: "4111111111111111",
        expiry_month: 12,
        expiry_year: 2028,
        payment_method: "cards"
      }
    })
  }
);

const data = await response.json();
console.log(data);

Path parameters

string

required

Your 6-character terminal identifier. Scopes the request to your merchant account configuration.

Request body

number

required

Charge amount in major currency units (e.g., 19.99 for $19.99). Minimum 0.01, maximum 999999.99.

string

required

ISO 4217 currency code (e.g., USD, EUR, GBP).

object

required

Configuration for the recurring billing series.

Show properties

string

required

Who controls the billing schedule. One of merchant, our_platform, or payment_provider.

merchant - you trigger each charge manually via the charge endpoint.
our_platform - SmartRetry schedules and executes charges automatically.
payment_provider - the underlying payment provider manages the schedule.

string

Date of the first scheduled payment in YYYY-MM-DD format. Required when managed_by is our_platform.

string

Billing frequency. One of daily, weekly, monthly, or yearly. Required when managed_by is our_platform.

integer

Interval multiplier applied to recurring_date_type. Minimum value: 1. For example, time_interval: 2 with recurring_date_type: monthly schedules a charge every 2 months. Required when managed_by is our_platform.

integer

Total number of payments in the series. Minimum value: 1. Omit to create an open-ended agreement with no payment limit.

string

Date on which the agreement automatically ends, in YYYY-MM-DD format. No charges are processed on or after this date.

object

Card details for the payment. Mutually exclusive with token.

Show properties

string

Full card number (PAN).

integer

Card expiry month (1–12).

integer

Card expiry year (2024–2099).

string

Payment method type. One of: cards, digital_wallets, bnpl, online_banking, rtp, vouchers, cash, direct_debit, cryptocurrencies.

object

Payer identity. Required unless you provide payer_fingerprint.

Show properties

string

required

Payer’s first name.

string

required

Payer’s last name.

string

required

Payer’s email address.

string

An 88-character stored payer fingerprint. Mutually exclusive with payer - provide one or the other, not both.

string

An 88-character stored payment token. Use this instead of payment_instrument when charging a saved card.

string

Card verification value. Optional, but may be required depending on your terminal configuration.

Response

string

Unique identifier for the initial transaction in this series (8 characters).

string

Order identifier associated with the initial transaction (8 characters).

string

Unique identifier for the recurring series (8 characters). Store this value - you need it for all subsequent recurring operations.

boolean

true if the initial payment was authorized and the series was created. false if the payment was declined. A 200 response with accepted: false means the request was valid but the transaction did not go through.

Example response

{
  "transaction_id": "TX8A3F2C",
  "order_id": "OR7B9E1D",
  "recurring_id": "RC9F4A2B",
  "accepted": true
}

Store recurring_id in your database alongside your subscription record immediately after a successful response. You need it to charge, update, cancel, or query the series.

Overview

Payments

Recurring

Future Transactions

Path parameters

Request body

Response

​Path parameters

​Request body

​Response

Path parameters

Request body

Response