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://api.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://api.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://api.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

terminal_friendly_id

string

required

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

Request body

amount

number

required

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

currency

string

required

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

recurring

object

required

Configuration for the recurring billing series.

Show properties

managed_by

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.

first_payment_date

string

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

recurring_date_type

string

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

time_interval

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.

number_of_payments

integer

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

cancellation_date

string

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

payment_instrument

object

Card details for the payment. Mutually exclusive with token.

Show properties

card_number

string

Full card number (PAN).

expiry_month

integer

Card expiry month (1–12).

expiry_year

integer

Card expiry year (2024–2099).

payment_method

string

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

payer

object

Payer identity. Required unless you provide payer_fingerprint.

Show properties

first_name

string

required

Payer’s first name.

last_name

string

required

Payer’s last name.

string

required

Payer’s email address.

payer_fingerprint

string

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

token

string

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

cvv

string

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

Response

transaction_id

string

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

order_id

string

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

recurring_id

string

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

accepted

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.

Transaction status

Recurring status

curl --request POST \
  --url https://api.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://api.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://api.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);

Overview

Payments

Recurring

Future Transactions

Path parameters

Request body

Response

​Path parameters

​Request body

​Response

Path parameters

Request body

Response