Recurring Payments

Recurring Payments let users set up automatic crypto purchases on a regular schedule — weekly or monthly. Once configured, the user's card is charged automatically on the selected day.

To enable Recurring Payments for your widget, contact your integration manager.

How It Works

When Recurring Payments are enabled for your widget, users can access them from the navigation menu (top-right icon). This opens the plan management screen.

You can also open the widget directly on either recurring screen using the widget_flow parameter:

Value	Opens
`recurrent_setup`	Plan creation — the user selects frequency and charge day, then completes the initial payment
`recurrent_manage`	Plan management — the user views existing plans and can cancel them

When the widget is opened with either of these values, the standard buy/sell flow is not accessible — only the recurring screens are shown.

Plan creation flow (recurrent_setup):

The user selects a frequency (weekly or monthly) and a charge day.
The user completes the initial payment to activate the subscription.
After setup, the user is redirected to your redirect_url.
Subsequent charges happen automatically on the configured schedule.

You can pre-fill and lock frequency and charge day using URL parameters — see Key Parameters below.

Key Parameters

Parameter	Description
`widget_flow`	`recurrent_setup` to open plan creation; `recurrent_manage` to open plan management
`address`	User's wallet address for receiving purchased crypto
`currency`	Pre-select cryptocurrency (e.g., `USDT`)
`fiat_currency`	Pre-select fiat currency (e.g., `EUR`)
`fiat_amount`	Pre-fill fiat amount
`network`	Pre-select blockchain network (e.g., `ETHEREUM`, `TRON`, `BINANCESMARTCHAIN`)
`frequency`	Lock the charge frequency: `weekly` or `monthly`
`charge_day`	Lock the charge day. For `monthly`: `1`–`31`. For `weekly`: `monday`–`sunday`
`merchant_subscription_id`	Your own identifier for the recurring plan. Max 255 characters. Must be unique per widget — returns an error if a plan with this ID already exists for your widget.
`merchant_transaction_id`	Your internal transaction ID
`redirect_url`	URL to redirect the user after completing subscription setup
`signature`	Security signature — see Signature Generation

If frequency or charge_day is pre-set, the value is fixed in the widget UI. The user must return to your screen to change it.

See the full Widget Parameters reference for all available options.

Example

Redirect URL:

https://exchange.mercuryo.io/?widget_id=YOUR_WIDGET_ID
  &widget_flow=recurrent_setup
  &currency=USDT
  &network=TRON
  &fiat_currency=EUR
  &fiat_amount=540
  &address=TQhoZ9hgkQ1NMAMJZ23EPaGtJDMCmv6yJd
  &frequency=monthly
  &charge_day=15
  &merchant_subscription_id=your-plan-id-001
  &merchant_transaction_id=tx_123456
  &redirect_url=https://yourapp.com/success
  &signature=v2:GENERATED_SIGNATURE

iFrame JS SDK:

mercuryoWidget.run({
  widgetId: 'YOUR_WIDGET_ID',
  host: document.getElementById('mercuryo-widget'),
  address: 'TQhoZ9hgkQ1NMAMJZ23EPaGtJDMCmv6yJd',
  widgetFlow: 'recurrent_setup',
  currency: 'USDT',
  network: 'TRON',
  fiatCurrency: 'EUR',
  fiatAmount: '540',
  frequency: 'monthly',
  chargeDay: '15',
  merchantSubscriptionId: 'your-plan-id-001',
  merchantTransactionId: 'tx_123456',
  redirectUrl: 'https://yourapp.com/success',
  signature: 'v2:GENERATED_SIGNATURE'
});

Callbacks

Subscription lifecycle (`type=recurring_subscription`)

When a recurring subscription changes status, Mercuryo sends a type=recurring_subscription callback to your configured callback URL — separate from individual charge notifications.

Event	`status`	`cancel_reason`
First charge completed, subscription is now active	`active`	—
User cancelled the subscription	`cancelled`	`user_cancelled`
System cancelled after 3 consecutive failed charges	`cancelled`	`system_attempts_exceeded`

See the Callback Reference for the full payload structure and examples.

Charge enrichment

Buy and withdrawal transactions created by a recurring charge include three additional fields in their callback payload. These fields are absent on non-recurring transactions.

Field	Type	Description
`recurring_subscription_id`	string	Recurring plan identifier in Mercuryo
`recurring_merchant_subscription_id`	string \| null	Your plan identifier (`merchant_subscription_id`). `null` if not provided at setup
`recurring_execution_attempt`	integer	Charge attempt number within the current cycle (1–3)

See the Callback Reference for the full transaction callback payload.

Sandbox: Only GBP is available as the fiat currency when testing recurring payments in the Sandbox environment.

Off-Chain

Mercuryo PRO