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
direct-integration-api-reference.json
direct-integration-api-reference.yaml
Languages
Servers
Mock server
https://developer.adfin.com/_mock/products/direct-integration/direct-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

Retrieve a recurring invoice

Request

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

Responses

OK

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": [
    { … }
  ]
}

Update a recurring invoice

Request

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

The Adfin ID of the recurring invoice

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"}
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}]}
curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/schedules/invoices/{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"
    },
    "invoiceDetails": {
      "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
        }
      ]
    }
  }'

Responses

The request has succeeded and has resulted in one recurring invoice 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 invoice

Request

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

The Adfin ID of the recurring invoice to be deleted

curl -i -X DELETE \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/schedules/invoices/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The recurring invoice was deleted

Cancel a recurring invoice

Request

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

The Adfin ID of the recurring invoice

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/schedules/invoices/{id}:cancel' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The recurring invoice has been cancelled

Activate a recurring invoice

Request

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

The Adfin ID of the recurring invoice

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/schedules/invoices/{id}:activate' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The recurring invoice has been activated

Create a recurring invoice

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

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}]}
invoiceDetails.​customerobject(CustomerDetails)required

Contains the unique identifier for the customer.

Example: {"id":"80349480-490b-4234-92e7-fad697e3d446"}
invoiceDetails.​customer.​idstringrequired

The Adfin ID of the customer.

Example: "80349480-490b-4234-92e7-fad697e3d446"
invoiceDetails.​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}
invoiceDetails.​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}
invoiceDetails.​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"
invoiceDetails.​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"
invoiceDetails.​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!"
invoiceDetails.​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
invoiceDetails.​descriptionstring

A short summary or purpose of the invoice. Appears in both the invoice document and customer communications.

Example: "Monthly subscription for January"
invoiceDetails.​currencyCodestringrequired

The three-letter ISO 4217 currency code (e.g., GBP, EUR, USD). Indicates the currency in which the invoice is issued.

Example: "GBP"
invoiceDetails.​itemsTaxTypestringrequired

Defines how tax is applied to the invoice line items.

Possible values:

  • INCLUSIVE: Tax is included in item prices.
  • EXCLUSIVE: Tax is added on top of item prices.
  • NONE: No tax applied.
Example: "INCLUSIVE"
invoiceDetails.​itemsArray of objects(NewLineItemRequest)required

The list of line items included in the invoice. Each item represents a product, service, or fee with its own amount and tax configuration.

Example: [{"description":"Pro Plan Subscription","unitAmount":5000,"quantity":1,"taxRate":0.1}]
invoiceDetails.​items[].​descriptionstring

The description of the item.

invoiceDetails.​items[].​quantitynumber

The quantity of items.

invoiceDetails.​items[].​unitAmountnumber

The price per unit of the item.

invoiceDetails.​items[].​taxRatenumber

The tax rate percentage applied on the line item amount (quantity * unit amount).

invoiceDetails.​items[].​taxRateIdstring

Tax rate id for this line item. Use the Tax Rates API to manage your tax rates.

Example: "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6"
invoiceDetails.​items[].​accountCodeIdstring

Sales account id for this line item. If you require specific sales accounts to be used, provide the account code id here. To recieve your account codes, contact support@adfin.com

invoiceDetails.​items[].​productIdstring

The base product id for this line item. Use the Items catalog API to manage your products.

Example: "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6"
curl -i -X POST \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/schedules/invoices \
  -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"
    },
    "invoiceDetails": {
      "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
        }
      ]
    }
  }'

Responses

The request was successful and the recurring invoice was created

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": [
    { … }
  ]
}

Payment requests

Operations

Recurring payment requests

Operations

Payments

Operations

Tax rates

Operations

Items

Operations

Workflows

Operations

Webhooks

Operations