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

Webhooks

Operations

Retrieve a webhook

Request

Security
Platform Bearer Token
Path
clientIdstringrequired

The application identifier

webhookIdstringrequired

The webhook identifier

curl -i -X GET \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/apps/{clientId}/webhooks/{webhookId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The details of an existing webhook

Bodyapplication/json
idstring

The identifier of the webhook

clientIdstring

The identifier of the application

urlstring

The target URL of the webhook

namestring

Name of the webhook

descriptionstring

Description of the webhook

eventsArray of strings

The list of event types to trigger webhook instantiation

enabledboolean

The state of the webhook

creationTimestring(date-time)

The creation timestamp of the webhook

lastUpdatedTimestring(date-time)

The last updated timestamp of the webhook

Response
application/json
{
  "id": "string",
  "clientId": "string",
  "url": "string",
  "name": "string",
  "description": "string",
  "events": [
    "string"
  ],
  "enabled": true,
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z"
}

Update a webhook

Request

Security
Platform Bearer Token
Path
clientIdstringrequired

The application identifier

webhookIdstringrequired

The webhook identifier

Bodyapplication/jsonrequired
urlstring

The url of the webhook target.

Example: "https://hooks.example.com/adfin/webhooks"
eventsArray of strings

The list of events to subscribe.

Example: ["invoice","dd-mandate"]
namestring

The name of the webhook.

Example: "Adfin Events"
descriptionstring

The description of the webhook.

Example: "Triggers for invoice lifecycle events."
enabledboolean

The state of the webhook configuration.

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/apps/{clientId}/webhooks/{webhookId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://hooks.example.com/adfin/webhooks",
    "events": [
      "invoice",
      "dd-mandate"
    ],
    "name": "Adfin Events",
    "description": "Triggers for invoice lifecycle events.",
    "enabled": true
  }'

Responses

The updated webhook

Bodyapplication/json
idstring

The identifier of the webhook

clientIdstring

The identifier of the application

urlstring

The target URL of the webhook

namestring

Name of the webhook

descriptionstring

Description of the webhook

eventsArray of strings

The list of event types to trigger webhook instantiation

enabledboolean

The state of the webhook

creationTimestring(date-time)

The creation timestamp of the webhook

lastUpdatedTimestring(date-time)

The last updated timestamp of the webhook

Response
application/json
{
  "id": "string",
  "clientId": "string",
  "url": "string",
  "name": "string",
  "description": "string",
  "events": [
    "string"
  ],
  "enabled": true,
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z"
}

Delete a webhook

Request

Security
Platform Bearer Token
Path
clientIdstringrequired

The application identifier

webhookIdstringrequired

The webhook identifier

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

Responses

The webhook has been deleted

Generate or replace the webhook signing secret key

Request

Security
Platform Bearer Token
Path
clientIdstringrequired

The application identifier

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/apps/{clientId}/webhooks/digest' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The generated secret key

Bodyapplication/json
secretKeystring
Response
application/json
{
  "secretKey": "string"
}

Create or update the authentication method and credentials for webhook target URLs

Request

Security
Platform Bearer Token
Path
clientIdstringrequired

The application identifier

Bodyapplication/jsonrequired
basicAuthenticationobject(BasicAuthentication)

Basic authentication credentials used for the webhook invocations.

apiKeyAuthenticationobject(ApiKeyAuthentication)

API Key used for the webhook invocations authentication.

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/apps/{clientId}/webhooks/auth' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "basicAuthentication": {
      "username": "string",
      "password": "string"
    },
    "apiKeyAuthentication": {
      "headerKey": "string",
      "headerValue": "string"
    }
  }'

Responses

The authentication method and details have been stored

Retrieve webhooks for a clientId

Request

Security
Platform Bearer Token
Path
clientIdstringrequired

The application identifier

curl -i -X GET \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/apps/{clientId}/webhooks' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

A list of existing webhooks

Bodyapplication/json
webhooksResponseArray of objects(WebhookResponse)

The list of webhooks for an application identifier.

Response
application/json
{
  "webhooksResponse": [
    { … }
  ]
}

Create a webhook

Request

Security
Platform Bearer Token
Path
clientIdstringrequired

The application identifier

Bodyapplication/jsonrequired
urlstring

The url of the webhook target.

Example: "https://hooks.example.com/adfin/webhooks"
eventsArray of strings

The list of events to subscribe.

Example: ["invoice","dd-mandate"]
namestring

The name of the webhook.

Example: "Adfin Events"
descriptionstring

The description of the webhook.

Example: "Triggers for invoice lifecycle events."
curl -i -X POST \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/apps/{clientId}/webhooks' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://hooks.example.com/adfin/webhooks",
    "events": [
      "invoice",
      "dd-mandate"
    ],
    "name": "Adfin Events",
    "description": "Triggers for invoice lifecycle events."
  }'

Responses

The created webhook

Bodyapplication/json
idstring

The identifier of the webhook

clientIdstring

The identifier of the application

urlstring

The target URL of the webhook

namestring

Name of the webhook

descriptionstring

Description of the webhook

eventsArray of strings

The list of event types to trigger webhook instantiation

enabledboolean

The state of the webhook

creationTimestring(date-time)

The creation timestamp of the webhook

lastUpdatedTimestring(date-time)

The last updated timestamp of the webhook

Response
application/json
{
  "id": "string",
  "clientId": "string",
  "url": "string",
  "name": "string",
  "description": "string",
  "events": [
    "string"
  ],
  "enabled": true,
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z"
}