Recurring payment plans

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

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.

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. This is a final state.
`Canceled`	The company canceled the consent. This is a final state.
`Revoked`	The user withdrew a previously accepted consent. This is a final state.

From	Can move to
`Pending`	`Accepted`, `Declined`, `Canceled`
`Accepted`	`Revoked`, `Canceled`
`Declined`	—
`Canceled`	—
`Revoked`	—

Only payers with Accepted consent generate payment requests. If a payer declines or revokes consent, no further payments are created for them.

When you create a consent record, SynchPay sends the payer a notification prompting them to accept or decline. 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

The StartDate must not be in the past (evaluated in the timezone you specify). IntervalValue must be greater than zero. The plan is scoped to your company — only users authorized for the same company can manage it.

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"
}

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*

* You must provide at least one of SenderSynchProfileId or PhoneNumber.

Example request

{
  "SenderSynchProfileId": "6e8d9257-bd5f-45cf-8f29-6d0ae8a6d991"
}

Retrieving payer consents

Payers can list and inspect their consent records to see which recurring plans they are enrolled in.

List consents

Returns payment plan consents for the authenticated user. Only consents with Pending or Accepted status are included — declined, canceled, and revoked consents are excluded from the list.

URL: https://api.synchpay.com/transaction/paymentplanconsent
Method: GET
Authorization: Bearer <UserToken>

Response

{
  "Consents": [
    {
      "Id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "PaymentPlanId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
      "RecipientName": "Acme Dental",
      "Amount": {
        "Value": 5000,
        "CurrencyCode": "USD"
      },
      "IntervalValue": 1,
      "IntervalUnit": "Month",
      "NextDueDate": "2026-05-01",
      "Status": "Accepted"
    }
  ]
}

Returns details for a specific consent, including its current status.

URL: https://api.synchpay.com/transaction/paymentplanconsent/{paymentPlanConsentId}
Method: GET
Authorization: Bearer <UserToken>

Response

{
  "Id": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "PaymentPlanId": "d4e5f6a7-b8c9-0123-4567-89abcdef0123",
  "RecipientCompanyId": "0bba248e-2d4b-4666-bf04-dd3c65c8fc03",
  "RecipientCompany": {
    "Name": "Acme Dental",
    "ContactNumber": "+15559876543",
    "EmailAddress": "billing@acmedental.com",
    "FeeMultiplier": null,
    "WebsiteUrl": "https://acmedental.com",
    "Address": {
      "StreetNumberAndName": "456 Oak Ave",
      "ApartmentNumber": null,
      "City": "Springfield",
      "ZipCode": "62704",
      "State": "IL",
      "Country": "US"
    }
  },
  "Amount": {
    "Value": 5000,
    "CurrencyCode": "USD"
  },
  "IntervalValue": 1,
  "IntervalUnit": "Month",
  "NextDueDate": "2026-05-01",
  "Status": "Accepted"
}

These fields are shared by both the list and single-consent endpoints:

Field	Type	Description
`Id`	string	Unique identifier for the consent record.
`PaymentPlanId`	string	The payment plan this consent belongs to.
`Amount`	object	Recurring payment amount. Contains `Value` (integer, in cents) and `CurrencyCode`.
`IntervalValue`	integer	Number of time units between each payment.
`IntervalUnit`	string	Time unit for recurrence (`Day`, `Week`, `Month`, `Quarter`, or `Year`).
`NextDueDate`	string	The next scheduled payment date in `YYYY-MM-DD` format.
`Status`	string	Current consent status. See consent statuses.

The list endpoint includes a summary field for the recipient:

Field	Type	Description
`RecipientName`	string	Display name of the company receiving payments.

The single-consent endpoint includes full company details:

Field	Type	Description
`RecipientCompanyId`	string	Unique identifier of the company receiving payments.
`RecipientCompany`	object	Full details of the company receiving payments. See fields below.

RecipientCompany fields

Field	Type	Description
`Name`	string	Company display name.
`ContactNumber`	string	Company phone number. May be `null`.
`EmailAddress`	string	Company email address.
`FeeMultiplier`	number	Fee multiplier applied to payments. May be `null`.
`WebsiteUrl`	string	Company website URL. May be `null`.
`Address`	object	Company address. Contains `StreetNumberAndName`, `ApartmentNumber`, `City`, `ZipCode`, `State`, and `Country`.

Payers can respond to a consent request using these endpoints:

Action	Method	URL
Accept	`POST`	`/transaction/paymentplanconsent/{paymentPlanConsentId}/accept`
Decline	`POST`	`/transaction/paymentplanconsent/{paymentPlanConsentId}/decline`

Both endpoints require Bearer <UserToken> authorization. The decline endpoint handles both pending and accepted consents:

Pending consent — moves to Declined. The payer is rejecting the consent request.
Accepted consent — moves to Revoked. The payer is withdrawing from a previously accepted plan.

You don’t need to call a separate revoke endpoint. The decline action automatically determines the correct resulting status based on the consent’s current state.

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.

Payer experience in the mobile app

When you create a consent record through the API, the payer receives a push notification prompting them to review the recurring payment request. Here is what happens on their end: The payer opens the notification and sees a consent request screen that displays:

The recurring amount and frequency (for example, “$50.00/mo”)
The date of the first scheduled payment
The bank account the payment will be drawn from
The name and details of the requesting company

The payer slides to accept the recurring payment or navigates back to decline it. You can share a direct link that takes a payer straight to the consent review screen. The link format is:

https://synchpay.com/RecurringPayment/{planConsentId}

Replace {planConsentId} with the consent ID returned when you add payer consent. When the payer opens the link:

If they have the SynchPay mobile app installed, the link opens the app directly to the consent request screen (via universal links on iOS and app links on Android).
If they open the link in a browser, the web app loads the consent request screen.
If the payer is not logged in, they are prompted to log in first and then redirected to the consent request.

Direct links are useful when you want to send consent requests through your own communication channels (for example, email, SMS, or in-app messages) instead of relying solely on push notifications.

Upcoming payments on the Payments tab

After a payer accepts a recurring plan, their Payments tab shows an Upcoming section at the bottom of the unpaid payments list. Each upcoming recurring payment displays the recipient name, the next due date, and the amount. Tapping an upcoming payment opens a detail sheet where the payer can cancel the recurring plan.

Managing recurring payments from the Profile

Payers who have active recurring payment consents see a Recurring payments card on their Profile screen. Tapping it opens a list of all active plans with the recipient name, amount, and frequency. The payer can select any plan to cancel it.

When a payer cancels a recurring payment from the app, the consent moves to Revoked status. You receive the updated consent status through the API when you query the consent list or individual consent endpoints.

Filtering by frequency

The Payments tab includes a Frequency filter that lets payers categorize their payments into:

One-time — single payments
Irregular — occasional payments without a fixed schedule
Subscriptions — payments that recur at a regular frequency

This helps payers distinguish between one-off charges and ongoing recurring plans.

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 first payment’s due date is the plan’s StartDate. Each subsequent due date is calculated by adding the configured interval to the previous payment’s due date.
SynchPay generates one payment at a time per consent. The next payment is created only after the current one’s due date has passed.
If the due date falls on the current day and the payer has a valid debit authorization, SynchPay attempts to process the payment immediately.
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.

Get Started

Authorization

Companies

Users

Payments

Reporting

Webhooks

Demo Videos

Changelog

Recurring payment plans

Overview

How it works

Payment plan lifecycle

Status transitions

Frequency options

Creating a payment plan

Endpoint

Request body

Example request

Response

Endpoint

Path parameters

Request body

Example request

Retrieving payer consents

List consents

Response

Response

RecipientCompany fields

Managing a payment plan

Payer experience in the mobile app

Upcoming payments on the Payments tab

Managing recurring payments from the Profile

Filtering by frequency

Autopay and debit authorization

Payment generation

Get Started

Authorization

Companies

Users

Payments

Reporting

Webhooks

Demo Videos

Changelog

Documentation Index

​Overview

​How it works

​Payment plan lifecycle

​Status transitions

​Frequency options

​Payer consent

​Consent statuses

​Consent status transitions

​Creating a payment plan

​Endpoint

​Request body

​Example request

​Response

​Adding payer consent

​Endpoint

​Path parameters

​Request body

​Example request

​Retrieving payer consents

​List consents

​Response

​Get a single consent

​Response

​Consent response fields

​RecipientCompany fields

​Accept or decline a consent

​Managing a payment plan

​Payer experience in the mobile app

​Reviewing a consent request

​Direct links for consent requests

​Upcoming payments on the Payments tab

​Managing recurring payments from the Profile

​Filtering by frequency

​Autopay and debit authorization

​Payment generation

Overview

How it works

Payment plan lifecycle

Status transitions

Frequency options

Payer consent

Consent statuses

Consent status transitions

Creating a payment plan

Endpoint

Request body

Example request

Response

Adding payer consent

Endpoint

Path parameters

Request body

Example request

Retrieving payer consents

List consents

Response

Get a single consent

Response

Consent response fields

RecipientCompany fields

Accept or decline a consent

Managing a payment plan

Payer experience in the mobile app

Reviewing a consent request

Direct links for consent requests

Upcoming payments on the Payments tab

Managing recurring payments from the Profile

Filtering by frequency

Autopay and debit authorization

Payment generation