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.

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

Preview instalment plan for an invoice

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
invoiceIdstringrequired
Bodyapplication/jsonrequired
cadenceobject(Cadence)required
cadence.​typestringrequired

The type of the cadence (INTERVAL, DAY_OF_MONTH, etc.)

Enum"INTERVAL""INTERVAL_COUNT""DAY_OF_MONTH""CUSTOM"
cadence.​timeUnitstring

Required if type is INTERVAL. Defines the time unit (e.g., DAYS, MONTHS, etc.).

Enum"SECOND""MINUTE""HOUR""DAY""WEEK""MONTH""YEAR"
cadence.​frequencyinteger(int32)>= 1

Required if type is INTERVAL. Frequency of recurrence (e.g., every N time units).

cadence.​dayOfMonthinteger(int32)

Required if type is DAY_OF_MONTH. Specifies the day of the month the schedule applies.

cadence.​datesArray of strings(date-time)

Required if type is CUSTOM. A list of exact custom dates for the cadence.

cadence.​startDatestring(date-time)required

The start date of the schedule

cadence.​endDatestring(date-time)

The (optional) end date of the schedule

cadence.​countinteger(int32)[ 2 .. 120 ]

The total number of items. Required for INTERVAL_COUNT type

totalAmountnumber

Total amount to distribute across instalments. Defaults to the invoice total if not provided.

curl -i -X POST \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/invoices/{invoiceId}/instalments/preview' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "cadence": {
      "type": "INTERVAL",
      "timeUnit": "SECOND",
      "frequency": 1,
      "dayOfMonth": 0,
      "dates": [
        "2019-08-24T14:15:22Z"
      ],
      "startDate": "2019-08-24T14:15:22Z",
      "endDate": "2019-08-24T14:15:22Z",
      "count": 2
    },
    "totalAmount": 0
  }'

Responses

The instalment preview was generated successfully.

Bodyapplication/json
idstring

The internal id of the invoice

invoiceNostring

The number of the invoice. Can be empty when creating the invoice without an invoice number,but it will be automatically generated when the invoice is pushed to an accounting software. Once set, serves as a unique value that can be used as an idempotency key.

descriptionstring

Short description of the invoice

totalAmountstring

The invoice total amount. Includes tax amount, amount paid or reduced with credit notes)

taxAmountstring

The invoice tax amount.

dueAmountstring

The invoice amount due (remaining to be paid).

creditNotesAmountstring

The total amount that is credited.

dueDatestring(date-time)

The due date of the invoice

issueDatestring(date-time)

The issue date date of the invoice

creationTimestring(date-time)

The date the invoice was created

lastUpdatedTimestring(date-time)

The date the invoice was last updated

paidTimestring(date-time)

The date the invoice was paid

statusstring

The invoice status

Enum"DRAFT""UNPAID""OVERDUE""SCHEDULED""SUBMITTED""PAID""VOID""SETTLED"
statusReasonCodestring

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

Enum"MISSING_PAYER_CONTACT_DETAILS""PENDING_ACTIVATION""PENDING_DD_MANDATE""PENDING_DD_CAPABILITY""MARKED_AS_PAID""WORKFLOW_COMPLETED""NOTIFICATION_DELIVERY_FAILED""BULK_PRUNE""STALE_DRAFT_CLEANUP""OTHER"
statusReasonstring

Custom details on why the invoice is in a certain status

invoiceSourcestring

The source of the invoice

Enum"FILE_UPLOAD""MANUAL""PR""EXTERNAL""SCHEDULE""PLATFORM""EMAIL"
customerobject(CustomerResponse)
itemsTaxTypestring

How tax is applied to line items from the invoice

Enum"EXCLUSIVE""INCLUSIVE""NONE"
instalmentPlanDetailsobject(InstalmentPlanDetails)
itemsArray of objects(LineItemResponse)

The list of items from the invoice

paymentRequestsArray of objects(PaymentRequestDetails)

The payment requests that were created for this invoice

scheduleDetailsobject(ScheduleDetails)
creditNotesArray of objects(CreditNoteResponse)

The list of credit notes from the invoice

fileSourcestring

The file source of invoice

Enum"NONE""FILE_UPLOAD""EMAIL""EXTERNAL""ADFIN""PENDING_ADFIN"
externalDataArray of objects(InvoiceExternalData)

References about this invoice from external platforms Adfin integrates with. Such as ID etc

creditControlStatusstring

The credit control status of the invoice

Enum"AT_RISK""EXPECTED""CONFIRMED"
workflowTypestring

The workflow type of the invoice

Enum"AUTO_COLLECT""ON_DEMAND""NONE"
customFieldsArray of objects(CustomField)

The list of custom fields that are applied to the invoice

officeobject(InvoiceOfficeResponse)
Response
application/json
{ "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", "invoiceSource": "FILE_UPLOAD", "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": { … }, "collectionAgentId": "fe30a7f6-c47c-4051-9601-bd9dbc464447" }, "itemsTaxType": "EXCLUSIVE", "instalmentPlanDetails": { "cadence": { … } }, "items": [ { … } ], "paymentRequests": [ { … } ], "scheduleDetails": { "scheduleId": "string", "scheduleNo": "string", "type": "RECURRING" }, "creditNotes": [ { … } ], "fileSource": "NONE", "externalData": [ { … } ], "creditControlStatus": "AT_RISK", "workflowType": "AUTO_COLLECT", "customFields": [ { … } ], "office": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "string", "trackingItemId": "c7c7fc03-0b17-402e-aa79-1d532a6db210", "details": { … } } }

Import a credit note

Request

Apply a credit note from another system to an invoice. The credit note lowers the amount due. The invoice must still take payments.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
invoiceIdstring(uuid)required

The id of the invoice

Bodyapplication/jsonrequired
numberstringnon-emptyrequired

The credit note number. A number can be used once per invoice. It can be used again after that credit note is cancelled.

Example: "CN-0042"
amountnumber> 0required

The credit note amount. It lowers the amount due of the invoice and cannot be more than the amount due.

Example: 25
valueDatestring(date-time)

The date when the credit note was applied.

curl -i -X POST \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/invoices/{invoiceId}/credit_notes' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "CN-0042",
    "amount": 25,
    "valueDate": "2019-08-24T14:15:22Z"
  }'

Responses

Credit note successfully imported.

Bodyapplication/json
idstring

Credit note id.

numberstring

Credit note number.

amountnumber

Credit note amount.

valueDatestring(date-time)

Date when credit note was applied.

externalDataArray of objects(CreditNoteExternalData)

References about this credit note from external platforms Adfin integrates with. Such as ID etc

Response
application/json
{ "id": "string", "number": "string", "amount": 0, "valueDate": "2019-08-24T14:15:22Z", "externalData": [ { … } ] }

Get the collection preferences for an invoice

Request

The values in force, after the agent's settings and every override are resolved.

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Path
invoiceIdstring(uuid)required

The identifier of the invoice.

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

Responses

The collection method and preferences in force.

Bodyapplication/json
collectionMethodstringrequired

The collection method in force.

Enum"AUTO_COLLECT""ON_DEMAND"
preferencesobject(CollectionPreferences)required
preferences.​paymentRemindersobject(PreferenceToggle)
preferences.​paymentDistributionobject(PreferenceToggle)
preferences.​mandateRemindersobject(PreferenceToggle)
preferences.​cardRemindersobject(PreferenceToggle)
preferences.​directDebitEncouragementobject(PreferenceToggle)
preferences.​statementsobject(PreferenceToggle)
preferences.​lateFeesobject(LateFeesPreference)
preferences.​partialPaymentsobject(PartialPaymentsPreference)
preferences.​surchargingobject(PreferenceToggle)
Response
application/json
{ "collectionMethod": "AUTO_COLLECT", "preferences": { "paymentReminders": { … }, "paymentDistribution": { … }, "mandateReminders": { … }, "cardReminders": { … }, "directDebitEncouragement": { … }, "statements": { … }, "lateFees": { … }, "partialPayments": { … }, "surcharging": { … } } }

Recurring invoices

Operations

Payment requests

Operations

Recurring payment requests

Operations

Payments

Operations

Payouts

Operations

Tax rates

Operations

Items

Operations

Account codes

Operations

Activities

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

Operations

Scheduled Activities

What is planned next for a customer or a payment request.

Operations

Webhooks

Operations

Referrals

Operations