Skip to content

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 for Adfin's own integrations and system events. These tokens authenticate Adfin as the platform itself (not as a specific biller) and are required for endpoints like /api/webhook.

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

oAuth2

Operations

Biller

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/products/partner-integration/partner-integration-api-reference/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)

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"}
paymentRequestDetailsobject(RecurringPaymentRequestDetails)

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"}
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": "WEEKS",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00Z",
    "endDate": "2025-12-31T23:59:59Z"
  },
  "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)

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"}
paymentRequestDetailsobject(RecurringPaymentRequestDetails)

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"}
curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/partner-integration/partner-integration-api-reference/schedules/payment_requests/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cadence": {
      "timeUnit": "WEEKS",
      "frequency": 2,
      "startDate": "2025-01-01T00:00:00Z",
      "endDate": "2025-12-31T23:59:59Z"
    },
    "paymentRequestDetails": {
      "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"
    }
  }'

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)

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"}
invoiceDetailsobject(RecurringInvoiceDetails)

This defines the structure and configuration of invoices that will be automatically generated.

Example: {"customer":{"id":"80349480-490b-4234-92e7-fad697e3d446"},"paymentTerm":{"timeUnit":"DAYS","value":30},"distribution":{"collectionMethod":"AUTO_COLLECT","templateId":"d290f1ee-6c54-4b01-90e6-d701748f0851","customMessage":"Please find your invoice attached. Thank you for your business!","approvedForSending":true},"description":"Monthly subscription for January","currencyCode":"GBP","itemsTaxType":"INCLUSIVE","items":[{"description":"Pro Plan Subscription","unitAmount":5000,"quantity":1,"taxRate":0.1}]}
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": "WEEKS",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00Z",
    "endDate": "2025-12-31T23:59:59Z"
  },
  "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/products/partner-integration/partner-integration-api-reference/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/products/partner-integration/partner-integration-api-reference/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

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

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

  • WEEKS
  • MONTHS
  • YEARS
Example: "WEEKS"
cadence.​frequencyinteger(int32)>= 1required

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.​startDatestring(date-time)required

The first occurrence happens at this time.

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:59Z"
paymentRequestDetailsobject(RecurringPaymentRequestDetails)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.​customerobject(CustomerDetails)required

Contains the unique identifier for the customer.

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)

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.​distributionobject(CollectionDetails)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.​collectionMethodstring

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.​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: 1200
paymentRequestDetails.​taxRatenumber

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

Example: 20
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: "Quarterly service fee"
paymentRequestDetails.​referencestring

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

Example: "Q1-2025"
curl -i -X POST \
  https://developer.adfin.com/_mock/products/partner-integration/partner-integration-api-reference/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)

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"}
paymentRequestDetailsobject(RecurringPaymentRequestDetails)

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"}
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": "WEEKS",
    "frequency": 2,
    "startDate": "2025-01-01T00:00:00Z",
    "endDate": "2025-12-31T23:59:59Z"
  },
  "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": [
    { … }
  ]
}

Payments

Operations

Tax rates

Operations

Items

Operations

Workflows

Operations

Webhooks

Operations