Skip to content

docs(recurring-payments): rewrite with comprehensive workflow, security details, and practical implementation guide #58

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aimensahnoun wants to merge 1 commit into
base: 03-02-docs_api-features_migrate_batch-payments_page_from_legacy_docs_replace_ai-generated_placeholder_content_in_api-features_batch-payments.mdx_with_legacy_batch_payments_documentation_while_keeping_mintlify-compatible_formatting._-_
Choose a base branch
from
+119 −49
Open

docs(recurring-payments): rewrite with comprehensive workflow, security details, and practical implementation guide #58

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 119 additions & 49 deletions api-features/recurring-payments.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,70 +3,140 @@ title: "Recurring Payments"
description: "Automated payment schedules for subscriptions and recurring billing"
---

<Warning>
**AI-Generated Content** – This page was generated with AI assistance and may contain inaccuracies. While likely close to accurate, please verify critical details with the [stable documentation](https://docs.request.network) or [contact support](https://github.com/orgs/RequestNetwork/discussions).
</Warning>

## Overview

Recurring payments enable automated payment collection on predefined schedules, supporting subscription services, installment plans, and regular business expenses.
The Recurring Payments feature allows you to create and manage subscription-like payments on the blockchain. The API handles the scheduling and triggering of these payments, providing a reliable way to automate regular transfers.

## Core functionality

- **Create Recurring Schedules:** Define a payment schedule with a start date, frequency (daily, weekly, monthly, yearly), and total number of payments. The system will generate a payment permit that encapsulates all the payment details.
- **Payer Authorization:** To authorize the payment series, the payer signs the payment permit with an EIP-712 signature. This single authorization allows the system to trigger all subsequent payments in the schedule without further interaction from the payer. For the first payment, the payer may also need to approve a token allowance for the recurring payment contract if they have not already.
- **Automated Payments:** Once the payer has authorized the schedule, Request Network API backend systems automatically trigger the payments at the specified intervals. You can rely on the API to handle the entire lifecycle of the recurring payments.
- **Status Tracking and Webhooks:** You can monitor the status of each recurring payment, including processed payments, failures, and completion status (for example active, paused, completed). Webhook notifications are sent for key events like `payment.confirmed` and `payment.failed`, allowing your application to react in real time.
- **Flexible Management:** The API provides the ability to manage the lifecycle of a recurring payment. You can cancel a recurring payment schedule to stop future payments. If a payment fails (for example due to insufficient funds), the schedule is paused, and you can unpause it once the issue is resolved. Unpausing a recurring payment after issues are resolved allows the subscription to catch up on missed payments.

## Security and Trust

Recurring payments are built on a non-custodial smart contract with several security measures to protect payer funds and ensure predictable behavior. The core principle is that all payment parameters are defined upfront and cryptographically signed by the payer, preventing unauthorized changes.

## Payment Types
Key security features provided by the smart contract:

<CardGroup cols={2}>
<Card title="Subscriptions" icon="repeat">
Monthly/annual subscription billing
</Card>

<Card title="Recurring Payouts" icon="calendar-days">
Scheduled payment disbursements
</Card>
</CardGroup>
- **Signature-Protected Payments:** Payments cannot be triggered without a valid EIP-712 signature from the payer. The smart contract verifies the signature for every payment attempt.
- **Immutable Recipient:** The recipient address is part of the signed data. Funds can only be sent to this specified address and cannot be altered after the schedule is authorized.
- **Fixed Payment Amount:** The amount for each payment is fixed in the signed permit. The smart contract transfers only this exact amount.
- **Strict Payment Timing:** Payments cannot be triggered before their scheduled time. The contract calculates the due date for each payment and rejects premature attempts.
- **No-Repeat Payments:** The contract tracks payments, making it impossible to process the same payment more than once.
- **Enforced Payment Limit:** The total number of payments is defined in the signed permit. The smart contract enforces this limit and does not allow extra payments.
- **Sequential Payments:** Payments must be triggered in strict order (payment #1, then #2, then #3). Out-of-order attempts fail.
- **Signature Expiration:** Each recurring payment schedule has a `deadline`. If the signature expires, no further payments can be triggered.

## How It Works
## Recurring payment workflow

```mermaid
graph TD
A[Create Payment Plan] --> B[Schedule Setup]
B --> C[First Payment]
C --> D[Automatic Execution]
D --> E[Next Payment Date]
E --> D
sequenceDiagram
actor User as User (Payer)
participant App
participant API as Request Network API
participant Blockchain

App->>API: Create recurring payment schedule
activate API
API-->>App: Returns payment permit for signing
deactivate API

alt If token allowance is needed
App->>User: Prompt for one-time token allowance approval
User->>Blockchain: Approves allowance transaction
end

App->>User: Prompt to sign payment permit
User->>App: Provides signature for the permit

App->>API: Submit signed permit to activate schedule
activate API
API-->>App: Confirms activation
deactivate API

loop For each scheduled payment
API->>Blockchain: Triggers payment automatically
Blockchain-->>API: Payment result
API->>App: Webhook notification (payment.confirmed / payment.failed)
end
```

**Key Features:**
- **Flexible Schedules:** Daily, weekly, monthly, yearly intervals
- **Smart Contracts:** Automated execution without manual intervention
- **Fail-Safe Logic:** Retry mechanisms and payment recovery
## Supported Networks

Recurring payments are supported on the following blockchain networks:

- Ethereum
- Polygon
- Arbitrum
- Gnosis
- Base
- Binance Smart Chain
- Sepolia

## Supported currencies

Recurring payments support ERC20 currencies available on the supported networks.

See [Supported Chains and Currencies](/resources/supported-chains-and-currencies).

## Configuration Options
## How it works

### Schedule Types
- **Fixed Interval:** Regular payments (monthly, quarterly)
- **Custom Dates:** Specific payment dates
- **Business Days Only:** Skip weekends and holidays
<Steps>
<Step title="Create a recurring payment">
Create a recurring schedule with [POST /v2/payouts](https://api.request.network/open-api/#tag/v2payouts/POST/v2/payouts).

### Payment Amounts
- **Fixed Amount:** Same amount each payment
- **Variable Amount:** Different amounts per payment
- **Escalation:** Automatic amount increases
For recurring payments, include a `recurrence` object with:

- `startDate`
- `frequency` (`DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`)
- `totalPayments`
- `payer`

The response includes a payment permit payload (EIP-712 typed data) for signature and, when required, transactions for token allowance approval.
</Step>

<Step title="Payer authorization">
The payer must:

- approve the recurring payment contract to spend the required token amount (if not already approved)
- sign the payment permit with an EIP-712 compatible wallet

```javascript
import { Wallet, providers } from "ethers";

const privateKey = "WALLET_PRIVATE_KEY";
const provider = new providers.JsonRpcProvider("RPC_URL");

const wallet = new Wallet(privateKey, provider);

const recurringPaymentPermit = ...; // from API response
const signature = await wallet._signTypedData(
recurringPaymentPermit.domain,
recurringPaymentPermit.types,
recurringPaymentPermit.values,
);
```
</Step>

## Implementation Examples
<Step title="Recurring payment activation">
Activate the recurring payment by submitting the permit signature with [POST /v2/payouts/recurring/{id}](https://api.request.network/open-api/#tag/v2payouts/POST/v2/payouts/recurring/{id}).

<CardGroup cols={2}>
<Card title="SaaS Subscriptions" icon="laptop-code">
Monthly software license fees
</Card>

<Card title="Loan Payments" icon="hand-coins">
Structured repayment schedules
</Card>
</CardGroup>
A successful response confirms activation. The schedule is now active and payments are executed automatically at the configured intervals.
</Step>

## Available In EasyInvoice
<Step title="Status monitoring">
Retrieve status, processed payments, next payment date, and related details with [GET /v2/payouts/recurring/{id}](https://api.request.network/open-api/#tag/v2payouts/GET/v2/payouts/recurring/{id}).
</Step>

Both **Subscriptions** and **Recurring Payouts** are featured in the EasyInvoice demo with working examples.
<Step title="Recurring payment management">
Manage recurring payments with [PATCH /v2/payouts/recurring/{id}](https://api.request.network/open-api/#tag/v2payouts/PATCH/v2/payouts/recurring/{id}).

## Implementation Details
- **cancel**: stops all future payments
- **unpause**: resumes a paused recurring payment
</Step>
</Steps>

See [API Reference - Recurring Payments](/api-reference/recurring-payments) for complete technical documentation.
For full endpoint schemas and request/response examples, see [Request Network API Reference](https://api.request.network/open-api).