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
string

The request containing the redirect URL

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'

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. Possible values (non-exclusive): CREATED, PENDING, ACTIVE, CANCELLED, MIGRATING

failureReasonstring

The reason for failing to set up the mandate

statusReasonCodestring

The reason why the direct debit mandate is in a certain status.

  • PENDING_DD_CAPABILITY - The direct debit mandate was signed, but not yet submitted to the payment provider as the biller onboarding is still in progress.
  • PENDING_ACTIVATION - The direct debit mandate was signed, but not yet activated by the payment provider.
  • MIGRATED - The direct debit mandate was migrated to a new payment provider.
  • BANK_ACCOUNT_CHANGED - The direct debit mandate was created due to a bank account change (bank switching).
  • INCORRECT_BANK_DETAILS - The direct debit mandate has incorrect bank account details.
  • OTHER - Unknown reason. Possible values (non-exclusive): PENDING_DD_CAPABILITY, PENDING_ACTIVATION, MIGRATED, BANK_ACCOUNT_CHANGED, INCORRECT_BANK_DETAILS, OTHER
statusReasonstring

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

customerobject(CustomerResponse)

The customer details.

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)

The sender details.

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": "string",
  "failureReason": "string",
  "statusReasonCode": "string",
  "statusReason": "string",
  "customer": {
    "id": "string",
    "externalId": "string",
    "name": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "people": [ … ],
    "addresses": [ … ],
    "directDebitMandate": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ]
  },
  "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.

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. Possible values (non-exclusive): CREATED, PENDING, ACTIVE, CANCELLED, MIGRATING

failureReasonstring

The reason for failing to set up the mandate

statusReasonCodestring

The reason why the direct debit mandate is in a certain status.

  • PENDING_DD_CAPABILITY - The direct debit mandate was signed, but not yet submitted to the payment provider as the biller onboarding is still in progress.
  • PENDING_ACTIVATION - The direct debit mandate was signed, but not yet activated by the payment provider.
  • MIGRATED - The direct debit mandate was migrated to a new payment provider.
  • BANK_ACCOUNT_CHANGED - The direct debit mandate was created due to a bank account change (bank switching).
  • INCORRECT_BANK_DETAILS - The direct debit mandate has incorrect bank account details.
  • OTHER - Unknown reason. Possible values (non-exclusive): PENDING_DD_CAPABILITY, PENDING_ACTIVATION, MIGRATED, BANK_ACCOUNT_CHANGED, INCORRECT_BANK_DETAILS, OTHER
statusReasonstring

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

customerobject(CustomerResponse)

The customer details.

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)

The sender details.

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": "string",
  "failureReason": "string",
  "statusReasonCode": "string",
  "statusReason": "string",
  "customer": {
    "id": "string",
    "externalId": "string",
    "name": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "people": [ … ],
    "addresses": [ … ],
    "directDebitMandate": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ]
  },
  "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