# Create a recurring payment request

Endpoint: POST /schedules/payment_requests
Version: 1.0.0
Security: Biller Access Token (Staging), Biller Access Token (Production)

## Request fields (application/json):

  - `cadence` (object, required)
    A cadence that recurs at a fixed interval.
Use this to define schedules that repeat every N units of time,
such as "every 2 weeks" or "every 3 months".
    Example: {"timeUnit":"WEEKS","frequency":2,"startDate":"2025-01-01T00:00:00Z","endDate":"2025-12-31T23:59:59Z"}

  - `cadence.timeUnit` (string, required)
    Determines whether the cadence repeats in weeks, months or years.
Common values:
- WEEKS
- MONTHS
- YEARS
    Example: "WEEKS"

  - `cadence.frequency` (integer, required)
    Combined with timeUnit to determine how often the cadence occurs.
For example:
- frequency = 2 and timeUnit = WEEKS → every 2 weeks
- frequency = 1 and timeUnit = MONTHS → every month
    Example: 2

  - `cadence.startDate` (string, required)
    The first occurrence happens at this time.
    Example: "2025-01-01T00:00:00Z"

  - `cadence.endDate` (string)
    Optional end date for the cadence.
If provided, the generation stops at or before this date.
If omitted, the cadence continues indefinitely.
    Example: "2025-12-31T23:59:59Z"

  - `paymentRequestDetails` (object, required)
    Defines the configuration for a Payment Request (PR) automatically generated.

This object specifies the customer, collection workflow, currency, payment terms for the payment requests.
    Example: {"customer":{"id":"80349480-490b-4234-92e7-fad697e3d446"},"paymentTerm":{"timeUnit":"DAYS","value":30},"distribution":{"collectionMethod":"AUTO_COLLECT","templateId":"dc9c7c6e-4c12-4cc9-8d22-20c5b2a7f8f7","customMessage":"Please review and confirm payment.","approvedForSending":true},"amount":1200,"taxRate":20,"currencyCode":"GBP","description":"Quarterly service fee","reference":"Q1-2025"}

  - `paymentRequestDetails.customer` (object, required)
    Contains the unique identifier for the customer.
    Example: {"id":"80349480-490b-4234-92e7-fad697e3d446"}

  - `paymentRequestDetails.customer.id` (string, required)
    The Adfin ID of the customer.
    Example: "80349480-490b-4234-92e7-fad697e3d446"

  - `paymentRequestDetails.paymentTerm` (object)
    Defines the duration before an invoice is due, using a combination of a time unit and value.
For example, a value of 30 with a timeUnit of DAYS represents "net 30 days".
    Example: {"timeUnit":"DAYS","value":30}

  - `paymentRequestDetails.paymentTerm.timeUnit` (string)
    The unit of time for the payment term.
Common values include:
- DAYS
- WEEKS
- MONTHS

Optional. Defaults to DAYS if not provided.
. 
Possible values (non-exclusive): SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR
    Example: "DAYS"

  - `paymentRequestDetails.paymentTerm.value` (integer)
    The numeric value of the payment term.
Combined with timeUnit to calculate due dates.
    Example: 30

  - `paymentRequestDetails.distribution` (object, required)
    Information about how an invoice or payment request is distributed and collected.

This defines:
- The method by which payment is expected to be collected.
- The workflow template used to send the invoice or payment request.
- Optional custom message for the customer.
- Approval status for automatically distributing to the customer.
    Example: {"collectionMethod":"AUTO_COLLECT","templateId":"d290f1ee-6c54-4b01-90e6-d701748f0851","customMessage":"Thank you for your business!","approvedForSending":true}

  - `paymentRequestDetails.distribution.collectionMethod` (string)
    How the payment is expected to be collected.
For example:
- AUTO_COLLECT: Collected automatically via direct debit.
- ON_DEMAND: Collected via other payment methods (eg. CARD, APPLE_PAY, GOOGLE_PAY, BANK).
- NONE: No payment collection is initiated automatically.
. 
Possible values (non-exclusive): AUTO_COLLECT, ON_DEMAND, NONE
    Example: "AUTO_COLLECT"

  - `paymentRequestDetails.distribution.templateId` (string)
    The workflow template ID used for sending the invoice or payment request to the customer.
Optional — if null, the system default template will be used.
    Example: "d290f1ee-6c54-4b01-90e6-d701748f0851"

  - `paymentRequestDetails.distribution.customMessage` (string)
    An optional message that will be sent to the customer when the invoice or payment request is distributed.
Can be used for personalized greetings or additional instructions.
    Example: "Thank you for your business!"

  - `paymentRequestDetails.distribution.approvedForSending` (boolean, required)
    Boolean flag specifying whether the invoice or payment request is approved for sending.
Defaults to true if not explicitly set.
    Example: true

  - `paymentRequestDetails.amount` (number, required)
    The total amount to be collected for each of the payment requests generated.
    Example: 1200

  - `paymentRequestDetails.taxRate` (number)
    The INCLUSIVE tax rate (%) applied to the payment request.
    Example: 20

  - `paymentRequestDetails.currencyCode` (string, required)
    The three-letter ISO 4217 currency code (e.g., GBP, EUR, USD).
Indicates the currency in which the payment request is issued.
    Example: "GBP"

  - `paymentRequestDetails.description` (string)
    A short, description of the payment request.
    Example: "Quarterly service fee"

  - `paymentRequestDetails.reference` (string)
    An optional reference or identifier that links this payment request
to another system or document.
    Example: "Q1-2025"

## Response 201 fields (application/json):

  - `id` (string)
    The Adfin ID of the recurring payment request.
    Example: "1"

  - `recurringPaymentRequestNo` (string)
    A system-generated, unique identifier for the recurring payment request.
Automatically created using the prefix SCH followed by a numeric sequence (e.g., SCH-1, SCH-2, ...).
    Example: "SCH-42"

  - `nextDate` (string)
    The next date a new payment request will be generated.
    Example: "2025-10-15T00:00:00Z"

  - `status` (string)
    Indicates the current status of the recurring payment request.
Possible values might include:
- ACTIVE – currently generating new payment request
- FINISHED – has finished all planned occurrences
- CANCELLED – has been cancelled before finishing all planned occurrences
    Example: "ACTIVE"

  - `cadence` (object)
    A cadence that recurs at a fixed interval.
Use this to define schedules that repeat every N units of time,
such as "every 2 weeks" or "every 3 months".
    Example: {"timeUnit":"WEEKS","frequency":2,"startDate":"2025-01-01T00:00:00Z","endDate":"2025-12-31T23:59:59Z"}

  - `cadence.timeUnit` (string, required)
    Determines whether the cadence repeats in weeks, months or years.
Common values:
- WEEKS
- MONTHS
- YEARS
    Example: "WEEKS"

  - `cadence.frequency` (integer, required)
    Combined with timeUnit to determine how often the cadence occurs.
For example:
- frequency = 2 and timeUnit = WEEKS → every 2 weeks
- frequency = 1 and timeUnit = MONTHS → every month
    Example: 2

  - `cadence.startDate` (string, required)
    The first occurrence happens at this time.
    Example: "2025-01-01T00:00:00Z"

  - `cadence.endDate` (string)
    Optional end date for the cadence.
If provided, the generation stops at or before this date.
If omitted, the cadence continues indefinitely.
    Example: "2025-12-31T23:59:59Z"

  - `paymentRequestDetails` (object)
    Defines the configuration for a Payment Request (PR) automatically generated.

This object specifies the customer, collection workflow, currency, payment terms for the payment requests.
    Example: {"customer":{"id":"80349480-490b-4234-92e7-fad697e3d446"},"paymentTerm":{"timeUnit":"DAYS","value":30},"distribution":{"collectionMethod":"AUTO_COLLECT","templateId":"dc9c7c6e-4c12-4cc9-8d22-20c5b2a7f8f7","customMessage":"Please review and confirm payment.","approvedForSending":true},"amount":1200,"taxRate":20,"currencyCode":"GBP","description":"Quarterly service fee","reference":"Q1-2025"}

  - `paymentRequestDetails.customer` (object, required)
    Contains the unique identifier for the customer.
    Example: {"id":"80349480-490b-4234-92e7-fad697e3d446"}

  - `paymentRequestDetails.customer.id` (string, required)
    The Adfin ID of the customer.
    Example: "80349480-490b-4234-92e7-fad697e3d446"

  - `paymentRequestDetails.paymentTerm` (object)
    Defines the duration before an invoice is due, using a combination of a time unit and value.
For example, a value of 30 with a timeUnit of DAYS represents "net 30 days".
    Example: {"timeUnit":"DAYS","value":30}

  - `paymentRequestDetails.paymentTerm.timeUnit` (string)
    The unit of time for the payment term.
Common values include:
- DAYS
- WEEKS
- MONTHS

Optional. Defaults to DAYS if not provided.
. 
Possible values (non-exclusive): SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR
    Example: "DAYS"

  - `paymentRequestDetails.paymentTerm.value` (integer)
    The numeric value of the payment term.
Combined with timeUnit to calculate due dates.
    Example: 30

  - `paymentRequestDetails.distribution` (object, required)
    Information about how an invoice or payment request is distributed and collected.

This defines:
- The method by which payment is expected to be collected.
- The workflow template used to send the invoice or payment request.
- Optional custom message for the customer.
- Approval status for automatically distributing to the customer.
    Example: {"collectionMethod":"AUTO_COLLECT","templateId":"d290f1ee-6c54-4b01-90e6-d701748f0851","customMessage":"Thank you for your business!","approvedForSending":true}

  - `paymentRequestDetails.distribution.collectionMethod` (string)
    How the payment is expected to be collected.
For example:
- AUTO_COLLECT: Collected automatically via direct debit.
- ON_DEMAND: Collected via other payment methods (eg. CARD, APPLE_PAY, GOOGLE_PAY, BANK).
- NONE: No payment collection is initiated automatically.
. 
Possible values (non-exclusive): AUTO_COLLECT, ON_DEMAND, NONE
    Example: "AUTO_COLLECT"

  - `paymentRequestDetails.distribution.templateId` (string)
    The workflow template ID used for sending the invoice or payment request to the customer.
Optional — if null, the system default template will be used.
    Example: "d290f1ee-6c54-4b01-90e6-d701748f0851"

  - `paymentRequestDetails.distribution.customMessage` (string)
    An optional message that will be sent to the customer when the invoice or payment request is distributed.
Can be used for personalized greetings or additional instructions.
    Example: "Thank you for your business!"

  - `paymentRequestDetails.distribution.approvedForSending` (boolean, required)
    Boolean flag specifying whether the invoice or payment request is approved for sending.
Defaults to true if not explicitly set.
    Example: true

  - `paymentRequestDetails.amount` (number, required)
    The total amount to be collected for each of the payment requests generated.
    Example: 1200

  - `paymentRequestDetails.taxRate` (number)
    The INCLUSIVE tax rate (%) applied to the payment request.
    Example: 20

  - `paymentRequestDetails.currencyCode` (string, required)
    The three-letter ISO 4217 currency code (e.g., GBP, EUR, USD).
Indicates the currency in which the payment request is issued.
    Example: "GBP"

  - `paymentRequestDetails.description` (string)
    A short, description of the payment request.
    Example: "Quarterly service fee"

  - `paymentRequestDetails.reference` (string)
    An optional reference or identifier that links this payment request
to another system or document.
    Example: "Q1-2025"

  - `creationTime` (string)
    The date and time when the recurring payment request was created.
    Example: "2025-09-27T12:00:00Z"

  - `lastUpdatedTime` (string)
    The date and time when the recurring payment request was last updated.
    Example: "2025-10-01T08:30:00Z"

  - `totalPaymentRequests` (integer)
    The total number of payment requests this recurring payment request is expected to generate
based on cadence, start date, and end date.
    Example: 10

  - `nextPaymentRequests` (array)
    A list of upcoming payment requests to be generated.
Ordered by index and date, and limited to a maximum of 12 items.

  - `nextPaymentRequests.index` (integer)
    The sequence number of this payment request within the schedule.

Starts from 1 for the first generated payment request and increments for each occurrence.
    Example: 3

  - `nextPaymentRequests.issueDate` (string)
    The date and time when the next payment request will be issued to the customer.
Determined by the cadence configuration.
    Example: "2025-11-01T00:00:00Z"

  - `nextPaymentRequests.payByDate` (string)
    The date and time when the payment request is due for payment.
Calculated based on the payment terms.
    Example: "2025-11-08T00:00:00Z"


## Response 400 fields

## Response 401 fields

## Response 422 fields

## Response 500 fields