Skip to content
/
Bulk import payment reque...

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

Create a payment request

Request

Security
Biller Access Token (Production) or Biller Access Token (Staging)
Bodyapplication/jsonrequired
customerobject(CustomerDetails)required
Example: "80349480-490b-4234-92e7-fad697e3d446"
customer.​idstring

The Adfin ID of the customer for whom the invoice is created.

Example: "CUST-67890"
customer.​externalIdstring

The customer ID in the external platform integrating with Adfin.

Example: "ext-customer-001"
descriptionstring[ 0 .. 200 ] charactersrequired

A short description or summary of the payment request.

Example: "Monthly subscription fee for January"
totalAmountnumber>= 0.01

The payment request amount. Omit it when line items are supplied, in which case the total is calculated from them.

Example: 100
currencyCodestringrequired

The payment request currency.

Enum"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN"
Example: "GBP"
taxRatenumber[ 0 .. 100 ]

Optional tax rate percentage applied on the payment request amount.

Example: 20
referencestring[ 0 .. 22 ] characters^[a-zA-Z0-9 .]*$

Optional reference for the payment request.

Example: "REF 123456"
payByDatestring(date-time)

The date by which the payment request should be paid

Example: "2025-03-25T11:36:55.243Z"
distributionobject(DistributionDetails)
redirectUrlstring

The (optional) redirect URL to redirect the user after they complete the payment

curl -i -X POST \
  https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/payment_requests \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": {
      "id": "CUST-67890",
      "externalId": "ext-customer-001"
    },
    "description": "Monthly subscription fee for January",
    "totalAmount": 100,
    "currencyCode": "GBP",
    "taxRate": 20,
    "reference": "REF 123456",
    "payByDate": "2025-03-25T11:36:55.243Z",
    "distribution": {
      "collectionMethod": "ONE_TIME_PAYMENT",
      "customMessage": "string",
      "templateId": "string"
    },
    "redirectUrl": "string"
  }'

Responses

The request was successful and the payment request was created

Bodyapplication/json
idstring

The internal id of the payment request

paymentRequestNostring

The payment request number

referencestring

The payment request reference

descriptionstring

Short description of the payment request

totalAmountnumber

The payment request amount

principalAmountnumber

The principal amount of the payment request, excluding fees

paidAmountnumber

The total amount that is paid

dueAmountnumber

The amount that is due

feesArray of objects(FeeResponse)

The outstanding fees on this payment request

currencyCodestring

The currency in which the payment request is raised

Enum"AED""AFN""ALL""AMD""ANG""AOA""ARS""AUD""AWG""AZN"
taxRatenumber

Tax rate percentage

payByDatestring(date-time)

The (optional) date until when user recommended the payer to pay

creationTimestring(date-time)

The date the payment request was created

distributionTimestring(date-time)

The time when the payment request was distributed to the customer

lastNotificationSentTimestring(date-time)

The date the payment request was last sent to the customer

lastUpdatedTimestring(date-time)

The date the payment request was last updated

paidTimestring(date-time)

The date the payment request paid

paymentInitiationDatestring(date-time)

The date when payment is initiated for this payment request (only for Direct Debit)

chargeDatestring(date-time)

The date on which the customer will have their account debited

payoutDatestring(date-time)

The date on which the biller will get paid out for the payment

statusstring

The payment request status

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

The reason as predefined code why the payment request 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 payment request is in a certain status

paymentRequestSourcestring

The source of the payment request

Enum"MANUAL""SCHEDULE""INVOICE""EXTERNAL""OVERPAYMENT""GENERIC_PAYMENT_LINK""PAYMENT_ALLOCATION""PAYMENT_OVER_PHONE"
paymentsArray of objects(PaymentAllocationResponse)

The payments made as part of this payment request

discountsArray of objects(DiscountDetails)

The discounts applied to this payment request

paymentLinkobject(PaymentLinkDetails)
redirectUrlstring

The (optional) redirect URL to redirect the user after they complete the payment

invoicesArray of objects(InvoiceDetails)

The invoices associated to this payment request

customerobject(CustomerResponse)
distributionobject(DistributionDetails)
associationTypestring

The payment request association type

Enum"SINGLE""ONE_TO_ONE""PARTIAL""BATCH"
creditControlStatusstring

The credit control status of the payment request

Enum"AT_RISK""EXPECTED""CONFIRMED"
workflowTypestring

The workflow type of the payment request

Enum"AUTO_COLLECT""ON_DEMAND""NONE"
scheduleDetailsobject(ScheduleDetails)
instalmentDetailsobject(InstalmentDetails)
customFieldsArray of objects(CustomField)

The list of custom fields that are applied to the payment request

tagsArray of strings

The list of tag ids that are applied to the payment request

createdBystring

The creator of the payment request

applicableFeesArray of objects(FeeResponse)

Fees that would apply to this payment request if it isn't paid by the grace period (e.g. projected late fees). Populated only when no fees have been applied yet.

invoiceInputobject(InvoiceInputResponse)
Response
application/json
{
  "id": "string",
  "paymentRequestNo": "string",
  "reference": "string",
  "description": "string",
  "totalAmount": 0,
  "principalAmount": 0,
  "paidAmount": 0,
  "dueAmount": 0,
  "fees": [
    { … }
  ],
  "currencyCode": "AED",
  "taxRate": 0,
  "payByDate": "2019-08-24T14:15:22Z",
  "creationTime": "2019-08-24T14:15:22Z",
  "distributionTime": "2019-08-24T14:15:22Z",
  "lastNotificationSentTime": "2019-08-24T14:15:22Z",
  "lastUpdatedTime": "2019-08-24T14:15:22Z",
  "paidTime": "2019-08-24T14:15:22Z",
  "paymentInitiationDate": "2019-08-24T14:15:22Z",
  "chargeDate": "2019-08-24T14:15:22Z",
  "payoutDate": "2019-08-24T14:15:22Z",
  "status": "DRAFT",
  "statusReasonCode": "MISSING_PAYER_CONTACT_DETAILS",
  "statusReason": "string",
  "paymentRequestSource": "MANUAL",
  "payments": [
    { … }
  ],
  "discounts": [
    { … }
  ],
  "paymentLink": {
    "url": "string",
    "lastSeenTime": "2019-08-24T14:15:22Z"
  },
  "redirectUrl": "string",
  "invoices": [
    { … }
  ],
  "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"
  },
  "distribution": {
    "collectionMethod": "ONE_TIME_PAYMENT",
    "customMessage": "string",
    "templateId": "string"
  },
  "associationType": "SINGLE",
  "creditControlStatus": "AT_RISK",
  "workflowType": "AUTO_COLLECT",
  "scheduleDetails": {
    "scheduleId": "string",
    "scheduleNo": "string",
    "type": "RECURRING"
  },
  "instalmentDetails": {
    "index": 0,
    "cadence": { … }
  },
  "customFields": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "createdBy": "string",
  "applicableFees": [
    { … }
  ],
  "invoiceInput": {
    "issueInvoice": true,
    "itemsTaxType": "EXCLUSIVE",
    "items": [ … ]
  }
}

Bulk import payment requests

Request

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

How the imported payment requests are expected to be collected. Currently, only NONE is supported.

Enum"AUTO_COLLECT""ON_DEMAND""NONE"
Example: collectionMethod=NONE
deleteMissingPaymentRequestsbooleanrequired

Whether missing payment requests created in previous imports should be deleted.

Example: deleteMissingPaymentRequests=false
Bodymultipart/form-datarequired
inputFilestring(binary)required

Input file to be processed during the bulk import.

curl -i -X POST \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/payment_requests/bulk_import?collectionMethod=NONE&deleteMissingPaymentRequests=false' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F inputFile=string

Responses

The bulk import request has been accepted for processing.

Bodyapplication/json
jobIdstringrequired

The internal id of the bulk import job

typestringrequired

The type of the import job

Value"BULK_PAYMENT_REQUEST_IMPORT"
statusstringrequired

The status of the import job

Enum"PENDING""PROCESSING""COMPLETED""FAILED""DELETED"
creationTimestring(date-time)required

The creation time of the import job

countsByItemStatusArray of objects(ReviewSessionItemCountByStatus)required

The count of items for each review session item status

countsByItemStatus[].​statusstringrequired

The status of review session item

Enum"PENDING""PROCESSING""COMPLETED""FAILED"
countsByItemStatus[].​countinteger(int32)required

The count of items for this status

Response
application/json
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "BULK_PAYMENT_REQUEST_IMPORT",
  "status": "PENDING",
  "creationTime": "2024-01-15T10:30:00Z",
  "countsByItemStatus": []
}

Get the collection preferences for a payment request

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
paymentRequestIdstring(uuid)required

The identifier of the payment request.

curl -i -X GET \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/payment_requests/{paymentRequestId}/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.​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": { … },
    "mandateReminders": { … },
    "cardReminders": { … },
    "directDebitEncouragement": { … },
    "statements": { … },
    "lateFees": { … },
    "partialPayments": { … },
    "surcharging": { … }
  }
}

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