# Adfin API 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`. Version: 1.0.0 ## Servers Production API Server URL ``` https://api.adfin.com/api ``` Staging API Server URL ``` https://api.staging.adfin.com/api ``` ## Security ### Biller Access Token (Production) Type: oauth2 ### Platform Bearer Token Type: http Scheme: Bearer ### Biller Access Token (Staging) Type: oauth2 ## Download OpenAPI description [Adfin API](https://developer.adfin.com/_bundle/api-docs/prod.yaml) ## oAuth2 ### Issue an OAuth 2.0 access token - [POST /oauth2/token](https://developer.adfin.com/api-docs/prod/oauth2/issueoauth2token.md) ### Revoke an OAuth2 Refresh token - [POST /oauth2/revoke](https://developer.adfin.com/api-docs/prod/oauth2/revokeoauth2refreshtoken.md) ### Authorize an app to access Adfin data on behalf of an Adfin user - [POST /oauth2/authorize](https://developer.adfin.com/api-docs/prod/oauth2/authorize.md) ### Get the authorization details for an app - [GET /oauth2/authorization](https://developer.adfin.com/api-docs/prod/oauth2/getappauthorizationdetails.md) ## Biller ### Retrieves a biller - [GET /biller](https://developer.adfin.com/api-docs/prod/biller/getbiller.md): Fetches the details of the authenticated user's associated biller. Returns a 404 if no biller is found. ### Patch a Biller - [PATCH /biller](https://developer.adfin.com/api-docs/prod/biller/patchbiller.md): Applies JSON Patch operations to update specific biller fields. ## Customers ### Retrieve a list of customers by filter - [GET /customers](https://developer.adfin.com/api-docs/prod/customers/getcustomers.md) ### Update a customer - [PUT /customers](https://developer.adfin.com/api-docs/prod/customers/putcustomer.md) ### Create a customer - [POST /customers](https://developer.adfin.com/api-docs/prod/customers/createcustomer.md) ### Retrieve a customer - [GET /customers/{id}](https://developer.adfin.com/api-docs/prod/customers/getcustomerbyid.md) ### Update a customer by id - [PUT /customers/{id}](https://developer.adfin.com/api-docs/prod/customers/updatecustomerbyid.md) ### Upsert customer workflow settings - [PUT /customers/workflow_settings](https://developer.adfin.com/api-docs/prod/customers/upsertworkflowsettings.md) ### Upsert customer payment settings - [PUT /customers/payment_settings](https://developer.adfin.com/api-docs/prod/customers/upsertpaymentsettings.md) ### Retrieve customer workflow settings - [GET /customers/{id}/workflow_settings](https://developer.adfin.com/api-docs/prod/customers/getworkflowsettings.md) ### Retrieve customer payment settings - [GET /customers/{id}/payment_settings](https://developer.adfin.com/api-docs/prod/customers/getpaymentsettings.md) ## Direct debit mandates ### Retrieve a direct debit mandates by customer - [GET /customers/{id}/directdebitmandates](https://developer.adfin.com/api-docs/prod/direct-debit-mandates/getdirectdebitmandatesbycustomerid.md) ### Create a direct debit mandate - [PUT /customers/{id}/directdebitmandates](https://developer.adfin.com/api-docs/prod/direct-debit-mandates/create.md): The request body is optional and may contain only a redirectUrl. Bank details cannot be submitted through the API: the customer authorises the mandate themselves via the url returned in the response. In staging, you can open that link yourself and complete it with test bank details. ### Reinstate a cancelled direct debit mandate - [PUT /customers/directdebitmandates/{id}:reinstate](https://developer.adfin.com/api-docs/prod/direct-debit-mandates/reinstatedirectdebitmandate.md) ### Cancel a direct debit mandate - [PUT /customers/directdebitmandates/{id}:cancel](https://developer.adfin.com/api-docs/prod/direct-debit-mandates/canceldirectdebitmandate.md) ### Search direct debit mandates by filters - [GET /customers/directdebitmandates](https://developer.adfin.com/api-docs/prod/direct-debit-mandates/searchdirectdebitmandates.md) ### Retrieve a direct debit mandate - [GET /customers/directdebitmandates/{id}](https://developer.adfin.com/api-docs/prod/direct-debit-mandates/getdirectdebitmandate.md) ## Invoices ### Get an invoice by its id - [GET /invoices/{id}](https://developer.adfin.com/api-docs/prod/invoices/getinvoice.md) ### Update an invoice - [PUT /invoices/{id}](https://developer.adfin.com/api-docs/prod/invoices/putinvoice.md) ### Void an invoice - [PUT /invoices/{id}:void](https://developer.adfin.com/api-docs/prod/invoices/voidinvoice.md) ### Manually mark an invoice as paid - [PUT /invoices/{id}:mark-as-paid](https://developer.adfin.com/api-docs/prod/invoices/markinvoiceaspaid.md) ### Activate (send) an invoice - [PUT /invoices/{id}:activate](https://developer.adfin.com/api-docs/prod/invoices/activateinvoice.md) ### Retrieve a list of invoices by filter - [GET /invoices](https://developer.adfin.com/api-docs/prod/invoices/getinvoices.md) ### Create an invoice - [POST /invoices](https://developer.adfin.com/api-docs/prod/invoices/createinvoice.md) ### Preview instalment plan for an invoice - [POST /invoices/{invoiceId}/instalments/preview](https://developer.adfin.com/api-docs/prod/invoices/previewinstalmentforinvoice.md) ### Get the file for a specific invoice - [GET /invoices/{id}/file](https://developer.adfin.com/api-docs/prod/invoices/getfile.md) ## Recurring invoices ### Retrieve a recurring invoice - [GET /schedules/invoices/{id}](https://developer.adfin.com/api-docs/prod/recurring-invoices/getrecurringinvoicebyid.md) ### Update a recurring invoice - [PUT /schedules/invoices/{id}](https://developer.adfin.com/api-docs/prod/recurring-invoices/updaterecurringinvoice.md) ### Delete a recurring invoice - [DELETE /schedules/invoices/{id}](https://developer.adfin.com/api-docs/prod/recurring-invoices/deleterecurringinvoice.md) ### Cancel a recurring invoice - [PUT /schedules/invoices/{id}:cancel](https://developer.adfin.com/api-docs/prod/recurring-invoices/cancelrecurringinvoice.md) ### Activate a recurring invoice - [PUT /schedules/invoices/{id}:activate](https://developer.adfin.com/api-docs/prod/recurring-invoices/activaterecurringinvoice.md) ### Create a recurring invoice - [POST /schedules/invoices](https://developer.adfin.com/api-docs/prod/recurring-invoices/postrecurringinvoice.md): The recurring invoice is created as a draft. Nothing is generated or sent to the customer until it is activated, either via PUT /schedules/invoices/{id}:activate or from the console. ## Payment requests ### Get a payment request - [GET /payment_requests/{id}](https://developer.adfin.com/api-docs/prod/payment-requests/getpr.md) ### Update a payment request - [PUT /payment_requests/{id}](https://developer.adfin.com/api-docs/prod/payment-requests/putpaymentrequest.md) ### Void a payment request - [PUT /payment_requests/{id}:void](https://developer.adfin.com/api-docs/prod/payment-requests/voidpr.md) ### Manually mark a standalone payment request as paid - [PUT /payment_requests/{id}:mark-as-paid](https://developer.adfin.com/api-docs/prod/payment-requests/markpraspaid.md) ### Cancel auto-collection on the next failure - [PUT /payment_requests/{id}:cancel-collection-on-failure](https://developer.adfin.com/api-docs/prod/payment-requests/cancelcollectiononfailure.md): Marks this payment request so that, if its next auto-collection attempt fails, further collection retries are cancelled and the workflow transitions off auto-collect. ### Activate (send) a payment request - [PUT /payment_requests/{id}:activate](https://developer.adfin.com/api-docs/prod/payment-requests/activatepr.md) ### Update the distribution details of payment requests - [PUT /payment_requests/distribution](https://developer.adfin.com/api-docs/prod/payment-requests/updatedistributiondetails.md) ### Retrieve a list of payment requests by filter - [GET /payment_requests](https://developer.adfin.com/api-docs/prod/payment-requests/getpaymentrequests.md) ### Create a payment request - [POST /payment_requests](https://developer.adfin.com/api-docs/prod/payment-requests/postpaymentrequest.md) ### Bulk import payment requests - [POST /payment_requests/bulk_import](https://developer.adfin.com/api-docs/prod/payment-requests/bulkimport.md) ### Retrieve bulk payment request import job details - [GET /payment_requests/bulk_import/{jobId}](https://developer.adfin.com/api-docs/prod/payment-requests/getbulkpaymentrequestimportjobdetails.md) ### Retrieve bulk payment request import job items - [GET /payment_requests/bulk_import/{jobId}/items](https://developer.adfin.com/api-docs/prod/payment-requests/getbulkpaymentrequestimportjobitems.md) ### Cancel a payment request (deprecated) - [PUT /payment_requests/{id}:cancel](https://developer.adfin.com/api-docs/prod/payment-requests/cancelpr.md): This endpoint is deprecated and will be removed in a future release. Use /{id}:void instead ## Recurring payment requests ### Retrieve a recurring payment request by its ID - [GET /schedules/payment_requests/{id}](https://developer.adfin.com/api-docs/prod/recurring-payment-requests/getrecurringpaymentrequestbyid.md) ### Update a recurring payment request - [PUT /schedules/payment_requests/{id}](https://developer.adfin.com/api-docs/prod/recurring-payment-requests/updaterecurringpaymentrequest.md) ### Delete a recurring payment request - [DELETE /schedules/payment_requests/{id}](https://developer.adfin.com/api-docs/prod/recurring-payment-requests/deleterecurringpaymentrequest.md) ### Cancel a recurring payment request - [PUT /schedules/payment_requests/{id}:cancel](https://developer.adfin.com/api-docs/prod/recurring-payment-requests/cancelrecurringpaymentrequest.md) ### Create a recurring payment request - [POST /schedules/payment_requests](https://developer.adfin.com/api-docs/prod/recurring-payment-requests/postrecurringpaymentrequest.md) ## Payments ### Import a payment - [POST /payments:import](https://developer.adfin.com/api-docs/prod/payments/importpayment.md): Import a payment against an invoice with a custom reference. ## Tax rates ### Retrieve tax rate options - [GET /catalogs/tax_rates](https://developer.adfin.com/api-docs/prod/tax-rates/gettaxratecataloguesforbiller.md) ## Items ### Get line item catalogue items for a given filter - [GET /catalogs/items](https://developer.adfin.com/api-docs/prod/items/postlineitemcatalogueelement.md) ## Workflows Manage workflow configurations ### Create a new workflow - [PUT /workflows](https://developer.adfin.com/api-docs/prod/workflows/createworkflow.md) ## Webhooks ### Retrieve a webhook - [GET /apps/{clientId}/webhooks/{webhookId}](https://developer.adfin.com/api-docs/prod/webhooks/getwebhookbyid.md) ### Update a webhook - [PUT /apps/{clientId}/webhooks/{webhookId}](https://developer.adfin.com/api-docs/prod/webhooks/updatewebhook.md) ### Delete a webhook - [DELETE /apps/{clientId}/webhooks/{webhookId}](https://developer.adfin.com/api-docs/prod/webhooks/deletewebhook.md) ### Generate or replace the webhook signing secret key - [PUT /apps/{clientId}/webhooks/digest](https://developer.adfin.com/api-docs/prod/webhooks/generatewebhooksecretkey.md) ### Create or update the authentication method and credentials for webhook target URLs - [PUT /apps/{clientId}/webhooks/auth](https://developer.adfin.com/api-docs/prod/webhooks/storewebhookauthentication.md) ### Retrieve webhooks for a clientId - [GET /apps/{clientId}/webhooks](https://developer.adfin.com/api-docs/prod/webhooks/getwebhooks.md) ### Create a webhook - [POST /apps/{clientId}/webhooks](https://developer.adfin.com/api-docs/prod/webhooks/createwebhook.md) ## Customer Autopilot Settings Operations for managing customer-level autopilot settings ### Retrieve autopilot guidance for a customer. - [GET /customers/{customerId}/autopilot_settings](https://developer.adfin.com/api-docs/prod/customer-autopilot-settings/getcustomerautopilotsettings.md) ### Create or update autopilot guidance for a customer. - [PUT /customers/{customerId}/autopilot_settings](https://developer.adfin.com/api-docs/prod/customer-autopilot-settings/upsertcustomerautopilotsettings.md) ### Delete autopilot guidance for a customer. - [DELETE /customers/{customerId}/autopilot_settings](https://developer.adfin.com/api-docs/prod/customer-autopilot-settings/deletecustomerautopilotsettings.md) ## Card on file ### Remove a customer's card on file - [PUT /customers/{customerId}/cards_on_file/{cardOnFileId}:remove](https://developer.adfin.com/api-docs/prod/card-on-file/removecardonfile.md) ### Request card details from a customer - [PUT /customers/{customerId}/card_on_file:request](https://developer.adfin.com/api-docs/prod/card-on-file/requestcarddetails.md) ### List a customer's cards on file - [GET /customers/{customerId}/cards_on_file](https://developer.adfin.com/api-docs/prod/card-on-file/getcardsonfile.md)