Skip to content
/
Update the distribution d...

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.

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

Verifications

Operations

Customers

Operations

Direct debit mandates

Operations

Invoices

Operations

Recurring invoices

Operations

Payment requests

Operations

Activate (send) a payment request

Request

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

The id of the payment request

Bodyapplication/jsonrequired
collectionMethodstring

How the payment is expected to be collected for this invoice.

Enum"ONE_TIME_PAYMENT""DIRECT_DEBIT_PAYMENT""NONE"
customMessagestring

An optional message that will be sent to the customer when the invoice is activated.

templateIdstring

The schedule template id used for sending the invoice to customer.

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/payment_requests/{id}:activate' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "collectionMethod": "ONE_TIME_PAYMENT",
    "customMessage": "string",
    "templateId": "string"
  }'

Responses

The payment request was activated

Update the distribution details of payment requests

Request

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

The IDs of the payment requests for which to update the distribution details

distributionDetailsobject(CollectionDetails)
curl -i -X PUT \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/payment_requests/distribution \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentRequestIds": [
      "string"
    ],
    "distributionDetails": {
      "collectionMethod": "AUTO_COLLECT",
      "customMessage": "Thank you for your business!",
      "approvedForSending": true
    }
  }'

Responses

The distribution details were updated

Retrieve a list of payment requests by filter

Request

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

The id of the customer associated to the payment request.

externalCustomerIdstring

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

statusesArray of strings

The status of the payment request.

  • DRAFT: The payment request does not contain contact details for the payer or it is not yet distributed.
  • UNPAID: The payment request is not yet paid.
  • SCHEDULED: The payment request is scheduled to collect the payment via Direct Debit.
  • SUBMITTED: The remaining due amount on the payment request is covered by submitted (but not yet confirmed) Direct debit payments.
  • PAID: The payment request payment payment is captured.
  • CANCELLED: The payment request is cancelled.
  • SETTLED: THe payment request is paid out
Items Enum"DRAFT""UNPAID""OVERDUE""SCHEDULED""SUBMITTED""PAID""VOID""SETTLED"
associationTypesArray of strings

Payment request association type.

  • SINGLE - a one off payment request.
  • ONE_TO_ONE - a payment request associated with a single invoice.
  • PARTIAL - a payment request that is associated with an invoice that has multiple payment requests (many to one)
  • BATCH - a payment request that is associated with multiple invoices (one to many)

defaults to all types if not specified.

Items Enum"SINGLE""ONE_TO_ONE""PARTIAL""BATCH"
payByStartDatestring(date-time)

The start date after which the payment requests pay by date should be, including the start date.

payByEndDatestring(date-time)

The end date before which the payment requests pay by date should be, including the end date.

createdStartDatestring(date-time)

The start date after which the payment requests created date should be, including the start date.

createdEndDatestring(date-time)

The end date before which the payment requests created date should be, including the end date.

paidStartTimestring(date-time)

The start time after which the payment request was paid, including the paid start time.

paidEndTimestring(date-time)

The end time after which the payment request was paid, including the paid end time.

lastUpdatedStartTimestring(date-time)

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

lastUpdatedEndTimestring(date-time)

The end time before which the payment requests last updated time should be, including the end time.

paymentLinkLastSeenTimestring(date-time)

The start time before which the payment link was seen.

paymentInitiationDatestring(date-time)
searchTextstring

The text to search for in the payment requests.

includeCountboolean

Whether the response should include details on total count and counts per statuses

creditControlStatusesArray of strings

The credit control status of the payment request.

  • AT_RISK: The payment request is at risk of not being paid.
  • EXPECTED: The payment request is expected to be paid.
  • CONFIRMED: The payment request is paid.
Items Enum"AT_RISK""EXPECTED""CONFIRMED"
cashflowStatusesArray of strings

The cashflow status of the payment request.

  • UNPAID – not yet paid.
  • PROCESSING – expected to be paid.
  • PAID_OUT – already paid out.
Items Enum"UNPAID""PROCESSING""PAID_OUT"
cashflowPeriodStartDatestring(date-time)

Start of the cashflow period (inclusive)

cashflowPeriodEndDatestring(date-time)

End of the cashflow period (inclusive)

directDebitMandateStatusesArray of strings

The direct debit mandate status.

  • NO_MANDATE: payment requests linked to customers without a mandate
  • AWAITING_SIGNATURE: payment requests linked to customers awaiting signature
  • SIGNED: payment requests linked to customers with a signed mandate, but not yet active
  • ACTIVE: payment requests linked to customers with an active mandate.
Items Enum"NO_MANDATE""AWAITING_SIGNATURE""SIGNED""ACTIVE""MIGRATING"
workflowTypesArray of strings

The workflow type.

  • AUTO_COLLECT: automatic collection workflow, such as direct debit
  • ON_DEMAND: on demain workflow, such as via open banking and card payments
Items Enum"AUTO_COLLECT""ON_DEMAND""NONE"
minAmountnumber>= 0

amount greater than or equal to

maxAmountnumber>= 0

amount less than or equal to

scheduleIdstring

The id of the schedule associated to the payment request.

fieldValueIdsArray of strings

List of field value IDs to filter payment requests by their associated field mappings.

reviewSessionIdstring

The review session ID to filter payment requests by

pageinteger>= 0

Zero-based page index (0..N)

Default 0
sizeinteger>= 1

The size of the page to be returned

Default 50
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/payment_requests?customerId=string&externalCustomerId=string&statuses=DRAFT&associationTypes=SINGLE&payByStartDate=2019-08-24T14%3A15%3A22Z&payByEndDate=2019-08-24T14%3A15%3A22Z&createdStartDate=2019-08-24T14%3A15%3A22Z&createdEndDate=2019-08-24T14%3A15%3A22Z&paidStartTime=2019-08-24T14%3A15%3A22Z&paidEndTime=2019-08-24T14%3A15%3A22Z&lastUpdatedStartTime=2019-08-24T14%3A15%3A22Z&lastUpdatedEndTime=2019-08-24T14%3A15%3A22Z&paymentLinkLastSeenTime=2019-08-24T14%3A15%3A22Z&paymentInitiationDate=2019-08-24T14%3A15%3A22Z&searchText=string&includeCount=true&creditControlStatuses=AT_RISK&cashflowStatuses=UNPAID&cashflowPeriodStartDate=2019-08-24T14%3A15%3A22Z&cashflowPeriodEndDate=2019-08-24T14%3A15%3A22Z&directDebitMandateStatuses=NO_MANDATE&workflowTypes=AUTO_COLLECT&minAmount=0&maxAmount=0&scheduleId=string&fieldValueIds=string&reviewSessionId=string&page=0&size=50&sort=creationTime%2CDESC' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

The list of payment requests for the specified filter.

Bodyapplication/json
paymentRequestsArray of objects(PaymentRequestResponse)

List of payment requests

countobject(PaymentRequestStatusCountResponse)
paginationobject(Pagination)
Response
application/json
{
  "paymentRequests": [
    { … }
  ],
  "count": {
    "total": 0,
    "statusCounts": [ … ]
  },
  "pagination": {
    "page": 0,
    "size": 0,
    "totalPages": 0,
    "totalElements": 0,
    "numberOfElements": 0,
    "sort": "string"
  }
}

Recurring payment requests

Operations

Payments

Operations

Payouts

Operations

Tax rates

Operations

Items

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