Overview
Payment plans let you charge users on a recurring schedule without creating each payment request manually. You define the amount, frequency, and start date, then add one or more payers who consent to the plan. Once a plan is active, SynchPay automatically generates payment requests at each interval and processes them through autopay.
How it works
Create a payment plan
Define the recurring amount, frequency (for example, every 1 month or every 2 weeks), start date, and the bank account that will receive funds.
Add payer consent
For each user you want to charge, create a consent record on the plan. The user must accept the consent before payments begin.
Activate the plan
Once at least one payer has accepted, activate the plan. SynchPay begins generating payment requests automatically at each interval.
Automatic payment processing
When a payment request is due, SynchPay checks the payer’s debit authorization and processes the payment automatically. You receive a webhook for each completed payment.
Payment plan lifecycle
A payment plan moves through these statuses:
| Status | Description |
|---|
Draft | Initial state after creation. The plan is not yet generating payments. |
Active | The plan is live and generating payment requests on schedule. |
Paused | Temporarily stopped. No new payment requests are created until reactivated. |
Failed | The plan encountered an error. You can reactivate or cancel it. |
Canceled | Permanently stopped. This is a final state. |
Completed | All payments have been fulfilled. This is a final state. |
Status transitions
| From | Can move to |
|---|
Draft | Active, Canceled |
Active | Draft, Paused, Failed, Canceled, Completed |
Paused | Active, Canceled |
Failed | Active, Canceled |
Canceled | — |
Completed | — |
Frequency options
You configure how often payments recur using two fields:
IntervalValue — a number representing how many units between each payment (for example, 1, 2, 3)IntervalUnit — the time unit: Day, Week, Month, Quarter, or Year
Examples:
| IntervalValue | IntervalUnit | Schedule |
|---|
| 1 | Month | Every month |
| 2 | Week | Every 2 weeks |
| 1 | Quarter | Every quarter |
| 7 | Day | Every 7 days |
Payer consent
Before a user can be charged through a payment plan, they must provide consent. Each consent record links a payer to the plan and tracks their agreement status.
Consent statuses
| Status | Description |
|---|
Pending | Consent requested but the user has not yet responded. |
Accepted | The user agreed to the recurring payments. |
Declined | The user rejected the request. |
Canceled | The company canceled the consent. |
Revoked | The user withdrew a previously accepted consent. |
Only payers with Accepted consent generate payment requests. If a payer declines or revokes consent, no further payments are created for them.
Creating a payment plan
Endpoint
- URL:
https://api.synchpay.com/payment/plan
- Method:
POST
- Authorization:
Bearer <AccessToken>
Request body
| Parameter | Type | Description | Required |
|---|
Amount | object | Payment amount for each recurrence. Contains Value (integer, in cents) and CurrencyCode. | Yes |
RecipientBankAccountId | string | The bank account ID that receives the payments. | Yes |
StartDate | string | When recurring payments begin, in date-only format (for example, "2026-04-01"). | Yes |
TimeZone | string | The IANA timezone for the start date (for example, "America/New_York"). | Yes |
IntervalValue | integer | Number of time units between each payment. | Yes |
IntervalUnit | string | Time unit for recurrence: Day, Week, Month, Quarter, or Year. | Yes |
Example request
{
"Amount": {
"Value": 5000,
"CurrencyCode": "USD"
},
"RecipientBankAccountId": "a3f1c2d4-5678-9abc-def0-123456789abc",
"StartDate": "2026-04-01",
"TimeZone": "America/New_York",
"IntervalValue": 1,
"IntervalUnit": "Month"
}
Response
{
"PaymentPlanId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123"
}
Adding payer consent
After creating a plan, add one or more payers by creating consent records.
Endpoint
- URL:
https://api.synchpay.com/payment/plan/{paymentPlanId}/consent
- Method:
POST
- Authorization:
Bearer <AccessToken>
Path parameters
| Parameter | Type | Description | Required |
|---|
paymentPlanId | string | The payment plan ID to add the payer to. | Yes |
Request body
| Parameter | Type | Description | Required |
|---|
SenderSynchProfileId | string | The payer’s SynchPay profile ID. Required if PhoneNumber is not provided. | No* |
PhoneNumber | string | The payer’s phone number in international format (for example, +15551234567). Required if SenderSynchProfileId is not provided. | No* |
SenderSynchProfileId or PhoneNumber.
Example request
{
"SenderSynchProfileId": "6e8d9257-bd5f-45cf-8f29-6d0ae8a6d991"
}
Managing a payment plan
Use these endpoints to change the status of an existing plan:
| Action | Method | URL | Description |
|---|
| Activate | PUT | /payment/plan/{paymentPlanId}/activate | Start generating payments. |
| Pause | PUT | /payment/plan/{paymentPlanId}/pause | Temporarily stop payments. |
| Cancel | PUT | /payment/plan/{paymentPlanId}/cancel | Permanently stop the plan. |
Bearer <AccessToken> authorization.
Autopay and debit authorization
Recurring payment plans work with the debit authorization system. When a payment request is generated from a plan:
- SynchPay checks whether the payer has an approved debit authorization.
- If the payment amount is within the authorized limit, the payment is automatically scheduled and processed on the due date.
- If the payer does not have a valid debit authorization or the amount exceeds the limit, the payment request is created in
Pending status and requires manual approval.
To ensure fully automated recurring payments, set up debit authorization for each payer before activating the plan. See managing debit authorization for details. Payment generation
SynchPay automatically generates individual payment requests from active plans:
- Payment requests are created for each payer with
Accepted consent.
- The due date for each payment is calculated by adding the configured interval to the previous payment’s due date (or the plan’s start date for the first payment).
- Each generated payment request follows the same payment statuses as manually created payments.
- You receive payment status webhooks for each generated payment, so your existing webhook handlers work without changes.
