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

Resume collection for an invoice

Request

Starts collection of every payment request raised for this invoice by the named methods again. Those payment requests keep being collected even while the customer as a whole is paused. Methods that are not named keep their current state.

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

The identifier of the invoice.

Bodyapplication/jsonrequired
collectionMethodsArray of stringsnon-emptyuniquerequired

The collection methods to resume. At least one method is required.

Items Enum"AUTO_COLLECT""ON_DEMAND"
curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/invoices/{invoiceId}:resume_collection' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collectionMethods": [
      "AUTO_COLLECT"
    ]
  }'

Responses

Collection is resumed for the named methods.

Response
No content

Pause collection for an invoice

Request

Stops collection of every payment request raised for this invoice by the named methods, leaving the customer's other invoices alone. Methods that are not named keep collecting, and a method that is already paused stays as it is.

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

The identifier of the invoice.

Bodyapplication/jsonrequired
collectionMethodsArray of stringsnon-emptyuniquerequired

The collection methods to pause. At least one method is required.

Items Enum"AUTO_COLLECT""ON_DEMAND"
curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/invoices/{invoiceId}:pause_collection' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collectionMethods": [
      "AUTO_COLLECT"
    ]
  }'

Responses

Collection is paused for the named methods.

Response
No content

Get an invoice by its id

Request

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

The id of the invoice to get the details for

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

Responses

The Invoice data is successfully retrieved

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": { … } } }

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