diff --git a/api-features/recurring-payments.mdx b/api-features/recurring-payments.mdx index 4a216d5..0f53f52 100644 --- a/api-features/recurring-payments.mdx +++ b/api-features/recurring-payments.mdx @@ -3,70 +3,140 @@ title: "Recurring Payments" description: "Automated payment schedules for subscriptions and recurring billing" --- - -**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). - - ## 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: - - - Monthly/annual subscription billing - - - - Scheduled payment disbursements - - +- **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 + + +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. + + + +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, +); +``` + -## Implementation Examples + +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}). - - - Monthly software license fees - - - - Structured repayment schedules - - +A successful response confirms activation. The schedule is now active and payments are executed automatically at the configured intervals. + -## Available In EasyInvoice + +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}). + -Both **Subscriptions** and **Recurring Payouts** are featured in the EasyInvoice demo with working examples. + +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 + + -See [API Reference - Recurring Payments](/api-reference/recurring-payments) for complete technical documentation. \ No newline at end of file +For full endpoint schemas and request/response examples, see [Request Network API Reference](https://api.request.network/open-api).