Recurring payment plans

Set up automated recurring payments by creating payment plans with configurable frequency and payer consent.

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

1. 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.

2. 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.

3. Activate the plan

   Once at least one payer has accepted, activate the plan. SynchPay begins generating payment requests automatically at each interval.

4. 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.

You can identify a payer by either their SynchPay profile ID (for registered users) or their phone number (for users not yet registered).

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, [phone]). Required if SenderSynchProfileId is not provided.	No*

* You must provide at least one of 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.

All management endpoints require 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:

1. SynchPay checks whether the payer has an approved debit authorization.
2. If the payment amount is within the authorized limit, the payment is automatically scheduled and processed on the due date.
3. 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.