Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.smartretry.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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"
    }
  }'

​
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.
​
payment_instrument
object
Card details for the payment. Mutually exclusive with token.
​
payer
object
Payer identity. Required unless you provide payer_fingerprint.
​
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.