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 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
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

Verifications

Operations

Customers

Operations

Direct debit mandates

Operations

Invoices

Operations

Recurring invoices

Operations

Payment requests

Operations

Recurring payment requests

Operations

Payments

Operations

Payouts

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)
invoiceDetailsobject(InvoiceDetails)
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

Enum"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)
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": "string",
      "name": "string"
    },
    "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": "DRAFT",
      "statusReasonCode": "MISSING_PAYER_CONTACT_DETAILS",
      "statusReason": "string",
      "itemsTaxType": "EXCLUSIVE",
      "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"
          },
          "externalData": [
            {
              "id": "string",
              "connectorType": "XERO",
              "templateId": "string",
              "accountCode": "string",
              "groupLineId": "string"
            }
          ],
          "trackingItems": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        }
      ],
      "creditNotes": [
        {
          "id": "string",
          "number": "string",
          "amount": 0,
          "valueDate": "2019-08-24T14:15:22Z",
          "externalData": [
            {
              "connectorType": "XERO",
              "id": "string"
            }
          ]
        }
      ],
      "fileSource": "NONE",
      "invoiceSource": "FILE_UPLOAD",
      "externalData": [
        {
          "connectorType": "XERO",
          "id": "string",
          "brandingThemeId": "string"
        }
      ]
    },
    "name": "string",
    "type": "ONE_TIME_PAYMENT",
    "customMessage": "string",
    "events": [
      {
        "frequency": {
          "timeUnit": "MONTH, WEEK, DAY",
          "frequency": 0,
          "dayOfMonth": 0
        },
        "duration": {
          "startDate": "2019-08-24T14:15:22Z",
          "endDate": "2019-08-24T14:15:22Z",
          "maxNoOfExecutions": 0
        },
        "trigger": {
          "days": 0,
          "operator": "ON",
          "referenceDate": "DUE_DATE"
        },
        "relativeDateTrigger": {
          "days": 0,
          "operator": "ON",
          "referenceDate": "DUE_DATE"
        },
        "ordinalWeekdayTrigger": {
          "ordinal": 0,
          "dayOfWeek": "string"
        },
        "type": "NO_ACTION",
        "details": null
      }
    ],
    "settings": {
      "customerStatementSettings": {
        "minOutstandingBalance": 0,
        "minOverdueDays": 0
      }
    }
  }'

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)
invoiceDetailsobject(InvoiceDetails)
namestring

The name of the workflow created for the customer

typestringrequired

Attribute that specifies the type of workflow

Enum"ONE_TIME_PAYMENT""DD_MANDATE_AUTHORISATION""DD_PAYMENT""CUSTOMER_STATEMENT"
statestringrequired

The current state of the workflow

Enum"DRAFT""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)
autopilotReasoningstring

The overall strategy reasoning provided by the LLM, present only for autopilot workflows

Response
application/json
{
  "id": "string",
  "templateId": "string",
  "customerDetails": {
    "id": "string",
    "name": "string"
  },
  "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": "DRAFT",
    "statusReasonCode": "MISSING_PAYER_CONTACT_DETAILS",
    "statusReason": "string",
    "itemsTaxType": "EXCLUSIVE",
    "items": [ … ],
    "creditNotes": [ … ],
    "fileSource": "NONE",
    "invoiceSource": "FILE_UPLOAD",
    "externalData": [ … ]
  },
  "name": "string",
  "type": "ONE_TIME_PAYMENT",
  "state": "DRAFT",
  "paymentInitiationDate": "2019-08-24T14:15:22Z",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "events": [
    { … }
  ],
  "settings": [
    { … }
  ],
  "workflowSettings": {
    "reminderSettings": [ … ],
    "customerStatementSettings": { … }
  },
  "autopilotReasoning": "string"
}

Activities

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

Operations

Scheduled Activities

Operations

Webhooks

Operations