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

Payment requests

Operations

Recurring payment requests

Operations

Payments

Operations

Tax rates

Operations

Items

Operations

Workflows

Operations

Create a new workflow

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
idstring

The internal identifier of the schedule. Required only for updates.

templateIdstring

The internal id of the template to be used for defining the schedule. Can be used in place of defining individual events for a schedule; in this case, the events will be automatically copied from the template. This streamlines the process and ensures consistency across schedules.

customerDetailsobject(CustomerDetails)

Contains the unique identifier for the customer.

Example: {"id":"80349480-490b-4234-92e7-fad697e3d446"}
invoiceDetailsobject(InvoiceDetails)

Invoice details response object.

namestring[ 0 .. 50 ] characters

The name of the schedule to be created for the customer. It must contain only alphanumeric characters, and be limited to a maximum of 50 characters.

typestringrequired

The type of the schedule to be created for the customer. Possible values (non-exclusive): ONE_TIME_PAYMENT, DD_MANDATE_AUTHORISATION, DD_PAYMENT, CUSTOMER_STATEMENT

customMessagestring

The (optional) custom message to be added to notification

eventsArray of objects(EventRequest)

A list of events that will occur as part of the schedule, applicable exclusively to a single customer

settingsobject(WorkflowSettingsRequest)

Optional workflow specific settings.

curl -i -X PUT \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/workflows \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "string",
    "templateId": "string",
    "customerDetails": {
      "id": "80349480-490b-4234-92e7-fad697e3d446"
    },
    "invoiceDetails": {
      "id": "string",
      "invoiceNo": "string",
      "description": "string",
      "totalAmount": "string",
      "taxAmount": "string",
      "dueAmount": "string",
      "creditNotesAmount": "string",
      "dueDate": "2019-08-24T14:15:22Z",
      "issueDate": "2019-08-24T14:15:22Z",
      "creationTime": "2019-08-24T14:15:22Z",
      "lastUpdatedTime": "2019-08-24T14:15:22Z",
      "paidTime": "2019-08-24T14:15:22Z",
      "status": "string",
      "statusReasonCode": "string",
      "statusReason": "string",
      "itemsTaxType": "string",
      "items": [
        {
          "id": "string",
          "description": "string",
          "quantity": 0,
          "unitAmount": 0,
          "taxRate": 0,
          "taxAmount": 0,
          "totalAmount": 0,
          "taxDetails": {
            "id": "string",
            "rate": 0
          },
          "accountDetails": {
            "id": "string",
            "code": "string"
          },
          "productDetails": {
            "id": "string",
            "code": "string"
          },
          "trackingGroupIds": [
            {
              "groupId": "string",
              "itemId": "string"
            }
          ],
          "externalData": [
            {
              "id": "string",
              "connectorType": "string",
              "templateId": "string",
              "accountCode": "string"
            }
          ]
        }
      ],
      "creditNotes": [
        {
          "id": "string",
          "number": "string",
          "amount": 0,
          "valueDate": "2019-08-24T14:15:22Z",
          "externalData": [
            {
              "connectorType": "string",
              "id": "string"
            }
          ]
        }
      ],
      "fileSource": "string",
      "invoiceSource": "string",
      "externalData": [
        {
          "connectorType": "string",
          "id": "string"
        }
      ]
    },
    "name": "string",
    "type": "string",
    "customMessage": "string",
    "events": [
      {
        "frequency": {
          "timeUnit": "string",
          "frequency": 0,
          "dayOfMonth": 0
        },
        "duration": {
          "startDate": "2019-08-24T14:15:22Z",
          "endDate": "2019-08-24T14:15:22Z",
          "maxNoOfExecutions": 0
        },
        "trigger": {
          "days": 0,
          "operator": "string",
          "referenceDate": "string"
        },
        "relativeDateTrigger": {
          "days": 0,
          "operator": "string",
          "referenceDate": "string"
        },
        "ordinalWeekdayTrigger": {
          "ordinal": 0,
          "dayOfWeek": "string"
        },
        "type": "string",
        "details": {}
      }
    ],
    "settings": {
      "customerStatementSettings": {
        "isEnabled": true
      }
    }
  }'

Responses

The request was successful, resulting in the creation of one workflow.

Bodyapplication/json
idstringrequired

The internal id of the workflow created

templateIdstring

The internal id of the template used to define the workflow. This template id has been utilized to automatically copy events into the instance, streamlining the process and ensuring consistency throughout

customerDetailsobject(CustomerDetails)

Contains the unique identifier for the customer.

Example: {"id":"80349480-490b-4234-92e7-fad697e3d446"}
invoiceDetailsobject(InvoiceDetails)

Invoice details response object.

namestring

The name of the workflow created for the customer

typestringrequired

Attribute that specifies the type of workflow. Possible values (non-exclusive): ONE_TIME_PAYMENT, DD_MANDATE_AUTHORISATION, DD_PAYMENT, CUSTOMER_STATEMENT

statestringrequired

The current state of the workflow. Possible values (non-exclusive): PENDING, ACTIVE, PAUSED, COMPLETED, TERMINATED

paymentInitiationDatestring(date-time)

The payment initiation date of Auto Collect workflows

creationTimestring(date-time)required

The creation time of the workflow

lastUpdatedTimestring(date-time)

Last time the workflow was updated

eventsArray of objects(EventResponse)

The list of events that will occur as part of the workflow, applicable exclusively to a single customer

settingsArray of objects(ReminderSettingsResponse)

The settings for reminders

workflowSettingsobject(WorkflowSettingsResponse)

Configuration settings related to schedule.

Response
application/json
{
  "id": "string",
  "templateId": "string",
  "customerDetails": {
    "id": "80349480-490b-4234-92e7-fad697e3d446"
  },
  "invoiceDetails": {
    "id": "string",
    "invoiceNo": "string",
    "description": "string",
    "totalAmount": "string",
    "taxAmount": "string",
    "dueAmount": "string",
    "creditNotesAmount": "string",
    "dueDate": "2019-08-24T14:15:22Z",
    "issueDate": "2019-08-24T14:15:22Z",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "paidTime": "2019-08-24T14:15:22Z",
    "status": "string",
    "statusReasonCode": "string",
    "statusReason": "string",
    "itemsTaxType": "string",
    "items": [ … ],
    "creditNotes": [ … ],
    "fileSource": "string",
    "invoiceSource": "string",
    "externalData": [ … ]
  },
  "name": "string",
  "type": "string",
  "state": "string",
  "paymentInitiationDate": "2019-08-24T14:15:22Z",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "events": [
    { … }
  ],
  "settings": [
    { … }
  ],
  "workflowSettings": {
    "reminderSettings": [ … ],
    "customerStatementSettings": { … }
  }
}

Webhooks

Operations