|
| 1 | +--- |
| 2 | +description: Create subscriptions that would automatically be paid through out a timeframe. |
| 3 | +--- |
| 4 | + |
| 5 | +# Recurring payments |
| 6 | + |
| 7 | +{% hint style="info" %} |
| 8 | +**Talk to an expert** |
| 9 | + |
| 10 | +Discover how Request Network API can enhance your app's features - [book a call](https://calendly.com/mariana-rn/request-network-demo-docs) with us. |
| 11 | +{% endhint %} |
| 12 | + |
| 13 | +## Overview |
| 14 | + |
| 15 | +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. |
| 16 | + |
| 17 | +## Core functionality |
| 18 | + |
| 19 | +* **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. |
| 20 | +* **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 execute 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 haven't already. |
| 21 | +* **Automated Payments:** Once the payer has authorized the schedule, the 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. |
| 22 | +* **Status Tracking and Webhooks:** You can monitor the status of each recurring payment, including executed payments, failures, and completion status (e.g., active, paused, completed). Webhook notifications will be sent for key events like `payment.confirmed` and `payment.failed`, allowing your application to react in real time. |
| 23 | +* **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 (e.g., due to insufficient funds), the schedule will be paused, and you can unpause it once the issue is resolved. Unpausing a recurring payment once issues are resolved would allow the subscription to catch up on any missed payments. |
| 24 | + |
| 25 | +## Security & Trust |
| 26 | + |
| 27 | +Our recurring payments feature is built on a non-custodial smart contract that enforces several security measures to protect payers' funds and ensure predictable behavior. The core principle is that all payment parameters are defined upfront and cryptographically signed by the payer, preventing any unauthorized changes. |
| 28 | + |
| 29 | +Here are some key security features provided by the smart contract: |
| 30 | + |
| 31 | + |
| 32 | + |
| 33 | +* **Signature-Protected Payments:** Payments cannot be triggered without a valid EIP-712 signature from the payer. The smart contract verifies the signature for every execution attempt. |
| 34 | +* **Immutable Recipient:** The recipient's address is part of the signed data. Funds can only be sent to this specified address, which cannot be altered after the schedule is authorized. |
| 35 | +* **Fixed Payment Amount:** The amount for each payment is fixed in the signed permit. The smart contract will only transfer this exact amount, preventing any over- or under-payments. |
| 36 | +* **Strict Payment Timing:** Payments cannot be triggered before their scheduled time. The contract calculates the due date for each payment and will reject any attempts to execute it prematurely. |
| 37 | +* **No-Repeat Payments:** The contract tracks payments, making it impossible to process the same payment more than once. |
| 38 | +* **Enforced Payment Limit:** The total number of payments is defined in the signed permit. The smart contract enforces this limit and will not allow any extra payments beyond the agreed-upon total. |
| 39 | +* **Sequential Execution:** Payments must be executed in a strict, sequential order (e.g., payment #1, then #2, then #3). Any out-of-order attempt will fail, preventing missed or skipped payments from disrupting the schedule. |
| 40 | +* **Signature Expiration:** Each recurring payment schedule has a `deadline`. If the signature expires, no further payments can be triggered, providing a hard stop for the agreement. |
| 41 | + |
| 42 | +## Recurring payment workflow |
| 43 | + |
| 44 | +The following diagram illustrates the typical flow for creating and managing recurring payments: |
| 45 | + |
| 46 | +```mermaid |
| 47 | +--- |
| 48 | +config: |
| 49 | + fontSize: 10 |
| 50 | + sequence: |
| 51 | + wrap: true |
| 52 | + actorMargin: 50 |
| 53 | + height: 30 |
| 54 | +--- |
| 55 | +sequenceDiagram |
| 56 | + actor User as User (Payer) |
| 57 | + participant App |
| 58 | + participant API as Request Network API |
| 59 | + participant Blockchain |
| 60 | +
|
| 61 | + App->>API: Create recurring payment schedule |
| 62 | + activate API |
| 63 | + API-->>App: Returns payment permit for signing |
| 64 | + deactivate API |
| 65 | +
|
| 66 | + alt If token allowance is needed |
| 67 | + App->>User: Prompt for one-time token allowance approval |
| 68 | + User->>Blockchain: Approves allowance transaction |
| 69 | + end |
| 70 | +
|
| 71 | + App->>User: Prompt to sign payment permit |
| 72 | + User->>App: Provides signature for the permit |
| 73 | +
|
| 74 | + App->>API: Submit signed permit to activate schedule |
| 75 | + activate API |
| 76 | + API-->>App: Confirms activation |
| 77 | + deactivate API |
| 78 | +
|
| 79 | + loop For each scheduled payment |
| 80 | + API->>Blockchain: Triggers payment automatically |
| 81 | + Blockchain-->>API: Payment result |
| 82 | + API->>App: Webhook notification (payment.confirmed / payment.failed) |
| 83 | + end |
| 84 | +``` |
0 commit comments