Skip to content
/
Retrieve a recurring paym...

Adfin API (1.0.0)

Adfin uses OAuth 2.0 access tokens to authenticate all API requests.

There are two contexts in which tokens are issued:

  • Biller Access Tokens — Generated via the Authorization Code flow when a biller connects their Adfin account. These tokens grant access to that biller's data (invoices, payment requests, customers, etc.).

  • Platform Access Tokens — Generated via the Client Credentials flow when a platform authenticates as itself rather than as one of its billers. A platform uses one to manage its own webhook subscriptions under /api/apps/{clientId}/webhooks.

Download OpenAPI description
prod.json
prod.yaml
Languages
Servers
Mock server
https://developer.adfin.com/_mock/api-docs/prod/
Production API Server URL
https://api.adfin.com/api/
Staging API Server URL
https://api.staging.adfin.com/api/

oAuth2

Operations

Biller

Operations

Verifications

Operations

Customers

Operations

Direct debit mandates

Operations

Invoices

Operations

Recurring invoices

Operations

Payment requests

Operations

Recurring payment requests

Operations

Retrieve a recurring payment request by its ID

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired
curl -i -X GET \
  'https://developer.adfin.com/_mock/api-docs/prod/schedules/payment_requests/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

OK

Bodyapplication/json
idstring

The Adfin ID of the recurring payment request.

Example: "1"
recurringPaymentRequestNostring

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"
nextDatestring(date-time)

The next date a new payment request will be generated.

Example: "2025-10-15T00:00:00Z"
statusstring

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"
cadenceobject(IntervalCadence)
paymentRequestDetailsobject(RecurringPaymentRequestDetails)
creationTimestring(date-time)

The date and time when the recurring payment request was created.

Example: "2025-09-27T12:00:00Z"
lastUpdatedTimestring(date-time)

The date and time when the recurring payment request was last updated.

Example: "2025-10-01T08:30:00Z"
totalPaymentRequestsinteger(int32)

The total number of payment requests this recurring payment request is expected to generate based on cadence, start date, and end date.

Example: 10
nextPaymentRequestsArray of objects(NextPaymentRequestResponse)

A list of upcoming payment requests to be generated. Ordered by index and date, and limited to a maximum of 12 items.

Response
application/json
{
  "id": "1",
  "recurringPaymentRequestNo": "SCH-42",
  "nextDate": "2025-10-15T00:00:00Z",
  "status": "ACTIVE",
  "cadence": {
    "timeUnit": "WEEK",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-12-31T23:59:59.000Z"
  },
  "paymentRequestDetails": {
    "customer": { … },
    "paymentTerm": { … },
    "distribution": { … },
    "amount": 1200,
    "taxRate": 20,
    "currencyCode": "GBP",
    "description": "Quarterly service fee",
    "reference": "Q1-2025"
  },
  "creationTime": "2025-09-27T12:00:00Z",
  "lastUpdatedTime": "2025-10-01T08:30:00Z",
  "totalPaymentRequests": 10,
  "nextPaymentRequests": [
    { … }
  ]
}

Update a recurring payment request

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired

The Adfin ID of the recurring payment request

Bodyapplication/jsonrequired
cadenceobject(IntervalCadence)
paymentRequestDetailsobject(RecurringPaymentRequestDetails)
curl -i -X PUT \
  'https://developer.adfin.com/_mock/api-docs/prod/schedules/payment_requests/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cadence": {
      "timeUnit": "WEEK",
      "frequency": 2,
      "startDate": "2025-01-01T00:00:00.000Z",
      "endDate": "2025-12-31T23:59:59.000Z"
    },
    "paymentRequestDetails": {
      "customer": {
        "id": "80349480-490b-4234-92e7-fad697e3d446"
      },
      "paymentTerm": {
        "timeUnit": "DAY",
        "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"
    }
  }'

Responses

The request has succeeded and has resulted in one recurring payment request being updated

Bodyapplication/json
idstring

The Adfin ID of the recurring invoice.

Example: "1"
recurringInvoiceNostring

A system-generated, unique identifier for the recurring invoice. Automatically created using the prefix SCH followed by a numeric sequence (e.g., SCH-1, SCH-2, ...).

Example: "SCH-42"
nextIssueDatestring(date-time)

The next date a new invoice will be automatically generated.

Example: "2025-10-15T00:00:00Z"
statusstring

Indicates the current status of the recurring invoice. Possible values might include:

  • DRAFT – currently not generating new invoices
  • ACTIVE – currently generating new invoices
  • FINISHED – has finished all planned occurrences
  • CANCELLED – has been cancelled before finishing all planned occurrences
Example: "ACTIVE"
cadenceobject(IntervalCadence)
invoiceDetailsobject(RecurringInvoiceDetails)
creationTimestring(date-time)

The date and time when the recurring invoice was created.

Example: "2025-09-27T12:00:00Z"
lastUpdatedTimestring(date-time)

The date and time when the recurring invoice was last updated.

Example: "2025-10-01T08:30:00Z"
totalInvoicesinteger(int32)

The total number of invoices this recurring invoice is expected to generate based on cadence, start date, and end date.

Example: 10
amountnumber

The total amount of the recurring invoice. Calculated based on the sum of all invoice line items across all occurrences.

Example: 1234.5
nextInvoicesArray of objects(NextInvoiceResponse)

A list of upcoming invoices to be generated. Ordered by index and date, and limited to a maximum of 12 items.

Response
application/json
{
  "id": "1",
  "recurringInvoiceNo": "SCH-42",
  "nextIssueDate": "2025-10-15T00:00:00Z",
  "status": "ACTIVE",
  "cadence": {
    "timeUnit": "WEEK",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-12-31T23:59:59.000Z"
  },
  "invoiceDetails": {
    "customer": { … },
    "paymentTerm": { … },
    "distribution": { … },
    "description": "Monthly subscription for January",
    "currencyCode": "GBP",
    "itemsTaxType": "INCLUSIVE",
    "items": [ … ]
  },
  "creationTime": "2025-09-27T12:00:00Z",
  "lastUpdatedTime": "2025-10-01T08:30:00Z",
  "totalInvoices": 10,
  "amount": 1234.5,
  "nextInvoices": [
    { … }
  ]
}

Delete a recurring payment request

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired

The Adfin ID of the recurring payment request to be deleted

curl -i -X DELETE \
  'https://developer.adfin.com/_mock/api-docs/prod/schedules/payment_requests/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The recurring payment request was deleted

Cancel a recurring payment request

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired

The Adfin ID of the recurring payment request

curl -i -X PUT \
  'https://developer.adfin.com/_mock/api-docs/prod/schedules/payment_requests/{id}:cancel' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The recurring payment request has been cancelled

Create a recurring payment request

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
cadenceobject(IntervalCadence)required
Example: {"type":"INTERVAL","timeUnit":"MONTHS","frequency":1,"startDate":"2025-01-01T00:00:00Z"}
cadence.​timeUnitstringrequired

Determines whether the cadence repeats in weeks, months or years. Common values:

  • WEEK
  • MONTH
  • YEAR
Example: "MONTHS"
cadence.​frequencyinteger(int32)>= 1required

Combined with timeUnit to determine how often the cadence occurs. For example:

  • frequency = 2 and timeUnit = WEEK → every 2 weeks
  • frequency = 1 and timeUnit = MONTH → every month
Example: 1
cadence.​startDatestring(date-time)required

The first occurrence happens at this time. Format: ISO 8601 with milliseconds, e.g. 2025-01-01T00:00:00.000Z. Timestamps without milliseconds are rejected.

Example: "2025-01-01T00:00:00Z"
cadence.​endDatestring(date-time)

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:59.000Z"
paymentRequestDetailsobject(RecurringPaymentRequestDetails)required
Example: {"customer":{"id":"80349480-490b-4234-92e7-fad697e3d446"},"paymentTerm":{"timeUnit":"DAYS","value":30},"distribution":{"collectionMethod":"AUTO_COLLECT","templateId":"d290f1ee-6c54-4b01-90e6-d701748f0851","customMessage":"Thank you for your business!","approvedForSending":true},"amount":"10.00","taxRate":"0.1","currencyCode":"GBP","description":"Monthly subscription for January","reference":"PR-01"}
paymentRequestDetails.​customerobject(ScheduleCustomerDetails)required
Example: {"id":"80349480-490b-4234-92e7-fad697e3d446"}
paymentRequestDetails.​customer.​idstringrequired

The Adfin ID of the customer.

Example: "80349480-490b-4234-92e7-fad697e3d446"
paymentRequestDetails.​paymentTermobject(PaymentTerm)
Example: {"timeUnit":"DAYS","value":30}
paymentRequestDetails.​distributionobject(CollectionDetails)required
Example: {"collectionMethod":"AUTO_COLLECT","templateId":"d290f1ee-6c54-4b01-90e6-d701748f0851","customMessage":"Thank you for your business!","approvedForSending":true}
paymentRequestDetails.​distribution.​collectionMethodstring

How the payment is expected to be collected. For example:

  • AUTO_COLLECT: Collected automatically via direct debit. Takes effect once the customer has an active direct debit mandate; until they sign, collection waits with status reason PENDING_DD_MANDATE.
  • ON_DEMAND: Collected via other payment methods (eg. CARD, APPLE_PAY, GOOGLE_PAY, BANK).
  • NONE: No payment collection is initiated automatically.
Enum"AUTO_COLLECT""ON_DEMAND""NONE"
Example: "AUTO_COLLECT"
paymentRequestDetails.​distribution.​templateIdstring(uuid)

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.​customMessagestring

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.​approvedForSendingbooleanrequired

Boolean flag specifying whether the invoice or payment request is approved for sending. Defaults to true if not explicitly set.

Default true
Example: true
paymentRequestDetails.​amountnumberrequired

The total amount to be collected for each of the payment requests generated.

Example: "10.00"
paymentRequestDetails.​taxRatenumber

The INCLUSIVE tax rate (%) applied to the payment request.

Example: "0.1"
paymentRequestDetails.​currencyCodestringrequired

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.​descriptionstring

A short, description of the payment request.

Example: "Monthly subscription for January"
paymentRequestDetails.​referencestring

An optional reference or identifier that links this payment request to another system or document.

Example: "PR-01"
curl -i -X POST \
  https://developer.adfin.com/_mock/api-docs/prod/schedules/payment_requests \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cadence": {
      "type": "INTERVAL",
      "timeUnit": "MONTHS",
      "frequency": 1,
      "startDate": "2025-01-01T00:00:00Z"
    },
    "paymentRequestDetails": {
      "customer": {
        "id": "80349480-490b-4234-92e7-fad697e3d446"
      },
      "paymentTerm": {
        "timeUnit": "DAYS",
        "value": 30
      },
      "distribution": {
        "collectionMethod": "AUTO_COLLECT",
        "templateId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "customMessage": "Thank you for your business!",
        "approvedForSending": true
      },
      "amount": "10.00",
      "taxRate": "0.1",
      "currencyCode": "GBP",
      "description": "Monthly subscription for January",
      "reference": "PR-01"
    }
  }'

Responses

The request was successful and the recurring payment request was created

Bodyapplication/json
idstring

The Adfin ID of the recurring payment request.

Example: "1"
recurringPaymentRequestNostring

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"
nextDatestring(date-time)

The next date a new payment request will be generated.

Example: "2025-10-15T00:00:00Z"
statusstring

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"
cadenceobject(IntervalCadence)
paymentRequestDetailsobject(RecurringPaymentRequestDetails)
creationTimestring(date-time)

The date and time when the recurring payment request was created.

Example: "2025-09-27T12:00:00Z"
lastUpdatedTimestring(date-time)

The date and time when the recurring payment request was last updated.

Example: "2025-10-01T08:30:00Z"
totalPaymentRequestsinteger(int32)

The total number of payment requests this recurring payment request is expected to generate based on cadence, start date, and end date.

Example: 10
nextPaymentRequestsArray of objects(NextPaymentRequestResponse)

A list of upcoming payment requests to be generated. Ordered by index and date, and limited to a maximum of 12 items.

Response
application/json
{
  "id": "1",
  "recurringPaymentRequestNo": "SCH-42",
  "nextDate": "2025-10-15T00:00:00Z",
  "status": "ACTIVE",
  "cadence": {
    "timeUnit": "WEEK",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00.000Z",
    "endDate": "2025-12-31T23:59:59.000Z"
  },
  "paymentRequestDetails": {
    "customer": { … },
    "paymentTerm": { … },
    "distribution": { … },
    "amount": 1200,
    "taxRate": 20,
    "currencyCode": "GBP",
    "description": "Quarterly service fee",
    "reference": "Q1-2025"
  },
  "creationTime": "2025-09-27T12:00:00Z",
  "lastUpdatedTime": "2025-10-01T08:30:00Z",
  "totalPaymentRequests": 10,
  "nextPaymentRequests": [
    { … }
  ]
}

Get the collection preferences for a recurring payment request

Request

Returns how collection is set up for the payment requests this recurring payment request raises. The values in force, after the agent's settings and every override are resolved.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
recurringPaymentRequestIdstring(uuid)required

The identifier of the recurring payment request.

curl -i -X GET \
  'https://developer.adfin.com/_mock/api-docs/prod/schedules/payment_requests/{recurringPaymentRequestId}/collection_preferences' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The collection method and preferences in force.

Bodyapplication/json
collectionMethodstringrequired

The collection method in force.

Enum"AUTO_COLLECT""ON_DEMAND"
preferencesobject(CollectionPreferences)required
preferences.​paymentRemindersobject(PreferenceToggle)
preferences.​mandateRemindersobject(PreferenceToggle)
preferences.​cardRemindersobject(PreferenceToggle)
preferences.​directDebitEncouragementobject(PreferenceToggle)
preferences.​statementsobject(PreferenceToggle)
preferences.​lateFeesobject(LateFeesPreference)
preferences.​partialPaymentsobject(PartialPaymentsPreference)
preferences.​surchargingobject(PreferenceToggle)
Response
application/json
{
  "collectionMethod": "AUTO_COLLECT",
  "preferences": {
    "paymentReminders": { … },
    "mandateReminders": { … },
    "cardReminders": { … },
    "directDebitEncouragement": { … },
    "statements": { … },
    "lateFees": { … },
    "partialPayments": { … },
    "surcharging": { … }
  }
}

Reset the collection preferences for a recurring payment request

Request

Resets how collection is set up for the payment requests this recurring payment request raises. Clears every override, not only these settings, including any set by Adfin or in the Adfin app. To turn a single setting off, PATCH it with an enabled of false instead; a pause set with :pause_collection survives.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
recurringPaymentRequestIdstring(uuid)required

The identifier of the recurring payment request.

curl -i -X DELETE \
  'https://developer.adfin.com/_mock/api-docs/prod/schedules/payment_requests/{recurringPaymentRequestId}/collection_preferences' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The overrides held against the recurring payment request are cleared. A recurring payment request that holds none is left as it is.

Response
No content

Change the collection preferences for a recurring payment request

Request

Changes how collection is set up for the payment requests this recurring payment request raises. A field left out of the body is unchanged. partialPayments takes at most one of minimumAmount or minimumPercentage. statements, mandateReminders, cardReminders and directDebitEncouragement can only be set on the customer.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
recurringPaymentRequestIdstring(uuid)required

The identifier of the recurring payment request.

Bodyapplication/jsonrequired
collectionMethodstring

The collection method to use.

Enum"AUTO_COLLECT""ON_DEMAND"
preferencesobject(CollectionPreferences)
curl -i -X PATCH \
  'https://developer.adfin.com/_mock/api-docs/prod/schedules/payment_requests/{recurringPaymentRequestId}/collection_preferences' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collectionMethod": "AUTO_COLLECT",
    "preferences": {
      "paymentReminders": {
        "enabled": true
      },
      "mandateReminders": {
        "enabled": true
      },
      "cardReminders": {
        "enabled": true
      },
      "directDebitEncouragement": {
        "enabled": true
      },
      "statements": {
        "enabled": true
      },
      "lateFees": {
        "enabled": true,
        "gracePeriodDays": 0
      },
      "partialPayments": {
        "enabled": true,
        "minimumAmount": 0,
        "minimumPercentage": 0
      },
      "surcharging": {
        "enabled": true
      }
    }
  }'

Responses

The change was applied.

Response
No content

Payments

Operations

Payouts

Operations

Tax rates

Operations

Items

Operations

Activities

What has happened to a customer, invoice, payment request or schedule.

Operations

Scheduled Activities

What is planned next for a customer or a payment request.

Operations

Webhooks

Operations

Referrals

Operations