Skip to content
/
Retrieve a customer

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

Retrieve a list of customers by filter

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Query
onlyCustomersWithActivityboolean

Filter customers that have any financial activity (invoices, direct debits)

searchTextstring

Fuzzy search a customer based on a text

ddMandateSignedStartTimestring(date-time)

Filter customers that have signed their direct debit mandate after this date

ddMandateSignedEndTimestring(date-time)

Filter customers that have signed their direct debit mandate until this date

ddMandateStatusesArray of strings

The status of the latest direct debit mandate

Items Enum"CREATED""PENDING""ACTIVE""CANCELLED""MIGRATING"
includeCustomerFinancialDetailsboolean

This flag determines whether the response should include the financial status of the customer's invoices and payments

financialStatusesArray of strings

The financial statuses of the payment situation of the customer

Items Enum"DRAFT""OUTSTANDING""PENDING_PAYMENTS""OVERDUE""FULLY_PAID""NO_INVOICES"
lastUpdatedStartTimestring(date-time)

The start time after which the customer last updated time should be, including the start time.

tagIdsArray of strings

The tag ids of the customer

customerIdsArray of strings

The ids of the customers

pageinteger>= 0

Zero-based page index (0..N)

Default 0
sizeinteger>= 1

The size of the page to be returned

Default 20
sortArray of strings

Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.

Default ["creationTime,DESC"]
curl -i -X GET \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers?onlyCustomersWithActivity=true&searchText=string&ddMandateSignedStartTime=2019-08-24T14%3A15%3A22Z&ddMandateSignedEndTime=2019-08-24T14%3A15%3A22Z&ddMandateStatuses=CREATED&includeCustomerFinancialDetails=true&financialStatuses=DRAFT&lastUpdatedStartTime=2019-08-24T14%3A15%3A22Z&tagIds=string&customerIds=string&page=0&size=20&sort=creationTime%2CDESC' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of customers for the specified filter.

Bodyapplication/json
customersArray of objects(CustomerResponse)

The list of customers for the specified filter.

pageobject(Pagination)
paginationobject(Pagination)
Response
application/json
{
  "customers": [
    { … }
  ],
  "page": {
    "page": 0,
    "size": 0,
    "totalPages": 0,
    "totalElements": 0,
    "numberOfElements": 0,
    "sort": "string"
  },
  "pagination": {
    "page": 0,
    "size": 0,
    "totalPages": 0,
    "totalElements": 0,
    "numberOfElements": 0,
    "sort": "string"
  }
}

Update a customer

Request

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

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer. Only 1 pe supported for now

externalDataobject(CustomerExternalData)
trackingItemIdsArray of strings(uuid)

The list of tracking item catalogue IDs associated with the customer.

officeIdstring(uuid)

The office ID associated with the customer.

curl -i -X PUT \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "string",
    "externalId": "string",
    "name": "string",
    "people": [
      {
        "id": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "phoneNo": "string",
        "isPrimaryContact": true,
        "isIncludedInCommunications": true,
        "validForEmailCommunication": true,
        "validForPhoneCommunication": true
      }
    ],
    "addresses": [
      {
        "id": "string",
        "city": "string",
        "postalCode": "string",
        "country": "string",
        "addressLine1": "string"
      }
    ],
    "externalData": {
      "connectorType": "XERO",
      "id": "string",
      "name": "string"
    },
    "trackingItemIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "officeId": "da08ce10-cc2b-4a3d-a418-e10a176cc27a"
  }'

Responses

The request has succeeded and has resulted in one customer being updated.

Bodyapplication/json
idstring

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

creationTimestring(date-time)

The time the customer was created.

lastUpdatedTimestring(date-time)

The last time when the customer was updated.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer.

directDebitMandateobject(DirectDebitMandateSummary)
billerBankAccountobject(CustomerBankAccount)
timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)
externalDataArray of objects(CustomerExternalData)

References about this customer from external platforms Adfin integrates with, such as ID, etc.

tagsArray of strings

The tag ids associated with the customer.

statusstring

The status of the customer (ACTIVE, ARCHIVED)

Enum"ACTIVE""ARCHIVED"
statusReasonCodestring

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

Enum"MERGED""ARCHIVED_MANUALLY"
settingsobject(CustomerSettingsResponse)
trackingItemsArray of objects(TrackingItemCatalogueResponse)

The tracking item catalogues associated with the customer.

officeobject(InvoiceOfficeResponse)
Response
application/json
{
  "id": "string",
  "externalId": "string",
  "name": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "people": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "directDebitMandate": {
    "id": "string",
    "status": "CREATED",
    "statusReasonCode": "PENDING_DD_CAPABILITY",
    "statusReason": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "authorisationTime": "2019-08-24T14:15:22Z",
    "submissionTime": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "billerBankAccount": {
    "accountHolderAddress": { … },
    "accountHolderName": "string",
    "bankAccount": { … },
    "bankAddress": { … },
    "currencyCode": "AED"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "status": "ACTIVE",
  "statusReasonCode": "MERGED",
  "settings": {
    "paymentSettings": { … }
  },
  "trackingItems": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  }
}

Create a customer

Request

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

The full name of the customer.

Example: "John Doe"
peopleArray of objects(Person)

A list of people associated with the customer. Can include contacts, representatives, or stakeholders.

Example: [{"name":"Jane Smith","email":"jane.smith@example.com"}]
addressesArray of objects(Address)

A list of addresses for the customer. Currently, only one address is supported.

Example: [{"line1":"2 Catherine Pl","city":"London","state":"NY","postCode":"SW1E 6HF"}]
externalDataobject(CustomerExternalData)
Example: {"connectorType":"QuickBooks","id":"QB-56789","name":"My First Customer"}
trackingItemIdsArray of strings(uuid)

The list of tracking item catalogue IDs associated with the customer.

officeIdstring(uuid)

The office ID associated with the customer.

curl -i -X POST \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "John Doe",
    "people": [
      {
        "name": "Jane Smith",
        "email": "jane.smith@example.com"
      }
    ],
    "addresses": [
      {
        "line1": "2 Catherine Pl",
        "city": "London",
        "state": "NY",
        "postCode": "SW1E 6HF"
      }
    ],
    "externalData": {
      "connectorType": "XERO",
      "id": "string",
      "name": "string"
    },
    "trackingItemIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "officeId": "da08ce10-cc2b-4a3d-a418-e10a176cc27a"
  }'

Responses

The request has succeeded and has resulted in one customer being updated.

Bodyapplication/json
idstring

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

creationTimestring(date-time)

The time the customer was created.

lastUpdatedTimestring(date-time)

The last time when the customer was updated.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer.

directDebitMandateobject(DirectDebitMandateSummary)
billerBankAccountobject(CustomerBankAccount)
timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)
externalDataArray of objects(CustomerExternalData)

References about this customer from external platforms Adfin integrates with, such as ID, etc.

tagsArray of strings

The tag ids associated with the customer.

statusstring

The status of the customer (ACTIVE, ARCHIVED)

Enum"ACTIVE""ARCHIVED"
statusReasonCodestring

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

Enum"MERGED""ARCHIVED_MANUALLY"
settingsobject(CustomerSettingsResponse)
trackingItemsArray of objects(TrackingItemCatalogueResponse)

The tracking item catalogues associated with the customer.

officeobject(InvoiceOfficeResponse)
Response
application/json
{
  "id": "string",
  "externalId": "string",
  "name": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "people": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "directDebitMandate": {
    "id": "string",
    "status": "CREATED",
    "statusReasonCode": "PENDING_DD_CAPABILITY",
    "statusReason": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "authorisationTime": "2019-08-24T14:15:22Z",
    "submissionTime": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "billerBankAccount": {
    "accountHolderAddress": { … },
    "accountHolderName": "string",
    "bankAccount": { … },
    "bankAddress": { … },
    "currencyCode": "AED"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "status": "ACTIVE",
  "statusReasonCode": "MERGED",
  "settings": {
    "paymentSettings": { … }
  },
  "trackingItems": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  }
}

Retrieve a customer

Request

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

The id of the customer to get the details for

Query
idTypestringrequired

The connector type that this ID refers to

Enum"XERO""QUICKBOOKS""EXTERNAL"
includeCustomerFinancialDetailsboolean

This flag determines whether the response should include the financial status of the customer's invoices and payments.

curl -i -X GET \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{id}?idType=XERO&includeCustomerFinancialDetails=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The customer with the specified ID.

Bodyapplication/json
idstring

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

creationTimestring(date-time)

The time the customer was created.

lastUpdatedTimestring(date-time)

The last time when the customer was updated.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer.

directDebitMandateobject(DirectDebitMandateSummary)
billerBankAccountobject(CustomerBankAccount)
timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)
externalDataArray of objects(CustomerExternalData)

References about this customer from external platforms Adfin integrates with, such as ID, etc.

tagsArray of strings

The tag ids associated with the customer.

statusstring

The status of the customer (ACTIVE, ARCHIVED)

Enum"ACTIVE""ARCHIVED"
statusReasonCodestring

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

Enum"MERGED""ARCHIVED_MANUALLY"
settingsobject(CustomerSettingsResponse)
trackingItemsArray of objects(TrackingItemCatalogueResponse)

The tracking item catalogues associated with the customer.

officeobject(InvoiceOfficeResponse)
Response
application/json
{
  "id": "string",
  "externalId": "string",
  "name": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "people": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "directDebitMandate": {
    "id": "string",
    "status": "CREATED",
    "statusReasonCode": "PENDING_DD_CAPABILITY",
    "statusReason": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "authorisationTime": "2019-08-24T14:15:22Z",
    "submissionTime": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "billerBankAccount": {
    "accountHolderAddress": { … },
    "accountHolderName": "string",
    "bankAccount": { … },
    "bankAddress": { … },
    "currencyCode": "AED"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "status": "ACTIVE",
  "statusReasonCode": "MERGED",
  "settings": {
    "paymentSettings": { … }
  },
  "trackingItems": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  }
}

Update a customer by id

Request

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

The id of the customer to update.

Bodyapplication/jsonrequired
externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer. Only 1 pe supported for now

externalDataobject(CustomerExternalData)
trackingItemIdsArray of strings(uuid)

The list of tracking item catalogue IDs associated with the customer.

officeIdstring(uuid)

The office ID associated with the customer.

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "externalId": "string",
    "name": "string",
    "people": [
      {
        "id": "string",
        "firstName": "string",
        "lastName": "string",
        "email": "string",
        "phoneNo": "string",
        "isPrimaryContact": true,
        "isIncludedInCommunications": true,
        "validForEmailCommunication": true,
        "validForPhoneCommunication": true
      }
    ],
    "addresses": [
      {
        "id": "string",
        "city": "string",
        "postalCode": "string",
        "country": "string",
        "addressLine1": "string"
      }
    ],
    "externalData": {
      "connectorType": "XERO",
      "id": "string",
      "name": "string"
    },
    "trackingItemIds": [
      "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    ],
    "officeId": "da08ce10-cc2b-4a3d-a418-e10a176cc27a"
  }'

Responses

The request has succeeded and has resulted in one customer being updated.

Bodyapplication/json
idstring

The Adfin id of the customer.

externalIdstring

The id of the customer from the platform that is integrating with Adfin.

namestring

The full name of the customer.

creationTimestring(date-time)

The time the customer was created.

lastUpdatedTimestring(date-time)

The last time when the customer was updated.

peopleArray of objects(Person)

The list of people assigned to the customer.

addressesArray of objects(Address)

The list of the addresses for the customer.

directDebitMandateobject(DirectDebitMandateSummary)
billerBankAccountobject(CustomerBankAccount)
timezonestring

The timezone of the customer.

discountobject(CustomerDiscount)
externalDataArray of objects(CustomerExternalData)

References about this customer from external platforms Adfin integrates with, such as ID, etc.

tagsArray of strings

The tag ids associated with the customer.

statusstring

The status of the customer (ACTIVE, ARCHIVED)

Enum"ACTIVE""ARCHIVED"
statusReasonCodestring

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

Enum"MERGED""ARCHIVED_MANUALLY"
settingsobject(CustomerSettingsResponse)
trackingItemsArray of objects(TrackingItemCatalogueResponse)

The tracking item catalogues associated with the customer.

officeobject(InvoiceOfficeResponse)
Response
application/json
{
  "id": "string",
  "externalId": "string",
  "name": "string",
  "creationTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "people": [
    { … }
  ],
  "addresses": [
    { … }
  ],
  "directDebitMandate": {
    "id": "string",
    "status": "CREATED",
    "statusReasonCode": "PENDING_DD_CAPABILITY",
    "statusReason": "string",
    "creationTime": "2019-08-24T14:15:22Z",
    "lastUpdatedTime": "2019-08-24T14:15:22Z",
    "authorisationTime": "2019-08-24T14:15:22Z",
    "submissionTime": "2019-08-24T14:15:22Z",
    "url": "string"
  },
  "billerBankAccount": {
    "accountHolderAddress": { … },
    "accountHolderName": "string",
    "bankAccount": { … },
    "bankAddress": { … },
    "currencyCode": "AED"
  },
  "timezone": "string",
  "discount": {
    "percentage": 0,
    "period": 0
  },
  "externalData": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "status": "ACTIVE",
  "statusReasonCode": "MERGED",
  "settings": {
    "paymentSettings": { … }
  },
  "trackingItems": [
    { … }
  ],
  "office": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210",
    "details": { … }
  }
}

Upsert customer workflow settings

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
customerIdsArray of stringsrequired

List of customer IDs to update

workflowSettingsobject(CustomerWorkflowSettings)required
workflowSettings.​workflowTransitionsArray of objects(WorkflowTransition)required

List of workflow transition configurations, each defining a source and target workflow type

workflowSettings.​workflowTransitions[].​sourcestringrequired

The current workflow type from which it is transitioning

Enum"AUTO_COLLECT""ON_DEMAND""NONE"
workflowSettings.​workflowTransitions[].​targetstringrequired

The workflow type to which it is transitioning

Enum"AUTO_COLLECT""ON_DEMAND""NONE"
workflowSettings.​workflowTransitions[].​typestringrequired

Defines how a workflow transition is triggered

Enum"AUTOMATIC""MANUAL"
workflowSettings.​autoCollectobject(AutoCollectSettings)required
workflowSettings.​autoCollect.​isEnabledbooleanrequired

Indicates whether auto-collect workflow is enabled

workflowSettings.​autoCollect.​isDefaultbooleanrequired

Indicates whether auto-collect is the default workflow

workflowSettings.​autoCollect.​pauseCollectionboolean

When true, payment collection is paused. While paused, no automatic retries or scheduled collection attempts will occur.

Example: true
workflowSettings.​autoCollect.​resumeCollectionAtstring(date-time)

The timestamp when automatic collection should resume. If null, collection remains paused until updated manually.

Example: "2025-01-15T10:00:00Z"
workflowSettings.​onDemandobject(OnDemandSettings)required
workflowSettings.​onDemand.​isEnabledbooleanrequired

Indicates whether on-demand workflow is enabled

workflowSettings.​onDemand.​isDefaultbooleanrequired

Indicates whether on-demand is the default workflow

workflowSettings.​customerStatementobject(CustomerStatementSettings)required
workflowSettings.​customerStatement.​isEnabledbooleanrequired

Indicates whether customer statement workflow is enabled

curl -i -X PUT \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/workflow_settings \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerIds": [
      "string"
    ],
    "workflowSettings": {
      "workflowTransitions": [
        {
          "source": "AUTO_COLLECT",
          "target": "AUTO_COLLECT",
          "type": "AUTOMATIC"
        }
      ],
      "autoCollect": {
        "isEnabled": true,
        "isDefault": true,
        "pauseCollection": true,
        "resumeCollectionAt": "2025-01-15T10:00:00Z"
      },
      "onDemand": {
        "isEnabled": true,
        "isDefault": true
      },
      "customerStatement": {
        "isEnabled": true
      }
    }
  }'

Responses

The customer workflow settings were successfully updated.

Bodyapplication/json
workflowTransitionsArray of objects(WorkflowTransition)

List of workflow transition configurations, each defining a source and target workflow type

autoCollectobject(AutoCollectSettings)required
autoCollect.​isEnabledbooleanrequired

Indicates whether auto-collect workflow is enabled

autoCollect.​isDefaultbooleanrequired

Indicates whether auto-collect is the default workflow

autoCollect.​pauseCollectionboolean

When true, payment collection is paused. While paused, no automatic retries or scheduled collection attempts will occur.

Example: true
autoCollect.​resumeCollectionAtstring(date-time)

The timestamp when automatic collection should resume. If null, collection remains paused until updated manually.

Example: "2025-01-15T10:00:00Z"
onDemandobject(OnDemandSettings)required
onDemand.​isEnabledbooleanrequired

Indicates whether on-demand workflow is enabled

onDemand.​isDefaultbooleanrequired

Indicates whether on-demand is the default workflow

customerStatementobject(CustomerStatementSettings)required
customerStatement.​isEnabledbooleanrequired

Indicates whether customer statement workflow is enabled

Response
application/json
{
  "workflowTransitions": [
    { … }
  ],
  "autoCollect": {
    "isEnabled": true,
    "isDefault": true,
    "pauseCollection": true,
    "resumeCollectionAt": "2025-01-15T10:00:00Z"
  },
  "onDemand": {
    "isEnabled": true,
    "isDefault": true
  },
  "customerStatement": {
    "isEnabled": true
  }
}

Upsert customer payment settings

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
customerIdsArray of strings

The list of ids of the customers for which to upsert payment settings

paymentSettingsobject(CustomerPaymentSettings)
curl -i -X PUT \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/customers/payment_settings \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerIds": [
      "string"
    ],
    "paymentSettings": {
      "allowPartialPayments": true,
      "minPartialPaymentAmount": 0,
      "surchargeIsEnabled": true
    }
  }'

Responses

The payment settings were successfully updated.

Bodyapplication/json
allowPartialPaymentsboolean

Indicates whether partial payments are allowed

minPartialPaymentAmountnumber

The minimum amount for partial payments

surchargeIsEnabledboolean

Indicates whether a surcharge is applied to commercial card payments

Response
application/json
{
  "allowPartialPayments": true,
  "minPartialPaymentAmount": 0,
  "surchargeIsEnabled": true
}

Retrieve customer workflow settings

Request

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

The id of the customer to get workflow settings for

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

Responses

The workflow settings were retrieved.

Bodyapplication/json
workflowTransitionsArray of objects(WorkflowTransition)

List of workflow transition configurations, each defining a source and target workflow type

autoCollectobject(AutoCollectSettings)required
autoCollect.​isEnabledbooleanrequired

Indicates whether auto-collect workflow is enabled

autoCollect.​isDefaultbooleanrequired

Indicates whether auto-collect is the default workflow

autoCollect.​pauseCollectionboolean

When true, payment collection is paused. While paused, no automatic retries or scheduled collection attempts will occur.

Example: true
autoCollect.​resumeCollectionAtstring(date-time)

The timestamp when automatic collection should resume. If null, collection remains paused until updated manually.

Example: "2025-01-15T10:00:00Z"
onDemandobject(OnDemandSettings)required
onDemand.​isEnabledbooleanrequired

Indicates whether on-demand workflow is enabled

onDemand.​isDefaultbooleanrequired

Indicates whether on-demand is the default workflow

customerStatementobject(CustomerStatementSettings)required
customerStatement.​isEnabledbooleanrequired

Indicates whether customer statement workflow is enabled

Response
application/json
{
  "workflowTransitions": [
    { … }
  ],
  "autoCollect": {
    "isEnabled": true,
    "isDefault": true,
    "pauseCollection": true,
    "resumeCollectionAt": "2025-01-15T10:00:00Z"
  },
  "onDemand": {
    "isEnabled": true,
    "isDefault": true
  },
  "customerStatement": {
    "isEnabled": true
  }
}

Retrieve customer payment settings

Request

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

The id of the customer to get payment settings for

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

Responses

The payment settings were retrieved.

Bodyapplication/json
allowPartialPaymentsboolean

Indicates whether partial payments are allowed

minPartialPaymentAmountnumber

The minimum amount for partial payments

surchargeIsEnabledboolean

Indicates whether a surcharge is applied to commercial card payments

Response
application/json
{
  "allowPartialPayments": true,
  "minPartialPaymentAmount": 0,
  "surchargeIsEnabled": true
}

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