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 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

Direct debit mandates

Operations

Invoices

Operations

Recurring invoices

Operations

Payment requests

Operations

Get a payment request

Request

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

The ID of the payment request

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

Responses

The payment request is successfully retrieved

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

paidAmountnumber

The total amount that is paid

dueAmountnumber

The amount that is due

currencyCodestring

The default currency of the biller.. Possible values (non-exclusive): AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SPL, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TVD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMW, ZWD

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 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.
  • OVERDUE: THe payment request is not yet paid and is past the pay by date.
  • 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 is captured.
  • VOID: The payment request is voided.
  • SETTLED: The payment request is paid out. . Possible values (non-exclusive): DRAFT, UNPAID, OVERDUE, SCHEDULED, SUBMITTED, PAID, VOID, SETTLED
statusReasonCodestring

The reason why the invoice is in a certain status.

  • MISSING_PAYER_CONTACT_DETAILS - The invoice is missing the contact details of payer.
  • PENDING_ACTIVATION - The invoice is not yet distributed by Adfin.. Possible values (non-exclusive): MISSING_PAYER_CONTACT_DETAILS, PENDING_ACTIVATION, PENDING_DD_MANDATE, PENDING_DD_CAPABILITY, MARKED_AS_PAID, WORKFLOW_COMPLETED, NOTIFICATION_DELIVERY_FAILED, BULK_PRUNE, OTHER
statusReasonstring

Custom details on why the payment request is in a certain status

paymentRequestSourcestring

The source of the payment request. Possible values (non-exclusive): MANUAL, SCHEDULE, INVOICE, EXTERNAL, OVERPAYMENT

paymentsArray of objects(PaymentResponse)

The payments made as part of this payment request

discountsArray of objects(DiscountDetails)

The discounts applied to this payment request

paymentLinkobject(PaymentLinkDetails)

Payment link details.

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)

The customer details.

distributionobject(DistributionDetails)

Information about how a payment request is distributed and collected.

associationTypestring

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). Possible values (non-exclusive): SINGLE, ONE_TO_ONE, PARTIAL, BATCH
creditControlStatusstring

The credit control status of the payment request. Possible values (non-exclusive): AT_RISK, EXPECTED, CONFIRMED

workflowTypestring

The workflow type of the payment request. Possible values (non-exclusive): AUTO_COLLECT, ON_DEMAND, NONE

scheduleDetailsobject(ScheduleDetails)

The details about the schedule associated with a payment request

instalmentDetailsobject(InstalmentDetails)

Instalment details

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

Response
application/json
{
  "id": "string",
  "paymentRequestNo": "string",
  "reference": "string",
  "description": "string",
  "totalAmount": 0,
  "paidAmount": 0,
  "dueAmount": 0,
  "currencyCode": "string",
  "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": "string",
  "statusReasonCode": "string",
  "statusReason": "string",
  "paymentRequestSource": "string",
  "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": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ]
  },
  "distribution": {
    "collectionMethod": "string",
    "customMessage": "string",
    "templateId": "string"
  },
  "associationType": "string",
  "creditControlStatus": "string",
  "workflowType": "string",
  "scheduleDetails": {
    "scheduleId": "string",
    "scheduleNo": "string",
    "type": "string"
  },
  "instalmentDetails": {
    "index": 0,
    "cadence": { … }
  },
  "customFields": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "createdBy": "string"
}

Update a payment request

Request

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

The ID of the payment request

Bodyapplication/jsonrequired
paymentRequestNostring

The payment request number.

Example: "PR-1234"
descriptionstring[ 0 .. 200 ] characters

A short description or summary of the payment request.

Example: "Monthly subscription fee for January"
payByDatestring(date-time)

The pay by date for the payment request.

Example: "2025-12-15T23:59:59Z"
amountnumber>= 0.01required

The payment request amount

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

reference for the payment request

Example: "REF 123456"
taxRatenumber[ 0 .. 100 ]

tax rate percentage applied on the payment request amount.

Example: 20
redirectUrlstring

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

curl -i -X PUT \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/payment_requests/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "paymentRequestNo": "PR-1234",
    "description": "Monthly subscription fee for January",
    "payByDate": "2025-12-15T23:59:59Z",
    "amount": 99.99,
    "reference": "REF 123456",
    "taxRate": 20,
    "redirectUrl": "string"
  }'

Responses

The request has succeeded and has resulted in one payment request being updated

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

paidAmountnumber

The total amount that is paid

dueAmountnumber

The amount that is due

currencyCodestring

The default currency of the biller.. Possible values (non-exclusive): AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SPL, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TVD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMW, ZWD

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 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.
  • OVERDUE: THe payment request is not yet paid and is past the pay by date.
  • 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 is captured.
  • VOID: The payment request is voided.
  • SETTLED: The payment request is paid out. . Possible values (non-exclusive): DRAFT, UNPAID, OVERDUE, SCHEDULED, SUBMITTED, PAID, VOID, SETTLED
statusReasonCodestring

The reason why the invoice is in a certain status.

  • MISSING_PAYER_CONTACT_DETAILS - The invoice is missing the contact details of payer.
  • PENDING_ACTIVATION - The invoice is not yet distributed by Adfin.. Possible values (non-exclusive): MISSING_PAYER_CONTACT_DETAILS, PENDING_ACTIVATION, PENDING_DD_MANDATE, PENDING_DD_CAPABILITY, MARKED_AS_PAID, WORKFLOW_COMPLETED, NOTIFICATION_DELIVERY_FAILED, BULK_PRUNE, OTHER
statusReasonstring

Custom details on why the payment request is in a certain status

paymentRequestSourcestring

The source of the payment request. Possible values (non-exclusive): MANUAL, SCHEDULE, INVOICE, EXTERNAL, OVERPAYMENT

paymentsArray of objects(PaymentResponse)

The payments made as part of this payment request

discountsArray of objects(DiscountDetails)

The discounts applied to this payment request

paymentLinkobject(PaymentLinkDetails)

Payment link details.

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)

The customer details.

distributionobject(DistributionDetails)

Information about how a payment request is distributed and collected.

associationTypestring

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). Possible values (non-exclusive): SINGLE, ONE_TO_ONE, PARTIAL, BATCH
creditControlStatusstring

The credit control status of the payment request. Possible values (non-exclusive): AT_RISK, EXPECTED, CONFIRMED

workflowTypestring

The workflow type of the payment request. Possible values (non-exclusive): AUTO_COLLECT, ON_DEMAND, NONE

scheduleDetailsobject(ScheduleDetails)

The details about the schedule associated with a payment request

instalmentDetailsobject(InstalmentDetails)

Instalment details

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

Response
application/json
{
  "id": "string",
  "paymentRequestNo": "string",
  "reference": "string",
  "description": "string",
  "totalAmount": 0,
  "paidAmount": 0,
  "dueAmount": 0,
  "currencyCode": "string",
  "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": "string",
  "statusReasonCode": "string",
  "statusReason": "string",
  "paymentRequestSource": "string",
  "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": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ]
  },
  "distribution": {
    "collectionMethod": "string",
    "customMessage": "string",
    "templateId": "string"
  },
  "associationType": "string",
  "creditControlStatus": "string",
  "workflowType": "string",
  "scheduleDetails": {
    "scheduleId": "string",
    "scheduleNo": "string",
    "type": "string"
  },
  "instalmentDetails": {
    "index": 0,
    "cadence": { … }
  },
  "customFields": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "createdBy": "string"
}

Void a payment request

Request

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

The ID of the payment request

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

Responses

The payment request has been voided

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.. Possible values (non-exclusive): 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": "string",
    "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)

Information about how an invoice or payment request is distributed and collected.

This defines:

  • The method by which payment is expected to be collected.
  • The workflow template used to send the invoice or payment request.
  • Optional custom message for the customer.
  • Approval status for automatically distributing to the customer.
Example: {"collectionMethod":"AUTO_COLLECT","templateId":"d290f1ee-6c54-4b01-90e6-d701748f0851","customMessage":"Thank you for your business!","approvedForSending":true}
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",
      "templateId": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "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.

statusesstring

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
associationTypesstring

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.

payByStartDatestring

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

payByEndDatestring

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

createdStartDatestring

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

createdEndDatestring

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

paidStartTimestring

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

paidEndTimestring

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

lastUpdatedStartTimestring

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

lastUpdatedEndTimestring

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

paymentLinkLastSeenTimestring

The start time before which the payment link was seen.

paymentInitiationDatestring(date-time)
searchTextstring

The text to search for in the payment requests.

includeCountstring

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

creditControlStatusesstring

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.
cashflowStatusesstring

The cashflow status of the payment request.

  • UNPAID – not yet paid.
  • PROCESSING – expected to be paid.
  • PAID_OUT – already paid out.
cashflowPeriodStartDatestring

Start of the cashflow period (inclusive)

cashflowPeriodEndDatestring

End of the cashflow period (inclusive)

directDebitMandateStatusesstring

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.
workflowTypesstring

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
minAmountstring>= 0

amount greater than or equal to

maxAmountstring>= 0

amount less than or equal to

scheduleIdstring

The id of the schedule associated to the payment request.

fieldValueIdsstring

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=string&associationTypes=string&payByStartDate=string&payByEndDate=string&createdStartDate=string&createdEndDate=string&paidStartTime=string&paidEndTime=string&lastUpdatedStartTime=string&lastUpdatedEndTime=string&paymentLinkLastSeenTime=string&paymentInitiationDate=2019-08-24T14%3A15%3A22Z&searchText=string&includeCount=string&creditControlStatuses=string&cashflowStatuses=string&cashflowPeriodStartDate=string&cashflowPeriodEndDate=string&directDebitMandateStatuses=string&workflowTypes=string&minAmount=string&maxAmount=string&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)

Payment request count details

paginationobject(Pagination)

Contains pagination information for a set of results

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

Create a payment request

Request

Security
Biller Access Token (Staging) or Biller Access Token (Production)
Bodyapplication/jsonrequired
customerobject(CustomerDetails)required

Contains the unique identifier for the customer.

Example: {"id":"80349480-490b-4234-92e7-fad697e3d446"}
customer.​idstringrequired

The Adfin ID of the customer.

Example: "80349480-490b-4234-92e7-fad697e3d446"
descriptionstring[ 0 .. 200 ] charactersrequired

A short description or summary of the payment request.

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

The payment request amount.

Example: 100
currencyCodestringrequired

The default currency of the biller.. Possible values (non-exclusive): AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SPL, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TVD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMW, ZWD

Example: "GBP"
taxRatenumber[ 0 .. 100 ]

Optional tax rate percentage applied on the payment request amount.

Example: 20
referencestring[ 0 .. 18 ] 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)

Information about how a payment request is distributed and collected.

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": "80349480-490b-4234-92e7-fad697e3d446"
    },
    "description": "Monthly subscription fee for January",
    "totalAmount": 100,
    "currencyCode": "GBP",
    "taxRate": 20,
    "reference": "REF 123456",
    "payByDate": "2025-03-25T11:36:55.243Z",
    "distribution": {
      "collectionMethod": "string",
      "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

paidAmountnumber

The total amount that is paid

dueAmountnumber

The amount that is due

currencyCodestring

The default currency of the biller.. Possible values (non-exclusive): AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHF, CLP, CNY, COP, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GGP, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, IMP, INR, IQD, IRR, ISK, JEP, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SPL, SRD, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TVD, TWD, TZS, UAH, UGX, USD, UYU, UZS, VEF, VND, VUV, WST, XAF, XCD, XDR, XOF, XPF, YER, ZAR, ZMW, ZWD

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 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.
  • OVERDUE: THe payment request is not yet paid and is past the pay by date.
  • 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 is captured.
  • VOID: The payment request is voided.
  • SETTLED: The payment request is paid out. . Possible values (non-exclusive): DRAFT, UNPAID, OVERDUE, SCHEDULED, SUBMITTED, PAID, VOID, SETTLED
statusReasonCodestring

The reason why the invoice is in a certain status.

  • MISSING_PAYER_CONTACT_DETAILS - The invoice is missing the contact details of payer.
  • PENDING_ACTIVATION - The invoice is not yet distributed by Adfin.. Possible values (non-exclusive): MISSING_PAYER_CONTACT_DETAILS, PENDING_ACTIVATION, PENDING_DD_MANDATE, PENDING_DD_CAPABILITY, MARKED_AS_PAID, WORKFLOW_COMPLETED, NOTIFICATION_DELIVERY_FAILED, BULK_PRUNE, OTHER
statusReasonstring

Custom details on why the payment request is in a certain status

paymentRequestSourcestring

The source of the payment request. Possible values (non-exclusive): MANUAL, SCHEDULE, INVOICE, EXTERNAL, OVERPAYMENT

paymentsArray of objects(PaymentResponse)

The payments made as part of this payment request

discountsArray of objects(DiscountDetails)

The discounts applied to this payment request

paymentLinkobject(PaymentLinkDetails)

Payment link details.

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)

The customer details.

distributionobject(DistributionDetails)

Information about how a payment request is distributed and collected.

associationTypestring

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). Possible values (non-exclusive): SINGLE, ONE_TO_ONE, PARTIAL, BATCH
creditControlStatusstring

The credit control status of the payment request. Possible values (non-exclusive): AT_RISK, EXPECTED, CONFIRMED

workflowTypestring

The workflow type of the payment request. Possible values (non-exclusive): AUTO_COLLECT, ON_DEMAND, NONE

scheduleDetailsobject(ScheduleDetails)

The details about the schedule associated with a payment request

instalmentDetailsobject(InstalmentDetails)

Instalment details

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

Response
application/json
{
  "id": "string",
  "paymentRequestNo": "string",
  "reference": "string",
  "description": "string",
  "totalAmount": 0,
  "paidAmount": 0,
  "dueAmount": 0,
  "currencyCode": "string",
  "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": "string",
  "statusReasonCode": "string",
  "statusReason": "string",
  "paymentRequestSource": "string",
  "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": { … },
    "timezone": "string",
    "discount": { … },
    "externalData": [ … ],
    "tags": [ … ]
  },
  "distribution": {
    "collectionMethod": "string",
    "customMessage": "string",
    "templateId": "string"
  },
  "associationType": "string",
  "creditControlStatus": "string",
  "workflowType": "string",
  "scheduleDetails": {
    "scheduleId": "string",
    "scheduleNo": "string",
    "type": "string"
  },
  "instalmentDetails": {
    "index": 0,
    "cadence": { … }
  },
  "customFields": [
    { … }
  ],
  "tags": [
    "string"
  ],
  "createdBy": "string"
}

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.

Example: collectionMethod=NONE
deleteMissingPaymentRequestsstringrequired

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. Possible values (non-exclusive): BULK_PAYMENT_REQUEST_IMPORT

statusstringrequired

The status of the import job. Possible values (non-exclusive): 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. Possible values (non-exclusive): 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": []
}

Retrieve bulk payment request import job details

Request

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

The ID of the bulk payment request import job

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

Responses

The bulk payment request import job details were successfully retrieved.

Bodyapplication/json
jobIdstringrequired

The internal id of the bulk import job

typestringrequired

The type of the import job. Possible values (non-exclusive): BULK_PAYMENT_REQUEST_IMPORT

statusstringrequired

The status of the import job. Possible values (non-exclusive): 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. Possible values (non-exclusive): 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": "COMPLETED",
  "creationTime": "2024-01-15T10:30:00Z",
  "countsByItemStatus": [
    { … },
    { … }
  ]
}

Retrieve bulk payment request import job items

Request

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

The ID of the bulk payment request import job

Query
statusesstring

The status of the bulk payment request import job item

  • PENDING: The item is still to be processed.
  • PROCESSING: The item is currently processing.
  • COMPLETED: The item has been processed.
  • FAILED: The item has failed to be processed.
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,ASC"]
curl -i -X GET \
  'https://developer.adfin.com/_mock/products/direct-integration/direct-integration-api-reference/payment_requests/bulk_import/{jobId}/items?statuses=string&page=0&size=20&sort=creationTime%2CASC' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Paginated response for the list of bulk payment request import job items

Bodyapplication/json
itemsArray of objects(BulkPaymentRequestImportItemResponse)

The bulk payment request import job items for the current page

paginationobject(Pagination)

Contains pagination information for a set of results

Response
application/json
{
  "items": [
    { … },
    { … }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 155,
    "totalPages": 8
  }
}

Cancel a payment requestDeprecated

Request

This endpoint is deprecated and will be removed in a future release. Use /{id}:void instead

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

The ID of the payment request

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

Responses

The payment request has been cancelled

Recurring payment requests

Operations

Payments

Operations

Tax rates

Operations

Items

Operations

Workflows

Operations

Webhooks

Operations