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

Retrieve a direct debit mandates by customer

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/customers/{id}/directdebitmandates' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The direct debit mandate attached to the customer with the given id.

Bodyapplication/json
mandatesArray of objects(DirectDebitMandateResponse)

The list of all direct debit mandates for the specified filter.

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

Create a direct debit mandate

Request

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

The id of the customer for whom to create the mandate

Bodyapplication/json
redirectUrlstring

The redirect URL to redirect the user after they sign the mandate

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/partner-integration/partner-integration-api-reference/customers/{id}/directdebitmandates' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "redirectUrl": "string"
  }'

Responses

The direct debit mandate was created

Bodyapplication/json
idstring

The ID of the mandate

creationTimestring(date-time)

The creation time of the mandate

lastUpdateTimestring(date-time)

The last time when the mandate was updated

distributionTimestring(date-time)

The time when the mandate was sent to the customer

authorisationTimestring(date-time)

The time when the mandate was signed by the customer

submissionTimestring(date-time)

The time when the mandate was submitted to the payment provider

statusstring

The mandate status

Enum"CREATED""PENDING""ACTIVE""CANCELLED""MIGRATING"
failureReasonstring

The reason for failing to set up the mandate

statusReasonCodestring

The reason as predefined code why the mandate is in a certain status

Enum"PENDING_DD_CAPABILITY""PENDING_ACTIVATION""MIGRATED""BANK_ACCOUNT_CHANGED""INCORRECT_BANK_DETAILS""INSTRUCTION_CANCELLED_BY_PAYER""PAYER_DECEASED""ACCOUNT_TRANSFERRED""ADVANCE_NOTICE_DISPUTED""AMOUNT_DISPUTED"
statusReasonstring

Reason explaining the current status of the direct debit mandate, especially useful for failure cases.

customerobject(CustomerResponse)
urlstring

The URL where the customer can sign the direct debit mandate.

redirectUrlstring

The (optional) redirect URL to redirect the user after they sign the mandate

senderobject(SenderResponse)
bankAccountNumberstring

The mandate bank account number

sortCodestring

The mandate sort code

bankAccountHolderNamestring

The mandate bank account holder name

Response
application/json
{
  "id": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdateTime": "2019-08-24T14:15:22Z",
  "distributionTime": "2019-08-24T14:15:22Z",
  "authorisationTime": "2019-08-24T14:15:22Z",
  "submissionTime": "2019-08-24T14:15:22Z",
  "status": "CREATED",
  "failureReason": "string",
  "statusReasonCode": "PENDING_DD_CAPABILITY",
  "statusReason": "string",
  "customer": {
    "id": "string",
    "externalId": "string",
    "name": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "people": [ … ],
    "addresses": [ … ],
    "directDebitMandate": { … },
    "billerBankAccount": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ],
    "status": "ACTIVE",
    "statusReasonCode": "MERGED",
    "settings": { … },
    "trackingItems": [ … ],
    "office": { … }
  },
  "url": "string",
  "redirectUrl": "string",
  "sender": {
    "name": "string"
  },
  "bankAccountNumber": "string",
  "sortCode": "string",
  "bankAccountHolderName": "string"
}

Reinstate a cancelled direct debit mandate

Request

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

Responses

The direct debit mandate was reinstated.

Bodyapplication/json
idstring

The ID of the mandate

creationTimestring(date-time)

The creation time of the mandate

lastUpdateTimestring(date-time)

The last time when the mandate was updated

distributionTimestring(date-time)

The time when the mandate was sent to the customer

authorisationTimestring(date-time)

The time when the mandate was signed by the customer

submissionTimestring(date-time)

The time when the mandate was submitted to the payment provider

statusstring

The mandate status

Enum"CREATED""PENDING""ACTIVE""CANCELLED""MIGRATING"
failureReasonstring

The reason for failing to set up the mandate

statusReasonCodestring

The reason as predefined code why the mandate is in a certain status

Enum"PENDING_DD_CAPABILITY""PENDING_ACTIVATION""MIGRATED""BANK_ACCOUNT_CHANGED""INCORRECT_BANK_DETAILS""INSTRUCTION_CANCELLED_BY_PAYER""PAYER_DECEASED""ACCOUNT_TRANSFERRED""ADVANCE_NOTICE_DISPUTED""AMOUNT_DISPUTED"
statusReasonstring

Reason explaining the current status of the direct debit mandate, especially useful for failure cases.

customerobject(CustomerResponse)
urlstring

The URL where the customer can sign the direct debit mandate.

redirectUrlstring

The (optional) redirect URL to redirect the user after they sign the mandate

senderobject(SenderResponse)
bankAccountNumberstring

The mandate bank account number

sortCodestring

The mandate sort code

bankAccountHolderNamestring

The mandate bank account holder name

Response
application/json
{
  "id": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdateTime": "2019-08-24T14:15:22Z",
  "distributionTime": "2019-08-24T14:15:22Z",
  "authorisationTime": "2019-08-24T14:15:22Z",
  "submissionTime": "2019-08-24T14:15:22Z",
  "status": "CREATED",
  "failureReason": "string",
  "statusReasonCode": "PENDING_DD_CAPABILITY",
  "statusReason": "string",
  "customer": {
    "id": "string",
    "externalId": "string",
    "name": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "people": [ … ],
    "addresses": [ … ],
    "directDebitMandate": { … },
    "billerBankAccount": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ],
    "status": "ACTIVE",
    "statusReasonCode": "MERGED",
    "settings": { … },
    "trackingItems": [ … ],
    "office": { … }
  },
  "url": "string",
  "redirectUrl": "string",
  "sender": {
    "name": "string"
  },
  "bankAccountNumber": "string",
  "sortCode": "string",
  "bankAccountHolderName": "string"
}

Cancel a direct debit mandate

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
idstringrequired
Bodyapplication/jsonrequired
reasonstring

The reason for cancelling a direct debit mandate

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/partner-integration/partner-integration-api-reference/customers/directdebitmandates/{id}:cancel' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "reason": "string"
  }'

Responses

The direct debit mandate was cancelled.

Search direct debit mandates by filters

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Query
customerIdstring(uuid)

The id of the customer associated to the direct debit mandate

statusesArray of strings

The status of the direct debit mandate

Items Enum"CREATED""PENDING""ACTIVE""CANCELLED""MIGRATING"
statusReasonCodesArray of strings

The reason code of the direct debit mandate status

Items Enum"PENDING_DD_CAPABILITY""PENDING_ACTIVATION""MIGRATED""BANK_ACCOUNT_CHANGED""INCORRECT_BANK_DETAILS""INSTRUCTION_CANCELLED_BY_PAYER""PAYER_DECEASED""ACCOUNT_TRANSFERRED""ADVANCE_NOTICE_DISPUTED""AMOUNT_DISPUTED"
canBeReinstatedboolean

Whether the mandate can be reinstated

curl -i -X GET \
  'https://developer.adfin.com/_mock/products/partner-integration/partner-integration-api-reference/customers/directdebitmandates?customerId=497f6eca-6276-4993-bfeb-53cbbbba6f08&statuses=CREATED&statusReasonCodes=PENDING_DD_CAPABILITY&canBeReinstated=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The mandates matching the provided filters.

Bodyapplication/json
mandatesArray of objects(DirectDebitMandateResponse)

The list of all direct debit mandates for the specified filter.

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

Retrieve a direct debit mandate

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/customers/directdebitmandates/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The direct debit mandate corresponding to the provided id.

Bodyapplication/json
idstring

The ID of the mandate

creationTimestring(date-time)

The creation time of the mandate

lastUpdateTimestring(date-time)

The last time when the mandate was updated

distributionTimestring(date-time)

The time when the mandate was sent to the customer

authorisationTimestring(date-time)

The time when the mandate was signed by the customer

submissionTimestring(date-time)

The time when the mandate was submitted to the payment provider

statusstring

The mandate status

Enum"CREATED""PENDING""ACTIVE""CANCELLED""MIGRATING"
failureReasonstring

The reason for failing to set up the mandate

statusReasonCodestring

The reason as predefined code why the mandate is in a certain status

Enum"PENDING_DD_CAPABILITY""PENDING_ACTIVATION""MIGRATED""BANK_ACCOUNT_CHANGED""INCORRECT_BANK_DETAILS""INSTRUCTION_CANCELLED_BY_PAYER""PAYER_DECEASED""ACCOUNT_TRANSFERRED""ADVANCE_NOTICE_DISPUTED""AMOUNT_DISPUTED"
statusReasonstring

Reason explaining the current status of the direct debit mandate, especially useful for failure cases.

customerobject(CustomerResponse)
urlstring

The URL where the customer can sign the direct debit mandate.

redirectUrlstring

The (optional) redirect URL to redirect the user after they sign the mandate

senderobject(SenderResponse)
bankAccountNumberstring

The mandate bank account number

sortCodestring

The mandate sort code

bankAccountHolderNamestring

The mandate bank account holder name

Response
application/json
{
  "id": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdateTime": "2019-08-24T14:15:22Z",
  "distributionTime": "2019-08-24T14:15:22Z",
  "authorisationTime": "2019-08-24T14:15:22Z",
  "submissionTime": "2019-08-24T14:15:22Z",
  "status": "CREATED",
  "failureReason": "string",
  "statusReasonCode": "PENDING_DD_CAPABILITY",
  "statusReason": "string",
  "customer": {
    "id": "string",
    "externalId": "string",
    "name": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "people": [ … ],
    "addresses": [ … ],
    "directDebitMandate": { … },
    "billerBankAccount": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ],
    "status": "ACTIVE",
    "statusReasonCode": "MERGED",
    "settings": { … },
    "trackingItems": [ … ],
    "office": { … }
  },
  "url": "string",
  "redirectUrl": "string",
  "sender": {
    "name": "string"
  },
  "bankAccountNumber": "string",
  "sortCode": "string",
  "bankAccountHolderName": "string"
}

Invoices

Operations

Recurring invoices

Operations

Payment requests

Operations

Recurring payment requests

Operations

Payments

Operations

Tax rates

Operations

Items

Operations

Workflows

Operations

Webhooks

Operations