{ "openapi": "3.1.0", "info": { "title": "Adfin API", "description": "Adfin uses OAuth 2.0 access tokens to authenticate all API requests.\n\nThere are two contexts in which tokens are issued:\n\n- **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.).\n\n- **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": [ { "url": "https://api.adfin.com/api", "description": "Production API Server URL" }, { "url": "https://api.staging.adfin.com/api", "description": "Staging API Server URL" } ], "security": [ { "Biller Access Token (Production)": [] }, { "Biller Access Token (Staging)": [] }, { "Adfin Bearer Token": [] } ], "tags": [ { "name": "oAuth2" }, { "name": "Biller" }, { "name": "Customers" }, { "name": "Direct debit mandates" }, { "name": "Invoices" }, { "name": "Recurring invoices" }, { "name": "Payment requests" }, { "name": "Recurring payment requests" }, { "name": "Payments" }, { "name": "Tax rates" }, { "name": "Items" }, { "name": "Workflows", "description": "Manage workflow configurations" }, { "name": "Workflows" }, { "name": "Webhooks" }, { "name": "Customer Autopilot Settings", "description": "Operations for managing customer-level autopilot settings" } ], "paths": { "/workflows": { "put": { "tags": [ "Workflows" ], "summary": "Create a new workflow", "operationId": "createWorkflow", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowRequest" } } }, "required": true }, "responses": { "200": { "description": "The request was successful, resulting in the creation of one workflow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowResponse" } } } }, "400": { "description": "There was an issue reading or understanding the request. Please ensure that it adheres to the required format and includes all necessary parameters." }, "401": { "description": "Authentication is required." }, "422": { "description": "A validation error occurred with the request." }, "500": { "description": "The server was unable to process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/schedules/payment_requests/{id}": { "get": { "tags": [ "Recurring payment requests" ], "summary": "Retrieve a recurring payment request by its ID", "operationId": "getRecurringPaymentRequestById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentRequestResponse" } } } }, "201": { "description": "The request was successful and the recurring payment request was retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentRequestResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "404": { "description": "Recurring payment request does not exist." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "put": { "tags": [ "Recurring payment requests" ], "summary": "Update a recurring payment request", "operationId": "updateRecurringPaymentRequest", "parameters": [ { "name": "id", "in": "path", "description": "The Adfin ID of the recurring payment request", "required": true, "schema": { "type": "string", "description": "The Adfin ID of the recurring payment request" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRecurringPaymentRequestRequest" } } }, "required": true }, "responses": { "200": { "description": "The request has succeeded and has resulted in one recurring payment request being updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoiceResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentRequestResponse" } } } }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "delete": { "tags": [ "Recurring payment requests" ], "summary": "Delete a recurring payment request", "operationId": "deleteRecurringPaymentRequest", "parameters": [ { "name": "id", "in": "path", "description": "The Adfin ID of the recurring payment request to be deleted", "required": true, "schema": { "type": "string", "description": "The Adfin ID of the recurring payment request to be deleted" } } ], "responses": { "204": { "description": "The recurring payment request was deleted" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/schedules/payment_requests/{id}:cancel": { "put": { "tags": [ "Recurring payment requests" ], "summary": "Cancel a recurring payment request", "operationId": "cancelRecurringPaymentRequest", "parameters": [ { "name": "id", "in": "path", "description": "The Adfin ID of the recurring payment request", "required": true, "schema": { "type": "string", "description": "The Adfin ID of the recurring payment request" } } ], "responses": { "200": { "description": "The recurring payment request has been cancelled" }, "404": { "description": "No recurring payment request can be found" }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/schedules/invoices/{id}": { "get": { "tags": [ "Recurring invoices" ], "summary": "Retrieve a recurring invoice", "operationId": "getRecurringInvoiceById", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoiceResponse" } } } }, "201": { "description": "The request was successful and the recurring invoice was retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoiceResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "404": { "description": "Recurring invoice does not exist." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "put": { "tags": [ "Recurring invoices" ], "summary": "Update a recurring invoice", "operationId": "updateRecurringInvoice", "parameters": [ { "name": "id", "in": "path", "description": "The Adfin ID of the recurring invoice", "required": true, "schema": { "type": "string", "description": "The Adfin ID of the recurring invoice" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRecurringInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "The request has succeeded and has resulted in one recurring invoice being updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoiceResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoiceResponse" } } } }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "delete": { "tags": [ "Recurring invoices" ], "summary": "Delete a recurring invoice", "operationId": "deleteRecurringInvoice", "parameters": [ { "name": "id", "in": "path", "description": "The Adfin ID of the recurring invoice to be deleted", "required": true, "schema": { "type": "string", "description": "The Adfin ID of the recurring invoice to be deleted" } } ], "responses": { "204": { "description": "The recurring invoice was deleted" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/schedules/invoices/{id}:cancel": { "put": { "tags": [ "Recurring invoices" ], "summary": "Cancel a recurring invoice", "operationId": "cancelRecurringInvoice", "parameters": [ { "name": "id", "in": "path", "description": "The Adfin ID of the recurring invoice", "required": true, "schema": { "type": "string", "description": "The Adfin ID of the recurring invoice" } } ], "responses": { "200": { "description": "The recurring invoice has been cancelled" }, "404": { "description": "No recurring invoice can be found" }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/schedules/invoices/{id}:activate": { "put": { "tags": [ "Recurring invoices" ], "summary": "Activate a recurring invoice", "operationId": "activateRecurringInvoice", "parameters": [ { "name": "id", "in": "path", "description": "The Adfin ID of the recurring invoice", "required": true, "schema": { "type": "string", "description": "The Adfin ID of the recurring invoice" } } ], "responses": { "200": { "description": "The recurring invoice has been activated" }, "404": { "description": "No recurring invoice can be found" }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/payment_requests/{id}": { "get": { "tags": [ "Payment requests" ], "summary": "Get a payment request", "operationId": "getPr", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the payment request", "required": true, "schema": { "type": "string", "description": "The ID of the payment request" } } ], "responses": { "200": { "description": "The payment request is successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestResponse" } } } }, "404": { "description": "No payment request can be found" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "put": { "tags": [ "Payment requests" ], "summary": "Update a payment request", "operationId": "putPaymentRequest", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the payment request", "required": true, "schema": { "type": "string", "description": "The ID of the payment request" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentRequestRequest" } } }, "required": true }, "responses": { "200": { "description": "The request has succeeded and has resulted in one payment request being updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestResponse" } } } }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/payment_requests/{id}:void": { "put": { "tags": [ "Payment requests" ], "summary": "Void a payment request", "operationId": "voidPr", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the payment request", "required": true, "schema": { "type": "string", "description": "The ID of the payment request" } } ], "responses": { "200": { "description": "The payment request has been voided" }, "404": { "description": "No payment request can be found" }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/payment_requests/{id}:mark-as-paid": { "put": { "tags": [ "Payment requests" ], "summary": "Manually mark a standalone payment request as paid", "operationId": "markPrAsPaid", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the payment request", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the payment request" } } ], "responses": { "200": { "description": "The payment request has been marked as paid" }, "404": { "description": "No payment request can be found" }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/payment_requests/{id}:cancel": { "put": { "tags": [ "Payment requests" ], "summary": "Cancel a payment request", "description": "This endpoint is deprecated and will be removed in a future release. Use /{id}:void instead", "operationId": "cancelPr", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the payment request", "required": true, "schema": { "type": "string", "description": "The ID of the payment request" } } ], "responses": { "200": { "description": "The payment request has been cancelled" }, "404": { "description": "No payment request can be found" }, "500": { "description": "The server could not process the request." } }, "deprecated": true, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/payment_requests/{id}:cancel-collection-on-failure": { "put": { "tags": [ "Payment requests" ], "summary": "Cancel auto-collection on the next failure", "description": "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.", "operationId": "cancelCollectionOnFailure", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the payment request", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the payment request" } } ], "responses": { "200": { "description": "The intent has been recorded on the payment request" }, "404": { "description": "No payment request can be found" }, "422": { "description": "The payment request is not in a state where the intent can be recorded" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/payment_requests/{id}:activate": { "put": { "tags": [ "Payment requests" ], "summary": "Activate (send) a payment request", "operationId": "activatePr", "parameters": [ { "name": "id", "in": "path", "description": "The id of the payment request", "required": true, "schema": { "type": "string", "description": "The id of the payment request" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "The payment request was activated" }, "400": { "description": "The payment request can not be activated" }, "404": { "description": "The payment request does not exist" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/payment_requests/distribution": { "put": { "tags": [ "Payment requests" ], "summary": "Update the distribution details of payment requests", "operationId": "updateDistributionDetails", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDistributionDetailsRequest" } } }, "required": true }, "responses": { "200": { "description": "The distribution details were updated" }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/invoices/{id}": { "get": { "tags": [ "Invoices" ], "summary": "Get an invoice by its id", "operationId": "getInvoice", "parameters": [ { "name": "id", "in": "path", "description": "The id of the invoice to get the details for", "required": true, "schema": { "type": "string", "description": "The id of the invoice to get the details for" } } ], "responses": { "200": { "description": "The Invoice data is successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "404": { "description": "The invoice cannot be found" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "put": { "tags": [ "Invoices" ], "summary": "Update an invoice", "operationId": "putInvoice", "parameters": [ { "name": "id", "in": "path", "description": "The id of the invoice being updated", "required": true, "schema": { "type": "string", "description": "The id of the invoice being updated" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "The request was successful and the invoice was updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/invoices/{id}:void": { "put": { "tags": [ "Invoices" ], "summary": "Void an invoice", "operationId": "voidInvoice", "parameters": [ { "name": "id", "in": "path", "description": "The id of the invoice", "required": true, "schema": { "type": "string", "description": "The id of the invoice" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "The invoice was voided" }, "400": { "description": "The invoice can not be voided" }, "404": { "description": "The invoice does not exist" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/invoices/{id}:mark-as-paid": { "put": { "tags": [ "Invoices" ], "summary": "Manually mark an invoice as paid", "operationId": "markInvoiceAsPaid", "parameters": [ { "name": "id", "in": "path", "description": "The id of the invoice to be marked as paid", "required": true, "schema": { "type": "string", "description": "The id of the invoice to be marked as paid" } } ], "responses": { "200": { "description": "The invoice was successfully marked as paid" }, "404": { "description": "The invoice cannot be found" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/invoices/{id}:activate": { "put": { "tags": [ "Invoices" ], "summary": "Activate (send) an invoice", "operationId": "activateInvoice", "parameters": [ { "name": "id", "in": "path", "description": "The id of the invoice", "required": true, "schema": { "type": "string", "description": "The id of the invoice" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "The invoice was activated" }, "400": { "description": "The invoice can not be activated" }, "404": { "description": "The invoice does not exist" } } } }, "/customers": { "get": { "tags": [ "Customers" ], "summary": "Retrieve a list of customers by filter", "operationId": "getCustomers", "parameters": [ { "name": "onlyCustomersWithActivity", "in": "query", "description": "Filter customers that have any financial activity (invoices, direct debits)", "required": false, "schema": { "type": "boolean", "description": "Filter customers that have any financial activity (invoices, direct debits)" } }, { "name": "searchText", "in": "query", "description": "Fuzzy search a customer based on a text", "required": false, "schema": { "type": "string", "description": "Fuzzy search a customer based on a text" } }, { "name": "ddMandateSignedStartTime", "in": "query", "description": "Filter customers that have signed their direct debit mandate after this date", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Filter customers that have signed their direct debit mandate after this date" } }, { "name": "ddMandateSignedEndTime", "in": "query", "description": "Filter customers that have signed their direct debit mandate until this date", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Filter customers that have signed their direct debit mandate until this date" } }, { "name": "ddMandateStatuses", "in": "query", "description": "The status of the latest direct debit mandate", "required": false, "schema": { "type": "array", "description": "The status of the latest direct debit mandate", "items": { "type": "string", "description": "The status of the Direct Debit Mandate, if any present.\n* CREATED: The Direct Debit Mandate was created with success.\n* PENDING: The Direct Debit Mandate was signed and accepted by the customer and it is in the Payment Provider's accepted timeframe.\n* ACTIVE: The Direct Debit Mandate was confirmed by the Payment Provider.\n* PENDING_CANCELLATION: The biller requested cancellation while a payment is in flight; the cancellation will fire once the payment resolves.\n* CANCELLED: The Direct Debit Mandate was cancelled directly by the customer.\n* MIGRATING: The Direct Debit Mandate is in process of migrating from one payment provider to another.", "enum": [ "CREATED", "PENDING", "ACTIVE", "PENDING_CANCELLATION", "CANCELLED", "MIGRATING" ] } } }, { "name": "includeCustomerFinancialDetails", "in": "query", "description": "This flag determines whether the response should include the financial status of the customer's invoices and payments", "required": false, "schema": { "type": "boolean", "description": "This flag determines whether the response should include the financial status of the customer's invoices and payments" } }, { "name": "financialStatuses", "in": "query", "description": "The financial statuses of the payment situation of the customer", "required": false, "schema": { "type": "array", "description": "The financial statuses of the payment situation of the customer", "items": { "type": "string", "description": "The status of the current payments situation of the customer.\n* DRAFT: The customer has draft invoices\n* OUTSTANDING: The customer has issued invoices waiting to be paid.\n* PENDING_PAYMENTS: The customer direct debits still being processed but not yet successfully covered.\n* FULLY_PAID: The customer has all its invoices fully paid and direct debits fully covered.\n* OVERDUE: The customer has invoices not yet paid which have passed their due date.", "enum": [ "DRAFT", "OUTSTANDING", "PENDING_PAYMENTS", "OVERDUE", "FULLY_PAID", "NO_INVOICES" ] } } }, { "name": "lastUpdatedStartTime", "in": "query", "description": "The start time after which the customer last updated time should be, including the start time.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start time after which the customer last updated time should be, including the start time." } }, { "name": "tagIds", "in": "query", "description": "The tag ids of the customer", "required": false, "schema": { "type": "array", "description": "The tag ids of the customer", "items": { "type": "string", "description": "The tag ids of the customer" } } }, { "name": "customerIds", "in": "query", "description": "The ids of the customers", "required": false, "schema": { "type": "array", "description": "The ids of the customers", "items": { "type": "string", "description": "The ids of the customers" } } }, { "name": "page", "in": "query", "description": "Zero-based page index (0..N)", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "size", "in": "query", "description": "The size of the page to be returned", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "required": false, "schema": { "type": "array", "default": [ "creationTime,DESC" ], "items": { "type": "string" } } } ], "responses": { "200": { "description": "The list of customers for the specified filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomersResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required - Invalid or missing authorization headers." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "put": { "tags": [ "Customers" ], "summary": "Update a customer", "operationId": "putCustomer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerRequest" } } }, "required": true }, "responses": { "200": { "description": "The request has succeeded and has resulted in one customer being updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "post": { "tags": [ "Customers" ], "summary": "Create a customer", "operationId": "createCustomer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomerRequest" } } }, "required": true }, "responses": { "200": { "description": "The request has succeeded and has resulted in one customer being updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Retrieve a customer", "operationId": "getCustomerById", "parameters": [ { "name": "id", "in": "path", "description": "The id of the customer to get the details for", "required": true, "schema": { "type": "string", "description": "The id of the customer to get the details for" } }, { "name": "idType", "in": "query", "description": "The connector type that this ID refers to", "required": true, "schema": { "type": "string", "description": "The connector type that this ID refers to", "enum": [ "XERO", "QUICKBOOKS", "EXTERNAL" ] } }, { "name": "includeCustomerFinancialDetails", "in": "query", "description": "This flag determines whether the response should include the financial status of the customer's invoices and payments.", "required": false, "schema": { "type": "boolean", "description": "This flag determines whether the response should include the financial status of the customer's invoices and payments." } } ], "responses": { "200": { "description": "The customer with the specified ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required - Invalid or missing authorization headers." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "put": { "tags": [ "Customers" ], "summary": "Update a customer by id", "operationId": "updateCustomerById", "parameters": [ { "name": "id", "in": "path", "description": "The id of the customer to update.", "required": true, "schema": { "type": "string", "description": "The id of the customer to update." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerByIdRequest" } } }, "required": true }, "responses": { "200": { "description": "The request has succeeded and has resulted in one customer being updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/{id}/directdebitmandates": { "get": { "tags": [ "Direct debit mandates" ], "summary": "Retrieve a direct debit mandates by customer", "operationId": "getDirectDebitMandatesByCustomerId", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The direct debit mandate attached to the customer with the given id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectDebitMandatesResponse" } } } }, "404": { "description": "The direct debit mandate doesn't exist" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "put": { "tags": [ "Direct debit mandates" ], "summary": "Create a direct debit mandate", "description": "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.", "operationId": "create", "parameters": [ { "name": "id", "in": "path", "description": "The id of the customer for whom to create the mandate", "required": true, "schema": { "type": "string", "description": "The id of the customer for whom to create the mandate" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDirectDebitMandateRequest" } } } }, "responses": { "200": { "description": "The direct debit mandate was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectDebitMandateResponse" } } } }, "400": { "description": "Invalid input was provided in the request" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/{customerId}/cards_on_file/{cardOnFileId}:remove": { "put": { "tags": [ "Card on file" ], "summary": "Remove a customer's card on file", "operationId": "removeCardOnFile", "parameters": [ { "name": "customerId", "in": "path", "description": "The id of the customer who owns the card on file", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The id of the customer who owns the card on file" } }, { "name": "cardOnFileId", "in": "path", "description": "The id of the card on file to remove", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The id of the card on file to remove" } } ], "responses": { "200": { "description": "The card on file was removed" }, "400": { "description": "The card on file does not exist or is not active" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/{customerId}/card_on_file:request": { "put": { "tags": [ "Card on file" ], "summary": "Request card details from a customer", "operationId": "requestCardDetails", "parameters": [ { "name": "customerId", "in": "path", "description": "The id of the customer to request card details from", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The id of the customer to request card details from" } } ], "responses": { "200": { "description": "Card details were requested from the customer" }, "400": { "description": "The customer already has an active or pending card-on-file request" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/{customerId}/autopilot_settings": { "get": { "tags": [ "Customer Autopilot Settings" ], "summary": "Retrieve autopilot guidance for a customer.", "operationId": "getCustomerAutopilotSettings", "parameters": [ { "name": "customerId", "in": "path", "description": "The unique identifier of the customer.", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the customer." } } ], "responses": { "200": { "description": "The guidance was retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAutopilotSettingsResponse" } } } }, "401": { "description": "Authentication is required." }, "500": { "description": "The server was unable to process the request." } } }, "put": { "tags": [ "Customer Autopilot Settings" ], "summary": "Create or update autopilot guidance for a customer.", "operationId": "upsertCustomerAutopilotSettings", "parameters": [ { "name": "customerId", "in": "path", "description": "The unique identifier of the customer.", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the customer." } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCustomerAutopilotSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "The request was successful.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAutopilotSettingsResponse" } } } }, "400": { "description": "There was an issue reading or understanding the request." }, "401": { "description": "Authentication is required." }, "422": { "description": "A validation error occurred with the request." }, "500": { "description": "The server was unable to process the request." } } }, "delete": { "tags": [ "Customer Autopilot Settings" ], "summary": "Delete autopilot guidance for a customer.", "operationId": "deleteCustomerAutopilotSettings", "parameters": [ { "name": "customerId", "in": "path", "description": "The unique identifier of the customer.", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The unique identifier of the customer." } } ], "responses": { "204": { "description": "The guidance was deleted." }, "401": { "description": "Authentication is required." }, "500": { "description": "The server was unable to process the request." } } } }, "/customers/workflow_settings": { "put": { "tags": [ "Customers" ], "summary": "Upsert customer workflow settings", "operationId": "upsertWorkflowSettings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCustomerWorkflowSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "The customer workflow settings were successfully updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWorkflowSettingsResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required - Invalid or missing authorization headers." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/payment_settings": { "put": { "tags": [ "Customers" ], "summary": "Upsert customer payment settings", "operationId": "upsertPaymentSettings", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertCustomerPaymentSettingsRequest" } } }, "required": true }, "responses": { "200": { "description": "The payment settings were successfully updated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPaymentSettingsResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required - Invalid or missing authorization headers." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/directdebitmandates/{id}:reinstate": { "put": { "tags": [ "Direct debit mandates" ], "summary": "Reinstate a cancelled direct debit mandate", "operationId": "reinstateDirectDebitMandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The direct debit mandate was reinstated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectDebitMandateResponse" } } } }, "400": { "description": "The direct debit mandate cannot be reinstated" }, "404": { "description": "The direct debit mandate doesn't exist" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/directdebitmandates/{id}:cancel": { "put": { "tags": [ "Direct debit mandates" ], "summary": "Cancel a direct debit mandate", "operationId": "cancelDirectDebitMandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelDirectDebitMandateRequest" } } }, "required": true }, "responses": { "200": { "description": "The direct debit mandate was cancelled." }, "400": { "description": "The direct debit mandate can not be cancelled" }, "404": { "description": "The direct debit mandate doesn't exist" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/apps/{clientId}/webhooks/{webhookId}": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve a webhook", "operationId": "getWebhookById", "parameters": [ { "name": "clientId", "in": "path", "description": "The application identifier", "required": true, "schema": { "type": "string", "description": "The application identifier" } }, { "name": "webhookId", "in": "path", "description": "The webhook identifier", "required": true, "schema": { "type": "string", "description": "The webhook identifier" } } ], "responses": { "200": { "description": "The details of an existing webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "404": { "description": "The application or the webhook does not exist" } }, "security": [ { "Platform Bearer Token": [] } ] }, "put": { "tags": [ "Webhooks" ], "summary": "Update a webhook", "operationId": "updateWebhook", "parameters": [ { "name": "clientId", "in": "path", "description": "The application identifier", "required": true, "schema": { "type": "string", "description": "The application identifier" } }, { "name": "webhookId", "in": "path", "description": "The webhook identifier", "required": true, "schema": { "type": "string", "description": "The webhook identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" } } }, "required": true }, "responses": { "200": { "description": "The updated webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Missing required fields" }, "404": { "description": "The application or the webhook does not exist" } }, "security": [ { "Platform Bearer Token": [] } ] }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete a webhook", "operationId": "deleteWebhook", "parameters": [ { "name": "clientId", "in": "path", "description": "The application identifier", "required": true, "schema": { "type": "string", "description": "The application identifier" } }, { "name": "webhookId", "in": "path", "description": "The webhook identifier", "required": true, "schema": { "type": "string", "description": "The webhook identifier" } } ], "responses": { "204": { "description": "The webhook has been deleted" }, "404": { "description": "The application or the webhook does not exist" } }, "security": [ { "Platform Bearer Token": [] } ] } }, "/apps/{clientId}/webhooks/digest": { "put": { "tags": [ "Webhooks" ], "summary": "Generate or replace the webhook signing secret key", "operationId": "generateWebhookSecretKey", "parameters": [ { "name": "clientId", "in": "path", "description": "The application identifier", "required": true, "schema": { "type": "string", "description": "The application identifier" } } ], "responses": { "200": { "description": "The generated secret key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDigestResponse" } } } }, "404": { "description": "The application does not exist" } }, "security": [ { "Platform Bearer Token": [] } ] } }, "/apps/{clientId}/webhooks/auth": { "put": { "tags": [ "Webhooks" ], "summary": "Create or update the authentication method and credentials for webhook target URLs", "operationId": "storeWebhookAuthentication", "parameters": [ { "name": "clientId", "in": "path", "description": "The application identifier", "required": true, "schema": { "type": "string", "description": "The application identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookAuthenticationRequest" } } }, "required": true }, "responses": { "204": { "description": "The authentication method and details have been stored" }, "400": { "description": "Missing required fields" }, "404": { "description": "The application does not exist" } }, "security": [ { "Platform Bearer Token": [] } ] } }, "/schedules/payment_requests": { "post": { "tags": [ "Recurring payment requests" ], "summary": "Create a recurring payment request", "operationId": "postRecurringPaymentRequest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecurringPaymentRequestRequest" } } }, "required": true }, "responses": { "201": { "description": "The request was successful and the recurring payment request was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringPaymentRequestResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/schedules/invoices": { "post": { "tags": [ "Recurring invoices" ], "summary": "Create a recurring invoice", "description": "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.", "operationId": "postRecurringInvoice", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRecurringInvoiceRequest" } } }, "required": true }, "responses": { "201": { "description": "The request was successful and the recurring invoice was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInvoiceResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/payments:import": { "post": { "tags": [ "Payments" ], "summary": "Import a payment", "description": "Import a payment against an invoice with a custom reference.", "operationId": "importPayment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportPaymentRequest" } } }, "required": true }, "responses": { "200": { "description": "Payment successfully imported." }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } } } }, "/payment_requests": { "get": { "tags": [ "Payment requests" ], "summary": "Retrieve a list of payment requests by filter", "operationId": "getPaymentRequests", "parameters": [ { "name": "customerId", "in": "query", "description": "The id of the customer associated to the payment request.", "required": false, "schema": { "type": "string", "description": "The id of the customer associated to the payment request." } }, { "name": "externalCustomerId", "in": "query", "description": "The id of the customer from the platform that is integrating with Adfin.", "required": false, "schema": { "type": "string", "description": "The id of the customer from the platform that is integrating with Adfin." } }, { "name": "statuses", "in": "query", "description": "The status of the payment request.\n* DRAFT: The payment request does not contain contact details for the payer or it is not yet distributed.\n* UNPAID: The payment request is not yet paid.\n* SCHEDULED: The payment request is scheduled to collect the payment via Direct Debit.\n* SUBMITTED: The remaining due amount on the payment request is covered by submitted (but not yet confirmed) Direct debit payments.\n* PAID: The payment request payment payment is captured.\n* CANCELLED: The payment request is cancelled.\n* SETTLED: THe payment request is paid out", "required": false, "schema": { "type": "array", "description": "The status of the payment request.\n* DRAFT: The payment request does not contain contact details for the payer or it is not yet distributed.\n* UNPAID: The payment request is not yet paid.\n* SCHEDULED: The payment request is scheduled to collect the payment via Direct Debit.\n* SUBMITTED: The remaining due amount on the payment request is covered by submitted (but not yet confirmed) Direct debit payments.\n* PAID: The payment request payment payment is captured.\n* CANCELLED: The payment request is cancelled.\n* SETTLED: THe payment request is paid out", "items": { "type": "string", "description": "The status of the payment request.\n* DRAFT: The payment request does not contain contact details for the payer or it is not yet distributed.\n* UNPAID: The payment request is not yet paid.\n* OVERDUE: THe payment request is not yet paid and is past the pay by date.\n* SCHEDULED: The payment request is scheduled to collect the payment via Direct Debit.\n* SUBMITTED: The remaining due amount on the payment request is covered by submitted (but not yet confirmed) Direct debit payments.\n* PAID: The payment request payment is captured.\n* VOID: The payment request is voided.\n* SETTLED: The payment request is paid out.\n", "enum": [ "DRAFT", "UNPAID", "OVERDUE", "SCHEDULED", "SUBMITTED", "PAID", "VOID", "SETTLED" ] } } }, { "name": "associationTypes", "in": "query", "description": "Payment request association type.\n* SINGLE - a one off payment request.\n* ONE_TO_ONE - a payment request associated with a single invoice.\n* PARTIAL - a payment request that is associated with an invoice that has multiple payment requests (many to one)\n* BATCH - a payment request that is associated with multiple invoices (one to many)\n\ndefaults to all types if not specified.", "required": false, "schema": { "type": "array", "description": "Payment request association type.\n* SINGLE - a one off payment request.\n* ONE_TO_ONE - a payment request associated with a single invoice.\n* PARTIAL - a payment request that is associated with an invoice that has multiple payment requests (many to one)\n* BATCH - a payment request that is associated with multiple invoices (one to many)\n\ndefaults to all types if not specified.", "items": { "type": "string", "description": "Payment request association type.\n* SINGLE - a one off payment request.\n* ONE_TO_ONE - a payment request associated with a single invoice.\n* PARTIAL - a payment request that is associated with an invoice that has multiple payment requests (many to one)\n* BATCH - a payment request that is associated with multiple invoices (one to many)", "enum": [ "SINGLE", "ONE_TO_ONE", "PARTIAL", "BATCH" ] } } }, { "name": "payByStartDate", "in": "query", "description": "The start date after which the payment requests pay by date should be, including the start date.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start date after which the payment requests pay by date should be, including the start date." } }, { "name": "payByEndDate", "in": "query", "description": "The end date before which the payment requests pay by date should be, including the end date.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The end date before which the payment requests pay by date should be, including the end date." } }, { "name": "createdStartDate", "in": "query", "description": "The start date after which the payment requests created date should be, including the start date.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start date after which the payment requests created date should be, including the start date." } }, { "name": "createdEndDate", "in": "query", "description": "The end date before which the payment requests created date should be, including the end date.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The end date before which the payment requests created date should be, including the end date." } }, { "name": "paidStartTime", "in": "query", "description": "The start time after which the payment request was paid, including the paid start time.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start time after which the payment request was paid, including the paid start time." } }, { "name": "paidEndTime", "in": "query", "description": "The end time after which the payment request was paid, including the paid end time.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The end time after which the payment request was paid, including the paid end time." } }, { "name": "lastUpdatedStartTime", "in": "query", "description": "The start time after which the payment requests last updated time should be, including the start time.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start time after which the payment requests last updated time should be, including the start time." } }, { "name": "lastUpdatedEndTime", "in": "query", "description": "The end time before which the payment requests last updated time should be, including the end time.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The end time before which the payment requests last updated time should be, including the end time." } }, { "name": "paymentLinkLastSeenTime", "in": "query", "description": "The start time before which the payment link was seen.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start time before which the payment link was seen." } }, { "name": "paymentInitiationDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "searchText", "in": "query", "description": "The text to search for in the payment requests.", "required": false, "schema": { "type": "string", "description": "The text to search for in the payment requests." } }, { "name": "includeCount", "in": "query", "description": "Whether the response should include details on total count and counts per statuses", "required": false, "schema": { "type": "boolean", "description": "Whether the response should include details on total count and counts per statuses" } }, { "name": "creditControlStatuses", "in": "query", "description": "The credit control status of the payment request.\n* AT_RISK: The payment request is at risk of not being paid.\n* EXPECTED: The payment request is expected to be paid.\n* CONFIRMED: The payment request is paid.\n", "required": false, "schema": { "type": "array", "description": "The credit control status of the payment request.\n* AT_RISK: The payment request is at risk of not being paid.\n* EXPECTED: The payment request is expected to be paid.\n* CONFIRMED: The payment request is paid.\n", "items": { "type": "string", "description": "The credit control status of the payment request.\n* AT_RISK: The payment request is at risk of not being paid.\n* EXPECTED: The payment request is expected to be paid.\n* CONFIRMED: The payment request is paid.\n", "enum": [ "AT_RISK", "EXPECTED", "CONFIRMED" ] } } }, { "name": "cashflowStatuses", "in": "query", "description": "The cashflow status of the payment request.\n* UNPAID – not yet paid.\n* PROCESSING – expected to be paid.\n* PAID_OUT – already paid out.\n", "required": false, "schema": { "type": "array", "description": "The cashflow status of the payment request.\n* UNPAID – not yet paid.\n* PROCESSING – expected to be paid.\n* PAID_OUT – already paid out.\n", "items": { "type": "string", "description": "The cashflow status of the payment request.\n* UNPAID – not yet paid.\n* PROCESSING – expected to be paid.\n* PAID_OUT – already paid out.\n", "enum": [ "UNPAID", "PROCESSING", "PAID_OUT" ] } } }, { "name": "cashflowPeriodStartDate", "in": "query", "description": "Start of the cashflow period (inclusive)", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Start of the cashflow period (inclusive)" } }, { "name": "cashflowPeriodEndDate", "in": "query", "description": "End of the cashflow period (inclusive)", "required": false, "schema": { "type": "string", "format": "date-time", "description": "End of the cashflow period (inclusive)" } }, { "name": "directDebitMandateStatuses", "in": "query", "description": "The direct debit mandate status.\n* NO_MANDATE: payment requests linked to customers without a mandate\n* AWAITING_SIGNATURE: payment requests linked to customers awaiting signature\n* SIGNED: payment requests linked to customers with a signed mandate, but not yet active\n* ACTIVE: payment requests linked to customers with an active mandate.\n", "required": false, "schema": { "type": "array", "description": "The direct debit mandate status.\n* NO_MANDATE: payment requests linked to customers without a mandate\n* AWAITING_SIGNATURE: payment requests linked to customers awaiting signature\n* SIGNED: payment requests linked to customers with a signed mandate, but not yet active\n* ACTIVE: payment requests linked to customers with an active mandate.\n", "items": { "type": "string", "description": "The direct debit mandate status.\n* NO_MANDATE: payment requests linked to customers without a mandate\n* AWAITING_SIGNATURE: payment requests linked to customers awaiting signature\n* SIGNED: payment requests linked to customers with a signed mandate, but not yet active\n* ACTIVE: payment requests linked to customers with an active mandate.\n", "enum": [ "NO_MANDATE", "AWAITING_SIGNATURE", "SIGNED", "ACTIVE", "MIGRATING" ] } } }, { "name": "workflowTypes", "in": "query", "description": "The workflow type.\n* AUTO_COLLECT: automatic collection workflow, such as direct debit\n* ON_DEMAND: on demain workflow, such as via open banking and card payments\n", "required": false, "schema": { "type": "array", "description": "The workflow type.\n* AUTO_COLLECT: automatic collection workflow, such as direct debit\n* ON_DEMAND: on demain workflow, such as via open banking and card payments\n", "items": { "type": "string", "description": "The workflow type.\n* AUTO_COLLECT: automatic collection workflow, such as direct debit\n* ON_DEMAND: on demain workflow, such as via open banking and card payments\n", "enum": [ "AUTO_COLLECT", "ON_DEMAND", "NONE" ] } } }, { "name": "minAmount", "in": "query", "description": "amount greater than or equal to", "required": false, "schema": { "type": "number", "description": "amount greater than or equal to", "minimum": 0 } }, { "name": "maxAmount", "in": "query", "description": "amount less than or equal to", "required": false, "schema": { "type": "number", "description": "amount less than or equal to", "minimum": 0 } }, { "name": "scheduleId", "in": "query", "description": "The id of the schedule associated to the payment request.", "required": false, "schema": { "type": "string", "description": "The id of the schedule associated to the payment request." } }, { "name": "fieldValueIds", "in": "query", "description": "List of field value IDs to filter payment requests by their associated field mappings.", "required": false, "schema": { "type": "array", "description": "List of field value IDs to filter payment requests by their associated field mappings.", "items": { "type": "string", "description": "List of field value IDs to filter payment requests by their associated field mappings." } } }, { "name": "reviewSessionId", "in": "query", "description": "The review session ID to filter payment requests by", "required": false, "schema": { "type": "string", "description": "The review session ID to filter payment requests by" } }, { "name": "page", "in": "query", "description": "Zero-based page index (0..N)", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "size", "in": "query", "description": "The size of the page to be returned", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "required": false, "schema": { "type": "array", "default": [ "creationTime,DESC" ], "items": { "type": "string" } } } ], "responses": { "200": { "description": "The list of payment requests for the specified filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestsResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required - Invalid or missing authorization headers." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "post": { "tags": [ "Payment requests" ], "summary": "Create a payment request", "operationId": "postPaymentRequest", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentRequestRequest" } } }, "required": true }, "responses": { "201": { "description": "The request was successful and the payment request was created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequestResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "404": { "description": "Customer does not exist." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } } } }, "/payment_requests/bulk_import": { "post": { "tags": [ "Payment requests" ], "summary": "Bulk import payment requests", "operationId": "bulkImport", "parameters": [ { "name": "collectionMethod", "in": "query", "description": "How the imported payment requests are expected to be collected. Currently, only NONE is supported.", "required": true, "schema": { "type": "string", "description": "How the imported payment requests are expected to be collected. Currently, only NONE is supported.", "enum": [ "AUTO_COLLECT", "ON_DEMAND", "NONE" ], "example": "NONE" }, "example": "NONE" }, { "name": "deleteMissingPaymentRequests", "in": "query", "description": "Whether missing payment requests created in previous imports should be deleted.", "required": true, "schema": { "type": "boolean", "description": "Whether missing payment requests created in previous imports should be deleted.", "example": false }, "example": false } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "inputFile": { "type": "string", "format": "binary", "description": "Input file to be processed during the bulk import." } }, "required": [ "inputFile" ] }, "examples": { "Bulk Import Request": { "summary": "Example bulk import request", "description": "Upload a input file with payment requests along with collection method and delete flag", "value": "collectionMethod: NONE\ndeleteMissingPaymentRequests: false\ninputFile: (binary file - payment_requests.csv)\n" } } } }, "required": true }, "responses": { "202": { "description": "The bulk import request has been accepted for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPaymentRequestImportResponse" }, "example": { "jobId": "550e8400-e29b-41d4-a716-446655440000", "type": "BULK_PAYMENT_REQUEST_IMPORT", "status": "PENDING", "creationTime": "2024-01-15T10:30:00Z", "countsByItemStatus": [] } } } }, "400": { "description": "There was an issue reading or understanding the request. Please ensure that it adheres to the required format and includes all necessary parameters." }, "401": { "description": "Authentication is required." }, "422": { "description": "A validation error occurred with the request." }, "500": { "description": "The server was unable to process the request." } } } }, "/oauth2/token": { "post": { "tags": [ "oAuth2" ], "summary": "Issue an OAuth 2.0 access token", "operationId": "issueOAuth2Token", "parameters": [ { "name": "Authorization", "in": "header", "description": "The authorization header", "required": false, "schema": { "type": "string", "description": "The authorization header" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "code": { "type": "string" }, "refresh_token": { "type": "string" }, "redirect_uri": { "type": "string" }, "scope": { "type": "array", "items": { "type": "string" } } }, "required": [ "grant_type" ] } } } }, "responses": { "200": { "description": "Access token was successfully issued.", "content": { "application/json": { "examples": { "AccessTokenExample": { "summary": "Example OAuth2 token response", "description": "AccessTokenExample", "value": { "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjV0ZGx6cUxiZ3ZVTXJ6SC1WZVZrZyJ9.eyJpc3MiOiJodHRwczovL2F1dGhlbnRpY2F0aW9uLnN0YWdpbmcuYWRmaW4uY29tLyIsInN1YiI6IkpkandtWEZPMXdqOGN2OXFtbEhFM2xoaVpVZWFqTlpYQGNsaWVudHMiLCJhdWQiOiJodHRwczovL3N0YWdpbmctYXV0aC1hZGZpbi5ldS5hdXRoMC5jb20vYXBpL3YyLyIsImlhdCI6MTc2MTI5NjA2NiwiZXhwIjoxNzYxMzAzMjY2LCJzY29wZSI6ImNyZWF0ZTpjbGllbnRfY3JlZGVudGlhbHMgcmVhZDpjbGllbnRfY3JlZGVudGlhbHMgdXBkYXRlOmNsaWVudF9jcmVkZW50aWFscyBkZWxldGU6Y2xpZW50X2NyZWRlbnRpYWxzIiwiZ3R5IjoiY2xpZW50LWNyZWRlbnRpYWxzIiwiYXpwIjoiSmRqd21YRk8xd2o4Y3Y5cW1sSEUzbGhpWlVlYWpOWlgifQ.V2K-38NuyrDkTlu5-4b8g3oIrPWjT8ESIJ7DqB9iawwjYsLGGCU1sPxIK974l6GQVRdF904IeDdLBJc4bLR-G0odtcTM9_SQpHFeZOTUi9WhIh-T_v81VvAN6j_OTW2qA30LfSGPQHJD6Z0fAAHpWqLVkFksuifCxi7LyJ6ufCI9FtoYz6XsG_AMaSbk71dEoc56ChjskXCofi5fmgDH1jZukj_oyzk00IURTpzmB3DjhZI_3TrDTk5tXjxmORiLM8yakJji6s0vqNxSGHUSWxCuMObbCrqeq7jYaUMzPDMhfwllBsGw5tQf1iAA1LUWgNRDjNgTqeY3Mk5oZVTEST", "expires_in": 7200, "token_type": "Bearer" } } } } } } } } }, "/oauth2/revoke": { "post": { "tags": [ "oAuth2" ], "summary": "Revoke an OAuth2 Refresh token", "operationId": "revokeOAuth2RefreshToken", "parameters": [ { "name": "Authorization", "in": "header", "description": "The authorization header", "required": false, "schema": { "type": "string", "description": "The authorization header" } } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "token": { "type": "string" } }, "required": [ "token" ] } } } }, "responses": { "200": { "description": "The Refresh token was successfully revoked." } } } }, "/oauth2/authorize": { "post": { "tags": [ "oAuth2" ], "summary": "Authorize an app to access Adfin data on behalf of an Adfin user", "operationId": "authorize", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeRequest" } } }, "required": true }, "responses": { "200": { "description": "The app was successfully authorized.", "content": { "application/json": { "examples": { "AuthorizeExample": { "summary": "Example OAuth2 authorization response", "description": "AuthorizeExample", "value": { "refresh_token": "v1.M03zAQtQuGE7AJbgcmSGIAZ9-j7IPRDJEgF_QzXHLn4gJR7yLb-RX6Ir8Q6n-pWzm9jXIvtmR8L46TnZxfTvSCc", "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjV0ZGx6cUxiZ3ZVTXJ6SC1WZVZrZyJ9.eyJwbGF0Zm9ybUNsaWVudElkIjoiUUlpdHVaNG44SFo5cktVeXBObTNRSFR1NmtNVFY2UFYiLCJpc3MiOiJodHRwczovL2F1dGhlbnRpY2F0aW9uLnN0YWdpbmcuYWRmaW4uY29tLyIsInN1YiI6ImF1dGgwfDY4MjYxZWIzOTA0NDg5ZjNmZGQxMDYyMCIsImF1ZCI6WyJodHRwczovL3N0YWdpbmctYXV0aDAtYXBpLmFkZmluLmNvbSJdLCJpYXQiOjE3NjEzMDkyNDUsImV4cCI6MTc2MTMxMjg0NSwic2NvcGUiOiJvcGVuaWQgcHJvZmlsZSBlbWFpbCBwaG9uZSBvZmZsaW5lX2FjY2VzcyIsImd0eSI6WyJyZWZyZXNoX3Rva2VuIiwicGFzc3dvcmQiXSwiYXpwIjoiTTlrNDdOZmlSeGIwOEVKakNKQWJGbm5mNnZLZE1GUDUiLCJwZXJtaXNzaW9ucyI6W119.bGCs_5Nh9q1aH_StRTJXMxlYzsAO-ROVi3Ttxh1NtlX6ginnIIzEvdLuY1iJWZ_4sFRuxIzX82mdbbFpuEGOIBoMDfqUOwGMnKY3A0z2366GkWuPT0L3Vd2iUH8Th_if9SnOKMIi_WWopaSuE_pyPtu_LuX1d5zUI70pXiYifRZL51qhDOCEx1rftHfH30GbSeZekVoe4m3Ap5I5f6MD7c03MxSa_oxw-V2keA6W_v1JJGMvXAKI5eqa3vaXW94RkbMbSh0ey6TMNXDyW-u2lCVbjrhGLVs16qMNEtSUaCcmToJ22Wi35Z4xlsv0FOLR9WbMWRmIrjr5BvQxQ2MNtA", "expires_in": 3600, "token_type": "Bearer" } } } } } } } } }, "/invoices": { "get": { "tags": [ "Invoices" ], "summary": "Retrieve a list of invoices by filter", "operationId": "getInvoices", "parameters": [ { "name": "invoiceNo", "in": "query", "description": "The invoice number.", "required": false, "schema": { "type": "string", "description": "The invoice number." } }, { "name": "customerId", "in": "query", "description": "The id of the customer associated to the invoice.", "required": false, "schema": { "type": "string", "description": "The id of the customer associated to the invoice." } }, { "name": "externalCustomerId", "in": "query", "description": "The id of the customer from the platform that is integrating with Adfin.", "required": false, "schema": { "type": "string", "description": "The id of the customer from the platform that is integrating with Adfin." } }, { "name": "statuses", "in": "query", "description": "The status of the invoice.\n* DRAFT: The invoice does not contain contact details for the payer or it is not yet distributed.\n* UNPAID: The invoice is not yet paid.\n* OVERDUE: The invoice is not yet paid and it is passed the due date.\n* SCHEDULED: The invoice is scheduled to collect the payment via Direct Debit.\n* SUBMITTED: The remaining due amount on the invoice is covered by submitted (but not yet confirmed) Direct Debit payments.\n* PAID: The invoice payment has been captured.\n* SETTLED: The invoice is paid out.\n* VOID: The invoice was voided.", "required": false, "schema": { "type": "array", "description": "The status of the invoice.\n* DRAFT: The invoice does not contain contact details for the payer or it is not yet distributed.\n* UNPAID: The invoice is not yet paid.\n* OVERDUE: The invoice is not yet paid and it is passed the due date.\n* SCHEDULED: The invoice is scheduled to collect the payment via Direct Debit.\n* SUBMITTED: The remaining due amount on the invoice is covered by submitted (but not yet confirmed) Direct Debit payments.\n* PAID: The invoice payment has been captured.\n* SETTLED: The invoice is paid out.\n* VOID: The invoice was voided.", "items": { "type": "string", "description": "The status of the invoice.\n* DRAFT: The invoice does not contain contact details for the payer or it is not yet distributed.\n* UNPAID: The invoice is not yet paid.\n* OVERDUE: The invoice is not yet paid and it is passed the due date.\n* SCHEDULED: The invoice is scheduled to collect the payment via Direct Debit.\n* SUBMITTED: The remaining due amount on the invoice is covered by submitted (but not yet confirmed) Direct Debit payments.\n* PAID: The invoice payment has been captured.\n* SETTLED: The invoice is paid out.\n* VOID: The invoice was voided." } } }, { "name": "statusReasons", "in": "query", "description": "The status reason codes of the invoice.", "required": false, "schema": { "type": "array", "description": "The status reason codes of the invoice.", "items": { "type": "string", "description": "The status reason codes of the invoice." } } }, { "name": "dueStartDate", "in": "query", "description": "The start date after which the invoices due date should be, including the start date.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start date after which the invoices due date should be, including the start date." } }, { "name": "dueEndDate", "in": "query", "description": "The end date before which the invoices due date should be, including the end date.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The end date before which the invoices due date should be, including the end date." } }, { "name": "issueStartDate", "in": "query", "description": "The start date after which the invoices issue date should be, including the start date.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start date after which the invoices issue date should be, including the start date." } }, { "name": "issueEndDate", "in": "query", "description": "The end date before which the invoices issue date should be, including the end date.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The end date before which the invoices issue date should be, including the end date." } }, { "name": "paidStartTime", "in": "query", "description": "The start time after which the invoice was paid, including the paid start time.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start time after which the invoice was paid, including the paid start time." } }, { "name": "paidEndTime", "in": "query", "description": "The end time after which the invoice was paid, including the paid end time.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The end time after which the invoice was paid, including the paid end time." } }, { "name": "lastUpdatedStartTime", "in": "query", "description": "The start time after which the invoices last updated time should be, including the start time.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start time after which the invoices last updated time should be, including the start time." } }, { "name": "lastUpdatedEndTime", "in": "query", "description": "The end time before which the invoices last updated time should be, including the end time.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The end time before which the invoices last updated time should be, including the end time." } }, { "name": "paymentLinkLastSeenTime", "in": "query", "description": "The start time before which the payment link was seen.", "required": false, "schema": { "type": "string", "format": "date-time", "description": "The start time before which the payment link was seen." } }, { "name": "searchText", "in": "query", "description": "The text to search for in the invoices.", "required": false, "schema": { "type": "string", "description": "The text to search for in the invoices." } }, { "name": "includeCount", "in": "query", "description": "Whether the response should include details on total count and counts per statuses", "required": false, "schema": { "type": "boolean", "description": "Whether the response should include details on total count and counts per statuses" } }, { "name": "creditControlStatuses", "in": "query", "description": "The credit control status of the invoice.\n* AT_RISK: The invoice is at risk of not being paid.\n* EXPECTED: The invoice is expected to be paid.\n* CONFIRMED: The invoice is paid.\n", "required": false, "schema": { "type": "array", "description": "The credit control status of the invoice.\n* AT_RISK: The invoice is at risk of not being paid.\n* EXPECTED: The invoice is expected to be paid.\n* CONFIRMED: The invoice is paid.\n", "items": { "type": "string", "description": "The credit control status of the invoice.\n* AT_RISK: The invoice is at risk of not being paid.\n* EXPECTED: The invoice is expected to be paid.\n* CONFIRMED: The invoice is paid.\n", "enum": [ "AT_RISK", "EXPECTED", "CONFIRMED" ] } } }, { "name": "cashflowStatuses", "in": "query", "description": "The cashflow status of the payment request.\n* UNPAID – not yet paid.\n* PROCESSING – expected to be paid.\n* PAID_OUT – already paid out.\n", "required": false, "schema": { "type": "array", "description": "The cashflow status of the payment request.\n* UNPAID – not yet paid.\n* PROCESSING – expected to be paid.\n* PAID_OUT – already paid out.\n", "items": { "type": "string", "description": "The cashflow status of the payment request.\n* UNPAID – not yet paid.\n* PROCESSING – expected to be paid.\n* PAID_OUT – already paid out.\n", "enum": [ "UNPAID", "PROCESSING", "PAID_OUT" ] } } }, { "name": "cashflowPeriodStartDate", "in": "query", "description": "Start of the cashflow period (inclusive)", "required": false, "schema": { "type": "string", "format": "date-time", "description": "Start of the cashflow period (inclusive)" } }, { "name": "cashflowPeriodEndDate", "in": "query", "description": "End of the cashflow period (inclusive)", "required": false, "schema": { "type": "string", "format": "date-time", "description": "End of the cashflow period (inclusive)" } }, { "name": "directDebitMandateStatuses", "in": "query", "description": "The direct debit mandate status.\n* NO_MANDATE: invoices linked to customers without a mandate\n* AWAITING_SIGNATURE: invoices linked to customers awaiting signature\n* SIGNED: invoices linked to customers with a signed mandate, but not yet active\n* ACTIVE: invoices linked to customers with an active mandate.\n* MIGRATING: invoices linked to customers with an active mandate which is being migrated to a different payment service provider.\n", "required": false, "schema": { "type": "array", "description": "The direct debit mandate status.\n* NO_MANDATE: invoices linked to customers without a mandate\n* AWAITING_SIGNATURE: invoices linked to customers awaiting signature\n* SIGNED: invoices linked to customers with a signed mandate, but not yet active\n* ACTIVE: invoices linked to customers with an active mandate.\n* MIGRATING: invoices linked to customers with an active mandate which is being migrated to a different payment service provider.\n", "items": { "type": "string", "description": "The direct debit mandate status.\n* NO_MANDATE: invoices linked to customers without a mandate\n* AWAITING_SIGNATURE: invoices linked to customers awaiting signature\n* SIGNED: invoices linked to customers with a signed mandate, but not yet active\n* ACTIVE: invoices linked to customers with an active mandate.\n* MIGRATING: invoices linked to customers with an active mandate which is being migrated to a different payment service provider.\n", "enum": [ "NO_MANDATE", "AWAITING_SIGNATURE", "SIGNED", "ACTIVE", "MIGRATING" ] } } }, { "name": "workflowTypes", "in": "query", "description": "The workflow type.\n* AUTO_COLLECT: automatic collection workflow, such as direct debit\n* ON_DEMAND: on demain workflow, such as via open banking and card payments\n", "required": false, "schema": { "type": "array", "description": "The workflow type.\n* AUTO_COLLECT: automatic collection workflow, such as direct debit\n* ON_DEMAND: on demain workflow, such as via open banking and card payments\n", "items": { "type": "string", "description": "The workflow type.\n* AUTO_COLLECT: automatic collection workflow, such as direct debit\n* ON_DEMAND: on demain workflow, such as via open banking and card payments\n", "enum": [ "AUTO_COLLECT", "ON_DEMAND", "NONE" ] } } }, { "name": "minAmount", "in": "query", "description": "amount greater than or equal to", "required": false, "schema": { "type": "number", "description": "amount greater than or equal to", "minimum": 0 } }, { "name": "maxAmount", "in": "query", "description": "amount less than or equal to", "required": false, "schema": { "type": "number", "description": "amount less than or equal to", "minimum": 0 } }, { "name": "reviewSessionId", "in": "query", "description": "The review session ID to filter invoices by", "required": false, "schema": { "type": "string", "description": "The review session ID to filter invoices by" } }, { "name": "invoiceIds", "in": "query", "description": "List of invoice IDs to filter by", "required": false, "schema": { "type": "array", "description": "List of invoice IDs to filter by", "items": { "type": "string", "description": "List of invoice IDs to filter by" } } }, { "name": "scheduleId", "in": "query", "description": "The id of the schedule associated to the invoice.", "required": false, "schema": { "type": "string", "description": "The id of the schedule associated to the invoice." } }, { "name": "fieldValueIds", "in": "query", "description": "List of field value IDs to filter invoices by their associated field mappings.", "required": false, "schema": { "type": "array", "description": "List of field value IDs to filter invoices by their associated field mappings.", "items": { "type": "string", "description": "List of field value IDs to filter invoices by their associated field mappings." } } }, { "name": "page", "in": "query", "description": "Zero-based page index (0..N)", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "size", "in": "query", "description": "The size of the page to be returned", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "required": false, "schema": { "type": "array", "default": [ "creationTime,DESC" ], "items": { "type": "string" } } } ], "responses": { "200": { "description": "The list of invoices for the specified filter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required - Invalid or missing authorization headers." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "post": { "tags": [ "Invoices" ], "summary": "Create an invoice", "operationId": "createInvoice", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } }, "required": true }, "responses": { "200": { "description": "The request was successful and the invoice was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/invoices/{invoiceId}/instalments/preview": { "post": { "tags": [ "Invoices" ], "summary": "Preview instalment plan for an invoice", "operationId": "previewInstalmentForInvoice", "parameters": [ { "name": "invoiceId", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreviewInvoiceInstalmentPlanRequest" } } }, "required": true }, "responses": { "200": { "description": "The instalment preview was generated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceResponse" } } } }, "400": { "description": "A problem reading or understanding the request." }, "401": { "description": "Authentication required." }, "404": { "description": "Invoice not found." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/apps/{clientId}/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "Retrieve webhooks for a clientId", "operationId": "getWebhooks", "parameters": [ { "name": "clientId", "in": "path", "description": "The application identifier", "required": true, "schema": { "type": "string", "description": "The application identifier" } } ], "responses": { "200": { "description": "A list of existing webhooks", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhooksResponse" } } } }, "404": { "description": "The application does not exist" } }, "security": [ { "Platform Bearer Token": [] } ] }, "post": { "tags": [ "Webhooks" ], "summary": "Create a webhook", "operationId": "createWebhook", "parameters": [ { "name": "clientId", "in": "path", "description": "The application identifier", "required": true, "schema": { "type": "string", "description": "The application identifier" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } }, "required": true }, "responses": { "201": { "description": "The created webhook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookResponse" } } } }, "400": { "description": "Missing required fields" }, "404": { "description": "The application or the webhook does not exist" } }, "security": [ { "Platform Bearer Token": [] } ] } }, "/biller": { "get": { "tags": [ "Biller" ], "summary": "Retrieves a biller", "description": "Fetches the details of the authenticated user's associated biller. Returns a 404 if no biller is found.", "operationId": "getBiller", "responses": { "200": { "description": "The biller details retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillerResponse" } } } }, "404": { "description": "The biller is not found" }, "500": { "description": "Something went wrong processing your request" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] }, "patch": { "tags": [ "Biller" ], "summary": "Patch a Biller", "description": "Applies JSON Patch operations to update specific biller fields.", "operationId": "patchBiller", "requestBody": { "content": { "application/json-patch+json": { "schema": { "$ref": "#/components/schemas/PatchBillerRequest" } } }, "required": true }, "responses": { "204": { "description": "The biller was successfully patched." }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "404": { "description": "Biller not found." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/payment_requests/bulk_import/{jobId}": { "get": { "tags": [ "Payment requests" ], "summary": "Retrieve bulk payment request import job details", "operationId": "getBulkPaymentRequestImportJobDetails", "parameters": [ { "name": "jobId", "in": "path", "description": "The ID of the bulk payment request import job", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the bulk payment request import job" } } ], "responses": { "200": { "description": "The bulk payment request import job details were successfully retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPaymentRequestImportResponse" }, "example": { "jobId": "550e8400-e29b-41d4-a716-446655440000", "type": "BULK_PAYMENT_REQUEST_IMPORT", "status": "COMPLETED", "creationTime": "2024-01-15T10:30:00Z", "countsByItemStatus": [ { "status": "COMPLETED", "count": 150 }, { "status": "PROCESSING", "count": 5 } ] } } } }, "400": { "description": "There was an issue reading or understanding the request. Please ensure that it adheres to the required format and includes all necessary parameters." }, "401": { "description": "Authentication is required." }, "404": { "description": "Bulk payment request import job not found." }, "422": { "description": "A validation error occurred with the request." }, "500": { "description": "The server was unable to process the request." } } } }, "/payment_requests/bulk_import/{jobId}/items": { "get": { "tags": [ "Payment requests" ], "summary": "Retrieve bulk payment request import job items", "operationId": "getBulkPaymentRequestImportJobItems", "parameters": [ { "name": "jobId", "in": "path", "description": "The ID of the bulk payment request import job", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The ID of the bulk payment request import job" } }, { "name": "statuses", "in": "query", "description": "The status of the bulk payment request import job item\n* PENDING: The item is still to be processed.\n* PROCESSING: The item is currently processing.\n* COMPLETED: The item has been processed.\n* FAILED: The item has failed to be processed.\n", "required": false, "schema": { "type": "array", "description": "The status of the bulk payment request import job item\n* PENDING: The item is still to be processed.\n* PROCESSING: The item is currently processing.\n* COMPLETED: The item has been processed.\n* FAILED: The item has failed to be processed.\n", "items": { "type": "string", "description": "The status of the bulk payment request import job item\n* PENDING: The item is still to be processed.\n* PROCESSING: The item is currently processing.\n* COMPLETED: The item has been processed.\n* FAILED: The item has failed to be processed.\n", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] } } }, { "name": "page", "in": "query", "description": "Zero-based page index (0..N)", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0 } }, { "name": "size", "in": "query", "description": "The size of the page to be returned", "required": false, "schema": { "type": "integer", "default": 20, "minimum": 1 } }, { "name": "sort", "in": "query", "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.", "required": false, "schema": { "type": "array", "default": [ "creationTime,ASC" ], "items": { "type": "string" } } } ], "responses": { "200": { "description": "Paginated response for the list of bulk payment request import job items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPaymentRequestImportItemsResponse" }, "example": { "items": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "jobId": "550e8400-e29b-41d4-a716-446655440000", "paymentRequestNo": "PR-2024-001", "bulkPrImportOperation": "UPSERT", "status": "FAILED", "statusReason": "Operation has failed", "creationTime": "2024-01-15T10:30:00Z" }, { "id": "223e4567-e89b-12d3-a456-426614174001", "jobId": "550e8400-e29b-41d4-a716-446655440000", "paymentRequestNo": "PR-2024-002", "bulkPrImportOperation": "DELETE", "status": "PENDING", "creationTime": "2024-01-15T10:30:01Z" } ], "pagination": { "page": 0, "size": 20, "totalElements": 155, "totalPages": 8 } } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required - Invalid or missing authorization headers." }, "404": { "description": "Bulk payment request import job not found." }, "422": { "description": "A request validation error." }, "500": { "description": "The server could not process the request." } } } }, "/oauth2/authorization": { "get": { "tags": [ "oAuth2" ], "summary": "Get the authorization details for an app", "operationId": "getAppAuthorizationDetails", "parameters": [ { "name": "clientId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "state", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The app was successfully retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppResponse" } } } }, "404": { "description": "No app was found with the provided client id" } } } }, "/invoices/{id}/file": { "get": { "tags": [ "Invoices" ], "summary": "Get the file for a specific invoice", "operationId": "getFile", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The invoice file is successfully returned", "content": { "application/octet-stream": { "schema": { "$ref": "#/components/schemas/StreamingResponseBody" } } } }, "404": { "description": "The invoice cannot be found" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/{id}/workflow_settings": { "get": { "tags": [ "Customers" ], "summary": "Retrieve customer workflow settings", "operationId": "getWorkflowSettings", "parameters": [ { "name": "id", "in": "path", "description": "The id of the customer to get workflow settings for", "required": true, "schema": { "type": "string", "description": "The id of the customer to get workflow settings for" } } ], "responses": { "200": { "description": "The workflow settings were retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerWorkflowSettingsResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required - Invalid or missing authorization headers." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/{id}/payment_settings": { "get": { "tags": [ "Customers" ], "summary": "Retrieve customer payment settings", "operationId": "getPaymentSettings", "parameters": [ { "name": "id", "in": "path", "description": "The id of the customer to get payment settings for", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The id of the customer to get payment settings for" } } ], "responses": { "200": { "description": "The payment settings were retrieved.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPaymentSettingsResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required - Invalid or missing authorization headers." }, "500": { "description": "The server could not process the request." } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/{customerId}/cards_on_file": { "get": { "tags": [ "Card on file" ], "summary": "List a customer's cards on file", "operationId": "getCardsOnFile", "parameters": [ { "name": "customerId", "in": "path", "description": "The id of the customer whose cards on file to list", "required": true, "schema": { "type": "string", "format": "uuid", "description": "The id of the customer whose cards on file to list" } }, { "name": "statuses", "in": "query", "description": "Only return cards with one of these statuses; when omitted, cards of every status are returned", "required": false, "schema": { "type": "array", "description": "Only return cards with one of these statuses; when omitted, cards of every status are returned", "items": { "type": "string", "description": "Only return cards with one of these statuses; when omitted, cards of every status are returned", "enum": [ "REQUESTED", "ACTIVE", "CANCELLED", "EXPIRED" ] }, "uniqueItems": true } } ], "responses": { "200": { "description": "The customer's cards on file, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardsOnFileResponse" } } } } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/directdebitmandates": { "get": { "tags": [ "Direct debit mandates" ], "summary": "Search direct debit mandates by filters", "operationId": "searchDirectDebitMandates", "parameters": [ { "name": "customerId", "in": "query", "description": "The id of the customer associated to the direct debit mandate", "required": false, "schema": { "type": "string", "format": "uuid", "description": "The id of the customer associated to the direct debit mandate" } }, { "name": "statuses", "in": "query", "description": "The status of the direct debit mandate", "required": false, "schema": { "type": "array", "description": "The status of the direct debit mandate", "items": { "type": "string", "description": "The status of the Direct Debit Mandate, if any present.\n* CREATED: The Direct Debit Mandate was created with success.\n* PENDING: The Direct Debit Mandate was signed and accepted by the customer and it is in the Payment Provider's accepted timeframe.\n* ACTIVE: The Direct Debit Mandate was confirmed by the Payment Provider.\n* PENDING_CANCELLATION: The biller requested cancellation while a payment is in flight; the cancellation will fire once the payment resolves.\n* CANCELLED: The Direct Debit Mandate was cancelled directly by the customer.\n* MIGRATING: The Direct Debit Mandate is in process of migrating from one payment provider to another.", "enum": [ "CREATED", "PENDING", "ACTIVE", "PENDING_CANCELLATION", "CANCELLED", "MIGRATING" ] } } }, { "name": "statusReasonCodes", "in": "query", "description": "The reason code of the direct debit mandate status", "required": false, "schema": { "type": "array", "description": "The reason code of the direct debit mandate status", "items": { "type": "string", "description": "The reason why the direct debit mandate is in a certain status.\n* PENDING_DD_CAPABILITY - The direct debit mandate was signed, but not yet submitted to the payment provider as the biller onboarding is still in progress.\n* PENDING_ACTIVATION - The direct debit mandate was signed, but not yet activated by the payment provider.\n* MIGRATED - The direct debit mandate was migrated to a new payment provider.\n* BANK_ACCOUNT_CHANGED - The direct debit mandate was created due to a bank account change (bank switching).\n* INCORRECT_BANK_DETAILS - The direct debit mandate has incorrect bank account details.\n* INSTRUCTION_CANCELLED_BY_PAYER - Customer cancelled mandate\n* PAYER_DECEASED - Account holder deceased\n* ADVANCE_NOTICE_DISPUTED - Customer disputes that advance notice was sent\n* AMOUNT_DISPUTED - Customer disputes that the amount is incorrect\n* DISPUTE_TOO_EARLY - Customer disputes that the advance notice was sent too early\n* DISPUTE_TOO_LATE - Customer disputes that the advance notice was sent too late\n* INVALID_SORT_CODE - Invalid sort code\n* INVALID_ACC_NUMBER - Invalid account number\n* ACCOUNT_CLOSED - Bank account closed\n* REINSTATED - The cancelled direct debit mandate was reinstated.\n* MIGRATION_TIMEOUT - The mandate migration timed out without a new active mandate being established.\n* DISCARDED_BY_BILLER - The mandate request was discarded by the biller before the customer signed it.\n* ACCEPTED_ON_CREATION - The mandate was created and accepted in the same operation.\n* OTHER - Unknown reason", "enum": [ "PENDING_DD_CAPABILITY", "PENDING_ACTIVATION", "MIGRATED", "BANK_ACCOUNT_CHANGED", "INCORRECT_BANK_DETAILS", "INSTRUCTION_CANCELLED_BY_PAYER", "PAYER_DECEASED", "ACCOUNT_TRANSFERRED", "ADVANCE_NOTICE_DISPUTED", "AMOUNT_DISPUTED", "MANDATE_NOT_FOUND", "DISPUTE_TOO_EARLY", "DISPUTE_TOO_LATE", "INVALID_SORT_CODE", "INVALID_ACC_NUMBER", "ACCOUNT_CLOSED", "CANCELLED_ON_DEMAND", "REINSTATED", "MIGRATION_TIMEOUT", "DISCARDED_BY_BILLER", "ACCEPTED_ON_CREATION", "OTHER" ] } } }, { "name": "canBeReinstated", "in": "query", "description": "Whether the mandate can be reinstated", "required": false, "schema": { "type": "boolean", "description": "Whether the mandate can be reinstated" } } ], "responses": { "200": { "description": "The mandates matching the provided filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectDebitMandatesResponse" } } } } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/customers/directdebitmandates/{id}": { "get": { "tags": [ "Direct debit mandates" ], "summary": "Retrieve a direct debit mandate", "operationId": "getDirectDebitMandate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The direct debit mandate corresponding to the provided id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectDebitMandateResponse" } } } }, "404": { "description": "The direct debit mandate doesn't exist" } }, "security": [ { "Biller Access Token (Staging)": [] }, { "Biller Access Token (Production)": [] } ] } }, "/catalogs/tax_rates": { "get": { "tags": [ "Tax rates" ], "summary": "Retrieve tax rate options", "operationId": "getTaxRateCataloguesForBiller", "parameters": [ { "name": "connectorType", "in": "query", "required": false, "schema": { "type": "string", "description": "The connector type", "enum": [ "XERO", "QUICKBOOKS", "PLATFORM" ] } } ], "responses": { "200": { "description": "The request has succeeded and has resulted in a list of tax rate options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTaxRateCatalogueResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "500": { "description": "The server could not process the request." } } } }, "/catalogs/items": { "get": { "tags": [ "Items" ], "summary": "Get line item catalogue items for a given filter", "operationId": "postLineItemCatalogueElement", "parameters": [ { "name": "description", "in": "query", "description": "Item description", "required": false, "schema": { "type": "string", "description": "Item description" } } ], "responses": { "200": { "description": "The request has succeeded and has resulted in one line item catalogue element created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLineItemCatalogueResponse" } } } }, "400": { "description": "A problem reading or understanding the request. Ensure that the request complies with the required format and includes all necessary parameters." }, "401": { "description": "Authentication required." }, "500": { "description": "The server could not process the request." } } } } }, "components": { "schemas": { "CreateWorkflowRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "The internal identifier of the schedule. Required only for updates." }, "templateId": { "type": "string", "description": "The internal id of the template to be used for defining the schedule. Can be used in place of defining individual events for a schedule; in this case, the events will be automatically copied from the template. This streamlines the process and ensures consistency across schedules." }, "customerDetails": { "$ref": "#/components/schemas/CustomerDetails", "description": "Information about the customer for whom this schedule is being created." }, "invoiceDetails": { "$ref": "#/components/schemas/InvoiceDetails", "description": "Information about the payment request for which this schedule is being created." }, "name": { "type": "string", "description": "The name of the schedule to be created for the customer. It must contain only alphanumeric characters, and be limited to a maximum of 50 characters.", "maxLength": 50, "minLength": 0 }, "type": { "type": "string", "description": "The type of the schedule to be created for the customer", "enum": [ "ONE_TIME_PAYMENT", "DD_MANDATE_AUTHORISATION", "DD_PAYMENT", "CUSTOMER_STATEMENT" ] }, "customMessage": { "type": "string", "description": "The (optional) custom message to be added to notification" }, "events": { "type": "array", "description": "A list of events that will occur as part of the schedule, applicable exclusively to a single customer", "items": { "$ref": "#/components/schemas/EventRequest" } }, "settings": { "$ref": "#/components/schemas/WorkflowSettingsRequest", "description": "Optional workflow specific settings." } }, "required": [ "type" ] }, "CustomerDetails": { "type": "object", "description": "Contains the unique identifier for the customer.\n", "example": { "id": "80349480-490b-4234-92e7-fad697e3d446" }, "properties": { "id": { "type": "string", "description": "The Adfin ID of the customer.", "example": "80349480-490b-4234-92e7-fad697e3d446" } }, "required": [ "id" ] }, "CustomerStatementSettings": { "type": "object", "description": "Customer statement workflow settings", "properties": { "isEnabled": { "type": "boolean", "description": "Indicates whether customer statement workflow is enabled" } }, "required": [ "isEnabled" ] }, "Duration": { "type": "object", "properties": { "startDate": { "type": "string", "format": "date-time", "description": "The date when the event execution will begin" }, "endDate": { "type": "string", "format": "date-time", "description": "The date on which the execution of the event will conclude" }, "maxNoOfExecutions": { "type": "integer", "format": "int32", "description": "The maximum allowable executions of an event" } } }, "EventRequest": { "type": "object", "properties": { "frequency": { "$ref": "#/components/schemas/Frequency", "description": "The frequency of the event" }, "duration": { "$ref": "#/components/schemas/Duration", "description": "The duration of the event" }, "trigger": { "$ref": "#/components/schemas/RelativeDateTrigger", "deprecated": true, "description": "Deprecated. Use relativeDateTrigger or ordinalWeekdayTrigger instead" }, "relativeDateTrigger": { "$ref": "#/components/schemas/RelativeDateTrigger", "description": "Triggers the event based on a relative date. Mutually exclusive with ordinalWeekdayTrigger" }, "ordinalWeekdayTrigger": { "$ref": "#/components/schemas/OrdinalWeekdayTrigger", "description": "Triggers the event based on an ordinal weekday. Mutually exclusive with relativeDateTrigger" }, "type": { "type": "string", "description": "Attribute that specifies the type of event", "enum": [ "NO_ACTION", "SEND_NOTIFICATION", "MAKE_PAYMENT", "UPDATE_DIRECT_DEBIT_PAYMENTS", "SEND_DD_INVOICE_NOTICE", "SEND_DD_COLLECTION_NOTICE", "SEND_DD_SUCCESS_COLLECTION_NOTICE", "SEND_DD_FAILED_COLLECTION_NOTICE", "START_FALLBACK_WORKFLOW", "SEND_MANDATE_AUTHORISATION_NOTIFICATION", "CREATE_DD_MANDATE", "PREVIEW_CHARGE_DATE", "PREVIEW_PAYOUT_DATE", "SEND_CUSTOMER_STATEMENT_NOTIFICATION" ] }, "details": { "description": "Attribute used for defining details related to an event. Can be utilized to create a new invoice request. This flexibility allows to tailor schedules effectively, ensuring that the appropriate information and formats are used for each scenario" } } }, "Frequency": { "type": "object", "properties": { "timeUnit": { "type": "string", "description": "Time unit measurements used to define the frequency of events", "enum": [ "MONTH, WEEK, DAY" ] }, "frequency": { "type": "integer", "format": "int32", "description": "The frequency of the time units" }, "dayOfMonth": { "type": "integer", "format": "int32", "description": "The specific day of the month designated for executing the event. Please note that short month handling is applicable; if the value is set to 29, 30, or 31, the execution will occur on the last day of the month when applicable" } } }, "InvoiceDetails": { "type": "object", "description": "Invoice details response object.", "properties": { "id": { "type": "string", "description": "The internal id of the invoice" }, "invoiceNo": { "type": "string", "description": "The number of the invoice. Unique value that can be used as idempotency key" }, "description": { "type": "string", "description": "Short description of the invoice" }, "totalAmount": { "type": "string", "description": "The invoice total amount. Includes tax amount, amount paid or reduced with credit notes)" }, "taxAmount": { "type": "string", "description": "The invoice tax amount." }, "dueAmount": { "type": "string", "description": "The invoice amount due (remaining to be paid)." }, "creditNotesAmount": { "type": "string", "description": "The total amount that is credited." }, "dueDate": { "type": "string", "format": "date-time", "description": "The due date of the invoice" }, "issueDate": { "type": "string", "format": "date-time", "description": "The issue date date of the invoice" }, "creationTime": { "type": "string", "format": "date-time", "description": "The date the invoice was created" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The date the invoice was last updated" }, "paidTime": { "type": "string", "format": "date-time", "description": "The date the invoice was paid" }, "status": { "type": "string", "description": "The invoice status", "enum": [ "DRAFT", "UNPAID", "OVERDUE", "SCHEDULED", "SUBMITTED", "PAID", "VOID", "SETTLED" ] }, "statusReasonCode": { "type": "string", "description": "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", "DIRECT_DEBIT_MANDATE_BANK_ACCOUNT_CHANGED" ] }, "statusReason": { "type": "string", "description": "Custom details on why the invoice is in a certain status" }, "itemsTaxType": { "type": "string", "description": "How tax is applied to line items from the invoice", "enum": [ "EXCLUSIVE", "INCLUSIVE", "NONE" ] }, "items": { "type": "array", "description": "The list of items from the invoice", "items": { "$ref": "#/components/schemas/LineItemResponse" } }, "creditNotes": { "type": "array", "description": "The list of credit notes from the invoice", "items": { "$ref": "#/components/schemas/CreditNoteResponse" } }, "fileSource": { "type": "string", "description": "The source of the file currently being served", "enum": [ "NONE", "FILE_UPLOAD", "EXTERNAL", "ADFIN", "PENDING_ADFIN" ] }, "invoiceSource": { "type": "string", "description": "The source of the invoice", "enum": [ "FILE_UPLOAD", "MANUAL", "PR", "EXTERNAL", "SCHEDULE", "PLATFORM" ] }, "externalData": { "type": "array", "description": "References about this invoice from external platforms Adfin integrates with. Such as ID etc", "items": { "$ref": "#/components/schemas/InvoiceExternalData" } } } }, "OrdinalWeekdayTrigger": { "type": "object", "properties": { "ordinal": { "type": "integer", "format": "int32", "description": "The ordinal position of the weekday in the month (e.g., 1 for first, 2 for second, -1 for last)" }, "dayOfWeek": { "type": "string", "description": "The day of the week (MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY)" } }, "required": [ "dayOfWeek", "ordinal" ] }, "RelativeDateTrigger": { "type": "object", "properties": { "days": { "type": "integer", "format": "int32", "description": "The number of days before/after sent date" }, "operator": { "type": "string", "description": "The operator used for determining the send date", "enum": [ "ON", "AFTER", "BEFORE" ] }, "referenceDate": { "type": "string", "description": "The reference date used for computing the date when to execute the workflow step", "enum": [ "DUE_DATE", "SENT_DATE", "PAYMENT_DATE" ] } } }, "WorkflowSettingsRequest": { "type": "object", "properties": { "customerStatementSettings": { "$ref": "#/components/schemas/CustomerStatementSettings", "description": "Configuration for customer statement distribution, including minimum outstanding balance and overdue day thresholds that determine when statements are sent." } } }, "EventResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The internal id of the created event" }, "frequency": { "$ref": "#/components/schemas/Frequency", "description": "The event frequency" }, "duration": { "$ref": "#/components/schemas/Duration", "description": "The event duration" }, "trigger": { "$ref": "#/components/schemas/RelativeDateTrigger", "description": "Deprecated. Use relativeDateTrigger or ordinalWeekdayTrigger instead" }, "relativeDateTrigger": { "$ref": "#/components/schemas/RelativeDateTrigger", "description": "Triggers the event based on a relative date. Mutually exclusive with ordinalWeekdayTrigger" }, "ordinalWeekdayTrigger": { "$ref": "#/components/schemas/OrdinalWeekdayTrigger", "description": "Triggers the event based on an ordinal weekday. Mutually exclusive with relativeDateTrigger" }, "triggerDate": { "type": "string", "format": "date-time", "description": "The event trigger date computed based on event execution configurations" }, "type": { "type": "string", "description": "The type of event", "enum": [ "NO_ACTION", "SEND_NOTIFICATION", "MAKE_PAYMENT", "UPDATE_DIRECT_DEBIT_PAYMENTS", "SEND_DD_INVOICE_NOTICE", "SEND_DD_COLLECTION_NOTICE", "SEND_DD_SUCCESS_COLLECTION_NOTICE", "SEND_DD_FAILED_COLLECTION_NOTICE", "START_FALLBACK_WORKFLOW", "SEND_MANDATE_AUTHORISATION_NOTIFICATION", "CREATE_DD_MANDATE", "PREVIEW_CHARGE_DATE", "PREVIEW_PAYOUT_DATE", "SEND_CUSTOMER_STATEMENT_NOTIFICATION" ] }, "state": { "type": "string", "description": "The current state of the event", "enum": [ "SCHEDULED", "ACTIVE", "PAUSED", "SKIPPED", "FAILED", "FINISHED", "INACTIVE", "DELETED" ] }, "details": { "description": "Attribute used for defining details related to an event. Can be utilized to create a new invoice request. This flexibility allows to tailor instances effectively, ensuring that the appropriate information and formats are used for each scenario" } } }, "ReminderSettingsResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The internal id of the schedule setting" }, "entityId": { "type": "string", "description": "The internal id of the entity for whom this schedule setting was created." }, "entityType": { "type": "string", "description": "Attribute that specifies the type of entity", "enum": [ "INVOICE", "CUSTOMER" ] }, "customerDetails": { "$ref": "#/components/schemas/CustomerDetails", "description": "Information about the customer associated to the entity for whom this schedule setting was created." }, "creationTime": { "type": "string", "format": "date-time", "description": "The creation time of the schedule setting" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "Last time the schedule setting was updated" }, "startTime": { "type": "string", "format": "date-time", "description": "The time when the schedule setting activates" }, "endTime": { "type": "string", "format": "date-time", "description": "The time when the schedule setting expires" } } }, "WorkflowResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The internal id of the workflow created" }, "templateId": { "type": "string", "description": "The internal id of the template used to define the workflow. This template id has been utilized to automatically copy events into the instance, streamlining the process and ensuring consistency throughout" }, "customerDetails": { "$ref": "#/components/schemas/CustomerDetails", "description": "Information about the customer for whom this workflow was created." }, "invoiceDetails": { "$ref": "#/components/schemas/InvoiceDetails", "description": "Information about the invoice for which this workflow was created." }, "name": { "type": "string", "description": "The name of the workflow created for the customer" }, "type": { "type": "string", "description": "Attribute that specifies the type of workflow", "enum": [ "ONE_TIME_PAYMENT", "DD_MANDATE_AUTHORISATION", "DD_PAYMENT", "CUSTOMER_STATEMENT" ] }, "state": { "type": "string", "description": "The current state of the workflow", "enum": [ "DRAFT", "PENDING", "ACTIVE", "PAUSED", "COMPLETED", "TERMINATED" ] }, "paymentInitiationDate": { "type": "string", "format": "date-time", "description": "The payment initiation date of Auto Collect workflows" }, "creationTime": { "type": "string", "format": "date-time", "description": "The creation time of the workflow" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "Last time the workflow was updated" }, "events": { "type": "array", "description": "The list of events that will occur as part of the workflow, applicable exclusively to a single customer", "items": { "$ref": "#/components/schemas/EventResponse" } }, "settings": { "type": "array", "description": "The settings for reminders", "items": { "$ref": "#/components/schemas/ReminderSettingsResponse" } }, "workflowSettings": { "$ref": "#/components/schemas/WorkflowSettingsResponse", "description": "Configuration settings related to schedule." }, "autopilotReasoning": { "type": "string", "description": "The overall strategy reasoning provided by the LLM, present only for autopilot workflows" } }, "required": [ "creationTime", "id", "state", "type" ] }, "WorkflowSettingsResponse": { "type": "object", "properties": { "reminderSettings": { "type": "array", "description": "Scheduled reminder configurations for invoices or customers, defining when automated reminders should be sent based on start and end times", "items": { "$ref": "#/components/schemas/ReminderSettingsResponse" } }, "customerStatementSettings": { "$ref": "#/components/schemas/CustomerStatementSettings", "description": "Configuration for customer statement distribution, including minimum outstanding balance and overdue day thresholds that determine when statements are sent." } } }, "CollectionDetails": { "type": "object", "description": "Information about how an invoice or payment request is distributed and collected.\n\nThis defines:\n- The method by which payment is expected to be collected.\n- The workflow template used to send the invoice or payment request.\n- Optional custom message for the customer.\n- Approval status for automatically distributing to the customer.\n", "example": { "collectionMethod": "AUTO_COLLECT", "customMessage": "Thank you for your business!", "approvedForSending": true }, "properties": { "collectionMethod": { "type": "string", "description": "How the payment is expected to be collected.\nFor example:\n- `AUTO_COLLECT`: Collected automatically via direct debit. Takes effect once the customer has an active direct debit mandate; until they sign, collection waits with status reason `PENDING_DD_MANDATE`.\n- `ON_DEMAND`: Collected via other payment methods (eg. `CARD`, `APPLE_PAY`, `GOOGLE_PAY`, `BANK`).\n- `NONE`: No payment collection is initiated automatically.\n", "enum": [ "AUTO_COLLECT", "ON_DEMAND", "NONE" ] }, "templateId": { "type": "string", "format": "uuid", "description": "The workflow template ID used for sending the invoice or payment request to the customer.\nOptional — if null, the system default template will be used.\n", "example": "d290f1ee-6c54-4b01-90e6-d701748f0851" }, "customMessage": { "type": "string", "description": "An optional message that will be sent to the customer when the invoice or payment request is distributed.\nCan be used for personalized greetings or additional instructions.\n", "example": "Please find your invoice attached. Thank you!" }, "approvedForSending": { "type": "boolean", "default": true, "description": "Boolean flag specifying whether the invoice or payment request is approved for sending.\nDefaults to `true` if not explicitly set.\n" } }, "required": [ "approvedForSending" ] }, "IntervalCadence": { "type": "object", "description": "A cadence that recurs at a fixed interval.\nUse this to define schedules that repeat every N units of time,\nsuch as \"every 2 weeks\" or \"every 3 months\".\n", "example": { "timeUnit": "WEEK", "frequency": 2, "startDate": "2025-01-01T00:00:00.000Z", "endDate": "2025-12-31T23:59:59.000Z" }, "properties": { "timeUnit": { "type": "string", "description": "Determines whether the cadence repeats in weeks, months or years.\nCommon values:\n- WEEK\n- MONTH\n- YEAR\n", "example": "WEEK" }, "frequency": { "type": "integer", "format": "int32", "description": "Combined with `timeUnit` to determine how often the cadence occurs.\nFor example:\n- `frequency = 2` and `timeUnit = WEEK` → every 2 weeks\n- `frequency = 1` and `timeUnit = MONTH` → every month\n", "example": 2, "minimum": 1 }, "startDate": { "type": "string", "format": "date-time", "description": "The first occurrence happens at this time.\nFormat: ISO 8601 with milliseconds, e.g. `2025-01-01T00:00:00.000Z`.\nTimestamps without milliseconds are rejected.\n", "example": "2025-01-01T00:00:00.000Z" }, "endDate": { "type": "string", "format": "date-time", "description": "Optional end date for the cadence.\nIf provided, the generation stops at or before this date.\nIf omitted, the cadence continues indefinitely.\n", "example": "2025-12-31T23:59:59.000Z" } }, "required": [ "frequency", "startDate", "timeUnit" ] }, "PaymentTerm": { "type": "object", "description": "Defines the duration before an invoice is due, using a combination of a time unit and value.\nFor example, a value of `30` with a `timeUnit` of `DAYS` represents \"net 30 days\".\n", "example": { "timeUnit": "DAYS", "value": 30 }, "properties": { "timeUnit": { "type": "string", "description": "The unit of time for the payment term.\nCommon values include:\n- `DAYS`\n- `WEEKS`\n- `MONTHS`\n\nOptional. Defaults to `DAYS` if not provided.\n", "enum": [ "SECOND", "MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "YEAR" ], "example": "DAYS" }, "value": { "type": "integer", "format": "int32", "description": "The numeric value of the payment term.\nCombined with `timeUnit` to calculate due dates.\n", "example": 30 } } }, "RecurringPaymentRequestDetails": { "type": "object", "description": "Defines the configuration for a **Payment Request (PR)** automatically generated.\n\nThis object specifies the customer, collection workflow, currency, payment terms for the payment requests.\n", "example": { "customer": { "id": "80349480-490b-4234-92e7-fad697e3d446" }, "paymentTerm": { "timeUnit": "DAY", "value": 30 }, "distribution": { "collectionMethod": "AUTO_COLLECT", "templateId": "dc9c7c6e-4c12-4cc9-8d22-20c5b2a7f8f7", "customMessage": "Please review and confirm payment.", "approvedForSending": true }, "amount": 1200, "taxRate": 20, "currencyCode": "GBP", "description": "Quarterly service fee", "reference": "Q1-2025" }, "properties": { "customer": { "$ref": "#/components/schemas/CustomerDetails", "description": "Adfin customer ID associated with this payment request.\n", "example": { "id": "80349480-490b-4234-92e7-fad697e3d446" } }, "paymentTerm": { "$ref": "#/components/schemas/PaymentTerm", "description": "Defines when payment is due after the payment request is issued.\n\nThis field represents the payment term, consisting of:\n- `timeUnit`: The unit of time (`DAY`, `WEEK`, etc.)\n- `value`: The duration\n\nBehavior:\n- When the distribution method is `ON_DEMAND`: you may freely configure this field.\n- When the distribution method is `AUTO_COLLECT`: this value is **always fixed to 3 DAY** and cannot be changed.\n\nExamples:\n- `{ \"timeUnit\": \"DAY\", \"value\": 30 }` → Payment due 30 days after issue\n- `{ \"timeUnit\": \"WEEK\", \"value\": 2 }` → Payment due 2 weeks after issue\n", "example": { "timeUnit": "DAY", "value": 30 } }, "distribution": { "$ref": "#/components/schemas/CollectionDetails", "description": "Specifies how the payment request will be sent and collected.\n" }, "amount": { "type": "number", "description": "The total amount to be collected for each of the payment requests generated.\n", "example": 1200 }, "taxRate": { "type": "number", "description": "The INCLUSIVE tax rate (%) applied to the payment request.\n", "example": 20 }, "currencyCode": { "type": "string", "description": "The three-letter ISO 4217 currency code (e.g., `GBP`, `EUR`, `USD`).\nIndicates the currency in which the payment request is issued.\n", "example": "GBP" }, "description": { "type": "string", "description": "A short, description of the payment request.\n", "example": "Quarterly service fee" }, "reference": { "type": "string", "description": "An optional reference or identifier that links this payment request\nto another system or document.\n", "example": "Q1-2025" } }, "required": [ "amount", "currencyCode", "customer", "distribution" ] }, "UpdateRecurringPaymentRequestRequest": { "type": "object", "description": "Update a recurring payment request.", "properties": { "cadence": { "$ref": "#/components/schemas/IntervalCadence", "description": "Specifies the frequency and recurrence pattern for payment request generation.\n\nExample:\n- `INTERVAL`: Fixed interval (e.g., every 2 weeks).\n" }, "paymentRequestDetails": { "$ref": "#/components/schemas/RecurringPaymentRequestDetails", "description": "Specifies the details of payment request that will be generated.\n\nContains metadata such as the customer, collection terms, amount and tax configuration.\n" } } }, "NewLineItemRequest": { "type": "object", "description": "Create line items.", "properties": { "description": { "type": "string", "description": "The description of the item." }, "quantity": { "type": "number", "description": "The quantity of items." }, "unitAmount": { "type": "number", "description": "The price per unit of the item." }, "taxRate": { "type": "number", "description": "The tax rate percentage applied on the line item amount (quantity * unit amount)." }, "taxRateId": { "type": "string", "description": "Tax rate id for this line item. Use the Tax Rates API to manage your tax rates.", "example": "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6" }, "accountCodeId": { "type": "string", "description": "Sales account id for this line item. If you require specific sales accounts to be used, provide the account code id here. To recieve your account codes, contact support@adfin.com" }, "productId": { "type": "string", "description": "The base product id for this line item. Use the Items catalog API to manage your products.", "example": "d4f1c2b3-4a5b-678c-9d0e-f1a2b3c4d5e6" }, "trackingItemIds": { "type": "array", "description": "Tracking item catalogue IDs for this line item.", "items": { "type": "string", "format": "uuid" } } } }, "NextInvoiceResponse": { "type": "object", "description": "Represents the next scheduled invoice within a recurring invoice schedule.\n\nThis object provides information about when the next invoice will be issued\nand when it is due, based on the schedule’s cadence and payment terms.\n", "properties": { "index": { "type": "integer", "format": "int32", "description": "The sequence number of this invoice within the schedule.\n\nStarts from `1` for the first generated invoice and increments for each occurrence.\n", "example": 3 }, "issueDate": { "type": "string", "format": "date-time", "description": "The date and time when the next invoice will be issued to the customer.\nDetermined by the cadence configuration.\n", "example": "2025-11-01T00:00:00Z" }, "dueDate": { "type": "string", "format": "date-time", "description": "The date and time when the invoice is due for payment.\nCalculated based on the payment terms.\n", "example": "2025-11-08T00:00:00Z" } } }, "RecurringInvoiceDetails": { "type": "object", "description": "This defines the structure and configuration of invoices that will be automatically generated.\n", "example": { "customer": { "id": "80349480-490b-4234-92e7-fad697e3d446" }, "paymentTerm": { "timeUnit": "DAY", "value": 30 }, "distribution": { "collectionMethod": "AUTO_COLLECT", "customMessage": "Please find your invoice attached. Thank you for your business!", "approvedForSending": true }, "description": "Monthly subscription for January", "currencyCode": "GBP", "itemsTaxType": "INCLUSIVE", "items": [ { "description": "Pro Plan Subscription", "unitAmount": 5000, "quantity": 1, "taxRate": 0.1 } ] }, "properties": { "customer": { "$ref": "#/components/schemas/CustomerDetails", "description": "Adfin customer ID associated with this invoice.\n", "example": { "id": "80349480-490b-4234-92e7-fad697e3d446" } }, "paymentTerm": { "$ref": "#/components/schemas/PaymentTerm", "description": "The payment terms for this invoice, specifying when payment is due.\n\nOptional — defaults to your organization's standard payment term if not provided.\nRepresented as a combination of `timeUnit` and `value`.\nFor `AUTO_COLLECT`, the payment term must be at least 3 days, so the direct debit payment notification can be sent to the customer before collection.\n", "example": { "timeUnit": "DAY", "value": 30 } }, "distribution": { "$ref": "#/components/schemas/CollectionDetails", "description": "Information about how this invoice is distributed and collected.\n" }, "description": { "type": "string", "description": "A short summary or purpose of the invoice.\nAppears in both the invoice document and customer communications.\n", "example": "Monthly subscription fee for January 2025" }, "currencyCode": { "type": "string", "description": "The three-letter ISO 4217 currency code (e.g., `GBP`, `EUR`, `USD`).\nIndicates the currency in which the invoice is issued.\n", "example": "GBP" }, "itemsTaxType": { "type": "string", "description": "Defines how tax is applied to the invoice line items.\n\nPossible values:\n- `INCLUSIVE`: Tax is included in item prices.\n- `EXCLUSIVE`: Tax is added on top of item prices.\n- `NONE`: No tax applied.\n", "example": "INCLUSIVE" }, "items": { "type": "array", "description": "The list of line items included in the invoice.\nEach item represents a product, service, or fee with its own amount and tax configuration.\n", "example": [ { "description": "Monthly Pro Plan Subscription", "unitAmount": 5000, "quantity": 1 }, { "description": "Additional API Usage", "unitAmount": 2000, "quantity": 1 } ], "items": { "$ref": "#/components/schemas/NewLineItemRequest" } }, "officeId": { "type": "string", "format": "uuid", "description": "The unique identifier of the office associated with this invoice.", "example": "80349480-490b-4234-92e7-fad697e3d446" } }, "required": [ "currencyCode", "customer", "distribution", "items", "itemsTaxType" ] }, "RecurringInvoiceResponse": { "type": "object", "description": "A schedule that defines when and how invoices are automatically generated for a customer,\nincluding cadence, payment terms, items, etc..\n", "properties": { "id": { "type": "string", "description": "The Adfin ID of the recurring invoice.", "example": 1 }, "recurringInvoiceNo": { "type": "string", "description": "A system-generated, unique identifier for the recurring invoice.\nAutomatically created using the prefix SCH followed by a numeric sequence (e.g., SCH-1, SCH-2, ...).\n", "example": "SCH-42" }, "nextIssueDate": { "type": "string", "format": "date-time", "description": "The next date a new invoice will be automatically generated.", "example": "2025-10-15T00:00:00Z" }, "status": { "type": "string", "description": "Indicates the current status of the recurring invoice.\nPossible values might include:\n- `DRAFT` – currently not generating new invoices\n- `ACTIVE` – currently generating new invoices\n- `FINISHED` – has finished all planned occurrences\n- `CANCELLED` – has been cancelled before finishing all planned occurrences\n", "example": "ACTIVE" }, "cadence": { "$ref": "#/components/schemas/IntervalCadence", "description": "Defines the recurrence pattern.\nUses a fixed interval cadence specifying:\n- `timeUnit`: Unit of time (WEEK, MONTH, YEAR)\n- `frequency`: Number of units between each occurrence\n- `startDate`: First occurrence\n- `endDate`: Optional final occurrence\n" }, "invoiceDetails": { "$ref": "#/components/schemas/RecurringInvoiceDetails", "description": "Details of the invoices to be automatically generated.\nIncludes:\n- `customer` – recipient of the invoice\n- `paymentTerm` – when the invoice is due\n- `distribution` – how the invoice is delivered and collected\n- `description` – optional summary\n- `currencyCode` – ISO 4217 currency code\n- `itemsTaxType` – tax applied on line items\n- `items` – individual line items in the invoice\n" }, "creationTime": { "type": "string", "format": "date-time", "description": "The date and time when the recurring invoice was created.", "example": "2025-09-27T12:00:00Z" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The date and time when the recurring invoice was last updated.", "example": "2025-10-01T08:30:00Z" }, "totalInvoices": { "type": "integer", "format": "int32", "description": "The total number of invoices this recurring invoice is expected to generate\nbased on cadence, start date, and end date.\n", "example": 10 }, "amount": { "type": "number", "description": "The total amount of the recurring invoice.\nCalculated based on the sum of all invoice line items across all occurrences.\n", "example": 1234.5 }, "nextInvoices": { "type": "array", "description": "A list of upcoming invoices to be generated.\nOrdered by index and date, and limited to a maximum of 12 items.\n", "items": { "$ref": "#/components/schemas/NextInvoiceResponse" } } } }, "NextPaymentRequestResponse": { "type": "object", "description": "Represents the next scheduled payment request within a recurring payment request schedule.\n\nThis object provides information about when the next payment request will be issued\nand when it is due, based on the schedule’s cadence and payment terms.\n", "properties": { "index": { "type": "integer", "format": "int32", "description": "The sequence number of this payment request within the schedule.\n\nStarts from `1` for the first generated payment request and increments for each occurrence.\n", "example": 3 }, "issueDate": { "type": "string", "format": "date-time", "description": "The date and time when the next payment request will be issued to the customer.\nDetermined by the cadence configuration.\n", "example": "2025-11-01T00:00:00Z" }, "payByDate": { "type": "string", "format": "date-time", "description": "The date and time when the payment request is due for payment.\nCalculated based on the payment terms.\n", "example": "2025-11-08T00:00:00Z" } } }, "RecurringPaymentRequestResponse": { "type": "object", "description": "A schedule that defines when and how payment request are automatically generated for a customer,\nincluding cadence, payment terms, etc..\n", "properties": { "id": { "type": "string", "description": "The Adfin ID of the recurring payment request.", "example": 1 }, "recurringPaymentRequestNo": { "type": "string", "description": "A system-generated, unique identifier for the recurring payment request.\nAutomatically created using the prefix SCH followed by a numeric sequence (e.g., SCH-1, SCH-2, ...).\n", "example": "SCH-42" }, "nextDate": { "type": "string", "format": "date-time", "description": "The next date a new payment request will be generated.", "example": "2025-10-15T00:00:00Z" }, "status": { "type": "string", "description": "Indicates the current status of the recurring payment request.\nPossible values might include:\n- `ACTIVE` – currently generating new payment request\n- `FINISHED` – has finished all planned occurrences\n- `CANCELLED` – has been cancelled before finishing all planned occurrences\n", "example": "ACTIVE" }, "cadence": { "$ref": "#/components/schemas/IntervalCadence", "description": "Defines the recurrence pattern.\nUses a fixed interval cadence specifying:\n- `timeUnit`: Unit of time (WEEK, MONTH, YEAR)\n- `frequency`: Number of units between each occurrence\n- `startDate`: First occurrence\n- `endDate`: Optional final occurrence\n" }, "paymentRequestDetails": { "$ref": "#/components/schemas/RecurringPaymentRequestDetails", "description": "Details of the payment request to be automatically generated.\nIncludes:\n- `customer` – recipient of the payment request\n- `paymentTerm` – when the payment request is due\n- `distribution` – how the payment request is delivered and collected\n- `description` – optional summary\n- `currencyCode` – ISO 4217 currency code\n- `amount` - amount of the payment request\n" }, "creationTime": { "type": "string", "format": "date-time", "description": "The date and time when the recurring payment request was created.", "example": "2025-09-27T12:00:00Z" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The date and time when the recurring payment request was last updated.", "example": "2025-10-01T08:30:00Z" }, "totalPaymentRequests": { "type": "integer", "format": "int32", "description": "The total number of payment requests this recurring payment request is expected to generate\nbased on cadence, start date, and end date.\n", "example": 10 }, "nextPaymentRequests": { "type": "array", "description": "A list of upcoming payment requests to be generated.\nOrdered by index and date, and limited to a maximum of 12 items.\n", "items": { "$ref": "#/components/schemas/NextPaymentRequestResponse" } } } }, "UpdateRecurringInvoiceRequest": { "type": "object", "description": "Update a recurring invoice.", "properties": { "cadence": { "$ref": "#/components/schemas/IntervalCadence", "description": "Specifies the frequency and recurrence pattern for invoice generation.\n\nExample:\n- `INTERVAL`: Fixed interval (e.g., every 2 weeks).\n" }, "invoiceDetails": { "$ref": "#/components/schemas/RecurringInvoiceDetails", "description": "Specifies the details of invoices that will be automatically generated.\n\nContains metadata such as the customer, collection terms, line items and tax configuration.\n" } } }, "UpdatePaymentRequestRequest": { "type": "object", "description": "Update a payment request.", "properties": { "paymentRequestNo": { "type": "string", "description": "The payment request number.", "example": "PR-1234" }, "description": { "type": "string", "description": "A short description or summary of the payment request.", "example": "Monthly subscription fee for January", "maxLength": 200, "minLength": 0 }, "payByDate": { "type": "string", "format": "date-time", "description": "The pay by date for the payment request.", "example": "2025-12-15T23:59:59Z" }, "amount": { "type": "number", "description": "The payment request amount", "example": 99.99, "minimum": 0.01 }, "reference": { "type": "string", "description": "reference for the payment request", "example": "REF 123456", "maxLength": 22, "minLength": 0, "pattern": "^[a-zA-Z0-9 .]*$" }, "taxRate": { "type": "number", "description": "tax rate percentage applied on the payment request amount.", "example": 20, "maximum": 100, "minimum": 0 }, "redirectUrl": { "type": "string", "description": "The (optional) redirect URL to redirect the user after they complete the payment" } }, "required": [ "amount" ] }, "AccountDetailsResponse": { "type": "object", "description": "The account details response.", "properties": { "id": { "type": "string", "description": "The ID of the account code." }, "code": { "type": "string", "description": "The account code value." } } }, "Address": { "type": "object", "description": "The address of a biller location", "properties": { "id": { "type": "string", "description": "The internal id of the address." }, "city": { "type": "string", "description": "The name of the city." }, "postalCode": { "type": "string", "description": "The postal code." }, "country": { "type": "string", "description": "The name of the biller country." }, "addressLine1": { "type": "string", "description": "The name of the street, and the house or building number." } } }, "Advance": { "type": "object", "description": "Advance details for a payment without existing payment requests", "properties": { "customerId": { "type": "string", "description": "The ID of the customer" }, "amount": { "type": "number", "description": "The amount to be paid" }, "currencyCode": { "type": "string", "description": "The currency code", "enum": [ "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" ] } }, "required": [ "amount", "currencyCode", "customerId" ] }, "BankAccount": { "type": "object", "properties": { "accountNumber": { "type": "string" }, "sortCode": { "type": "string" } } }, "Cadence": { "type": "object", "description": "The cadence of the schedule", "properties": { "type": { "type": "string", "description": "The type of the cadence (INTERVAL, DAY_OF_MONTH, etc.)", "enum": [ "INTERVAL", "INTERVAL_COUNT", "DAY_OF_MONTH", "CUSTOM" ] }, "timeUnit": { "type": "string", "description": "Required if type is INTERVAL.\nDefines the time unit (e.g., DAYS, MONTHS, etc.).\n", "enum": [ "SECOND", "MINUTE", "HOUR", "DAY", "WEEK", "MONTH", "YEAR" ] }, "frequency": { "type": "integer", "format": "int32", "description": "Required if type is INTERVAL.\nFrequency of recurrence (e.g., every N time units).\n", "minimum": 1 }, "dayOfMonth": { "type": "integer", "format": "int32", "description": "Required if type is DAY_OF_MONTH.\nSpecifies the day of the month the schedule applies.\n" }, "dates": { "type": "array", "description": "Required if type is CUSTOM.\nA list of exact custom dates for the cadence.\n", "items": { "type": "string", "format": "date-time" } }, "startDate": { "type": "string", "format": "date-time", "description": "The start date of the schedule" }, "endDate": { "type": "string", "format": "date-time", "description": "The (optional) end date of the schedule" }, "count": { "type": "integer", "format": "int32", "description": "The total number of items. Required for INTERVAL_COUNT type", "maximum": 120, "minimum": 2 } }, "required": [ "startDate", "type" ] }, "CatalogueExternalDataRequest": { "type": "object", "properties": { "connectorType": { "type": "string", "description": "The name of the platform for which this data is stored for.", "enum": [ "XERO", "QUICKBOOKS", "PLATFORM" ] }, "externalId": { "type": "string", "description": "The unique id of the item in the external platform." } } }, "CreditNoteExternalData": { "type": "object", "description": "References about the credit note from external platforms Adfin integrates with.", "properties": { "connectorType": { "type": "string", "description": "The name of the platform for which this data is stored for.", "enum": [ "XERO", "QUICKBOOKS", "PLATFORM" ] }, "id": { "type": "string", "description": "ID of the Credit Note in the external platform" } } }, "CreditNoteResponse": { "type": "object", "description": "Credit note details.", "properties": { "id": { "type": "string", "description": "Credit note id." }, "number": { "type": "string", "description": "Credit note number." }, "amount": { "type": "number", "description": "Credit note amount." }, "valueDate": { "type": "string", "format": "date-time", "description": "Date when credit note was applied." }, "externalData": { "type": "array", "description": "References about this credit note from external platforms Adfin integrates with. Such as ID etc", "items": { "$ref": "#/components/schemas/CreditNoteExternalData" } } } }, "CustomField": { "type": "object", "description": "A custom field containing field and field value information.", "properties": { "fieldId": { "type": "string", "description": "The ID of the field definition." }, "fieldValueId": { "type": "string", "description": "The ID of the specific field value." } } }, "CustomerBankAccount": { "type": "object", "description": "The bank account of the customer used for bank transfers", "properties": { "accountHolderAddress": { "$ref": "#/components/schemas/Address", "description": "Address of the bank account holder. Optional; used for compliance and verification." }, "accountHolderName": { "type": "string", "description": "Full name of the bank account holder as registered with the bank." }, "bankAccount": { "$ref": "#/components/schemas/BankAccount", "description": "Bank account identifiers (e.g., account number and sort code or IBAN/BIC)." }, "bankAddress": { "$ref": "#/components/schemas/Address", "description": "Address of the banking institution. Optional." }, "currencyCode": { "type": "string", "description": "Currency of the bank account (ISO 4217).", "enum": [ "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" ] } }, "required": [ "accountHolderName", "bankAccount", "currencyCode" ] }, "CustomerDiscount": { "type": "object", "description": "The customer discount details.", "properties": { "percentage": { "type": "number", "description": "The discount as a percentage to be applied for the invoices." }, "period": { "type": "integer", "format": "int32", "description": "The period in hours until the discount expires." } } }, "CustomerExternalData": { "type": "object", "description": "References about the customer from external platforms Adfin integrates with.", "properties": { "connectorType": { "type": "string", "description": "The name of the platform for which this data is stored for.", "enum": [ "XERO", "QUICKBOOKS" ] }, "id": { "type": "string", "description": "The ID of the Customer in the external platform." }, "name": { "type": "string", "description": "The name of the Customer in the external platform." } }, "required": [ "connectorType", "id" ] }, "CustomerPaymentSettingsResponse": { "type": "object", "description": "Customer payment settings", "properties": { "allowPartialPayments": { "type": "boolean", "description": "Indicates whether partial payments are allowed" }, "minPartialPaymentAmount": { "type": "number", "description": "The minimum amount for partial payments" }, "surchargeIsEnabled": { "type": "boolean", "description": "Indicates whether a surcharge is applied to commercial card payments" }, "lateFeesIsEnabled": { "type": "boolean", "description": "Indicates whether late fees calculation is enabled" } } }, "CustomerResponse": { "type": "object", "description": "The customer details.", "properties": { "id": { "type": "string", "description": "The Adfin id of the customer." }, "externalId": { "type": "string", "description": "The id of the customer from the platform that is integrating with Adfin." }, "name": { "type": "string", "description": "The full name of the customer." }, "creationTime": { "type": "string", "format": "date-time", "description": "The time the customer was created." }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The last time when the customer was updated." }, "people": { "type": "array", "description": "The list of people assigned to the customer.", "items": { "$ref": "#/components/schemas/Person" } }, "addresses": { "type": "array", "description": "The list of the addresses for the customer.", "items": { "$ref": "#/components/schemas/Address" } }, "directDebitMandate": { "$ref": "#/components/schemas/DirectDebitMandateSummary", "description": "Direct Debit details (if a mandate was created)." }, "billerBankAccount": { "$ref": "#/components/schemas/CustomerBankAccount", "description": "Biller bank account for bank transfers" }, "timezone": { "type": "string", "description": "The timezone of the customer." }, "discount": { "$ref": "#/components/schemas/CustomerDiscount", "description": "The discount applied for the customer." }, "externalData": { "type": "array", "description": "References about this customer from external platforms Adfin integrates with, such as ID, etc.", "items": { "$ref": "#/components/schemas/CustomerExternalData" } }, "tags": { "type": "array", "description": "The tag ids associated with the customer.", "items": { "type": "string" } }, "status": { "type": "string", "description": "The status of the customer (ACTIVE, ARCHIVED)", "enum": [ "ACTIVE", "ARCHIVED" ] }, "statusReasonCode": { "type": "string", "description": "The reason as a predefined code for why the customer is in a certain status", "enum": [ "MERGED", "ARCHIVED_MANUALLY" ] }, "settings": { "$ref": "#/components/schemas/CustomerSettingsResponse" }, "trackingItems": { "type": "array", "description": "The tracking item catalogues associated with the customer.", "items": { "$ref": "#/components/schemas/TrackingItemCatalogueResponse" } }, "office": { "$ref": "#/components/schemas/InvoiceOfficeResponse", "description": "The office associated with the customer." } } }, "CustomerSettingsResponse": { "type": "object", "description": "Customer settings", "properties": { "paymentSettings": { "$ref": "#/components/schemas/CustomerPaymentSettingsResponse" } } }, "DirectDebitMandateSummary": { "type": "object", "description": "Direct Debit details.", "properties": { "id": { "type": "string", "description": "The id of the direct debit mandate." }, "status": { "type": "string", "description": "Current status of the direct debit.", "enum": [ "CREATED", "PENDING", "ACTIVE", "PENDING_CANCELLATION", "CANCELLED", "MIGRATING" ] }, "statusReasonCode": { "type": "string", "description": "The reason as predefined code why the mandate is in a certain status", "enum": [ "PENDING_DD_CAPABILITY", "PENDING_ACTIVATION", "MIGRATED", "BANK_ACCOUNT_CHANGED", "INCORRECT_BANK_DETAILS", "INSTRUCTION_CANCELLED_BY_PAYER", "PAYER_DECEASED", "ACCOUNT_TRANSFERRED", "ADVANCE_NOTICE_DISPUTED", "AMOUNT_DISPUTED", "MANDATE_NOT_FOUND", "DISPUTE_TOO_EARLY", "DISPUTE_TOO_LATE", "INVALID_SORT_CODE", "INVALID_ACC_NUMBER", "ACCOUNT_CLOSED", "CANCELLED_ON_DEMAND", "REINSTATED", "MIGRATION_TIMEOUT", "DISCARDED_BY_BILLER", "ACCEPTED_ON_CREATION", "OTHER" ] }, "statusReason": { "type": "string", "description": "Reason explaining the current status of the direct debit mandate, especially useful for failure cases." }, "creationTime": { "type": "string", "format": "date-time", "description": "The time when the mandate was created" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The last time when the mandate was updated" }, "authorisationTime": { "type": "string", "format": "date-time", "description": "The time when the mandate was signed by the customer" }, "submissionTime": { "type": "string", "format": "date-time", "description": "The time when the mandate was submitted to the payment provider" }, "url": { "type": "string", "description": "The URL where the customer can sign the direct debit mandate." }, "bankAccountNumber": { "type": "string", "description": "The bank account number associated with the mandate." }, "mandateContactId": { "type": "string", "description": "The ID of the person linked as the mandate contact" }, "distributionTime": { "type": "string", "format": "date-time", "description": "The time when the mandate was first sent to the customer" }, "lastNotificationSentTime": { "type": "string", "format": "date-time", "description": "The time when the mandate was last sent to the customer" } } }, "DiscountDetails": { "type": "object", "description": "Information about the discount applied to the payment request", "properties": { "totalAmount": { "type": "number", "description": "The discounted amount" }, "expirationDate": { "type": "string", "format": "date-time", "description": "The date until when the discount is valid" } } }, "DistributionDetails": { "type": "object", "description": "Information about how a payment request is distributed and collected.", "properties": { "collectionMethod": { "type": "string", "description": "How the payment is expected to be collected for this payment request.", "enum": [ "ONE_TIME_PAYMENT", "DIRECT_DEBIT_PAYMENT", "NONE" ] }, "customMessage": { "type": "string", "description": "An optional message that will be sent to the customer when the payment request is distributed." }, "templateId": { "type": "string", "description": "The schedule template id used for sending the payment request to customer." }, "cancelCollectionOnFailure": { "type": "boolean", "description": "Whether collection should be cancelled if the payment fails" } } }, "FeeDetails": { "type": "object", "description": "Fee details applied to a payment", "properties": { "amount": { "type": "number", "description": "The amount of the fee" }, "applicationMethod": { "type": "string", "description": "The fee application method", "enum": [ "SURCHARGE", "LATE_FEE" ] }, "items": { "type": "array", "description": "The fee item breakdown", "items": { "$ref": "#/components/schemas/FeeItemDetail" } } } }, "FeeItemDetail": { "type": "object", "description": "Fee item detail within a payment fee", "properties": { "amount": { "type": "number", "description": "The amount allocated to this fee item" }, "type": { "type": "string", "description": "The fee item type (e.g. DAILY_INTEREST, FIXED_FEE)", "enum": [ "DAILY_INTEREST", "FIXED_FEE", "WAIVER" ] } } }, "FeeItemResponse": { "type": "object", "description": "Fee item details", "properties": { "id": { "type": "string", "format": "uuid", "description": "The fee item id" }, "type": { "type": "string", "description": "The fee item type", "enum": [ "DAILY_INTEREST", "FIXED_FEE", "WAIVER" ] }, "description": { "type": "string", "description": "The fee item description" }, "amount": { "type": "number", "description": "The fee item amount" }, "dueAmount": { "type": "number", "description": "The outstanding amount for this fee item" } } }, "FeeResponse": { "type": "object", "description": "Fee details", "properties": { "id": { "type": "string", "format": "uuid", "description": "The fee id" }, "amount": { "type": "number", "description": "The total fee amount" }, "dueAmount": { "type": "number", "description": "The outstanding fee amount" }, "type": { "type": "string", "description": "The fee type", "enum": [ "LATE_FEE" ] }, "effectiveDate": { "type": "string", "format": "date-time", "description": "The date when the fee becomes effective" }, "items": { "type": "array", "description": "The fee item breakdown", "items": { "$ref": "#/components/schemas/FeeItemResponse" } } } }, "InstalmentDetails": { "type": "object", "description": "Instalment details", "properties": { "index": { "type": "integer", "format": "int32", "description": "The index of the instalment within the instalment plan (1-based)" }, "cadence": { "$ref": "#/components/schemas/Cadence", "description": "The cadence configuration for the instalment plan" } }, "required": [ "cadence" ] }, "InvoiceExternalData": { "type": "object", "description": "References about the invoice from external platforms Adfin integrates with.", "properties": { "connectorType": { "type": "string", "description": "The name of the platform for which this data is stored for.", "enum": [ "XERO", "QUICKBOOKS", "PLATFORM" ] }, "id": { "type": "string", "description": "ID of the Invoice in the external platform" }, "brandingThemeId": { "type": "string", "description": "ID of the branding theme the invoice uses in the external platform, if any." } } }, "InvoiceOfficeDetailsResponse": { "type": "object", "description": "The office contact and address details.", "properties": { "email": { "type": "string", "description": "The office email address." }, "addressLine1": { "type": "string", "description": "The first line of the address." }, "addressLine2": { "type": "string", "description": "The second line of the address." }, "city": { "type": "string", "description": "The city." }, "country": { "type": "string", "description": "The country." }, "postcode": { "type": "string", "description": "The postcode." } } }, "InvoiceOfficeResponse": { "type": "object", "description": "The office associated with the customer.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the office." }, "name": { "type": "string", "description": "The name of the office." }, "trackingItemId": { "type": "string", "format": "uuid", "description": "The tracking item identifier." }, "details": { "$ref": "#/components/schemas/InvoiceOfficeDetailsResponse", "description": "The office contact and address details." } } }, "LineItemExternalData": { "type": "object", "description": "References about the line items from external platforms Adfin integrates with.", "properties": { "id": { "type": "string", "description": "The ID from the external platform" }, "connectorType": { "type": "string", "description": "The name of the platform for which this data is stored for.", "enum": [ "XERO", "QUICKBOOKS", "PLATFORM" ] }, "templateId": { "type": "string", "description": "The template ID from external platform from which this line item is created. Cannot use both the template ID and the account code." }, "accountCode": { "type": "string", "description": "The account code from external platform from which this line item is created. Cannot use both the template ID and the account code." }, "groupLineId": { "type": "string", "description": "The ID of the external platform's group line this line item is a component of. Null when the line item does not belong to a group." } } }, "LineItemResponse": { "type": "object", "description": "The line items associated with the invoice.", "properties": { "id": { "type": "string", "description": "The ID of the line item to update." }, "description": { "type": "string", "description": "The description of the item." }, "quantity": { "type": "number", "description": "The quantity of items." }, "unitAmount": { "type": "number", "description": "The price per unit of the item." }, "taxRate": { "type": "number", "description": "The tax rate percentage applied on the line item amount (quantity * unit amount)." }, "taxAmount": { "type": "number", "description": "The tax amount added on top of the line item amount." }, "totalAmount": { "type": "number", "description": "The total price of the item." }, "taxDetails": { "$ref": "#/components/schemas/TaxDetailsResponse", "description": "Tax rate details for this line item." }, "accountDetails": { "$ref": "#/components/schemas/AccountDetailsResponse", "description": "Account details for this line item." }, "productDetails": { "$ref": "#/components/schemas/ProductDetailsResponse", "description": "Product details for this line item." }, "externalData": { "type": "array", "description": "Information about this line item captured from external systems", "items": { "$ref": "#/components/schemas/LineItemExternalData" } }, "trackingItems": { "type": "array", "description": "The tracking items associated with this line item.", "items": { "$ref": "#/components/schemas/TrackingItemDetailsResponse" } } } }, "PaymentAllocationResponse": { "type": "object", "description": "Payment response details", "properties": { "id": { "type": "string", "description": "The ID of the payment allocation" }, "paymentId": { "type": "string", "description": "The ID of the payment" }, "paymentRequestId": { "type": "string", "description": "The ID of the payment request" }, "creationTime": { "type": "string", "format": "date-time", "description": "The date when the payment was initiated" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The last time when the payment was updated" }, "advance": { "$ref": "#/components/schemas/Advance", "description": "Advance details. Required when prAllocations are not provided." }, "prAllocations": { "type": "array", "description": "Per-payment-request allocations for this payment", "items": { "$ref": "#/components/schemas/PrAllocation" } }, "amount": { "type": "number", "description": "The paid amount" }, "feeDetails": { "$ref": "#/components/schemas/FeeDetails", "deprecated": true, "description": "Details about the applied fee" }, "fees": { "type": "array", "description": "Details about the applied fees", "items": { "$ref": "#/components/schemas/FeeDetails" } }, "status": { "type": "string", "description": "The current payment status", "enum": [ "PENDING", "SUBMITTED", "SENT", "SUCCESS", "CANCELLED", "FAILED", "SETTLED" ] }, "receiptNo": { "type": "string", "description": "The current payment receipt number" }, "paymentMethod": { "type": "string", "description": "The method used for making the payment", "enum": [ "BANK_PAYMENT", "CARD", "APPLE_PAY", "GOOGLE_PAY", "DIRECT_DEBIT", "IMPORTED", "MANUAL_BANK_TRANSFER", "BANK_TRANSFER", "AMEX" ] }, "channelPaymentId": { "type": "string", "description": "Unique identifier for the payment in the payment provider's system" }, "channelPaymentUrl": { "type": "string", "description": "The URL generated by the payment provider to perform the payment" }, "channelReferenceId": { "type": "string", "description": "The remittance reference ID for bank payments" }, "externalData": { "type": "array", "description": "References about this payment from external platforms Adfin integrates with", "items": { "$ref": "#/components/schemas/PaymentExternalData" } }, "paymentSource": { "type": "string", "description": "How the payment was initiated.", "enum": [ "PAYMENT_LINK", "GENERIC_PAYMENT_LINK", "PAYMENT_OVER_PHONE" ] }, "cardOnFileId": { "type": "string", "format": "uuid", "description": "The ID of the card on file the payment was taken from" }, "metadata": {} }, "required": [ "amount", "channelPaymentId", "creationTime", "id", "paymentId", "paymentMethod", "paymentRequestId", "status" ] }, "PaymentExternalData": { "type": "object", "description": "References about the credit note from external platforms Adfin integrates with.", "properties": { "connectorType": { "type": "string", "description": "The name of the platform for which this data is stored for.", "enum": [ "XERO", "QUICKBOOKS", "PLATFORM" ] }, "id": { "type": "string", "description": "ID of the payment in the external platform" } } }, "PaymentLinkDetails": { "type": "object", "description": "Payment link details.", "properties": { "url": { "type": "string", "description": "The payment URL." }, "lastSeenTime": { "type": "string", "format": "date-time", "description": "The date when the payment link was seen for the last time" } } }, "PaymentRequestResponse": { "type": "object", "description": "Payment Request", "properties": { "id": { "type": "string", "description": "The internal id of the payment request" }, "paymentRequestNo": { "type": "string", "description": "The payment request number" }, "reference": { "type": "string", "description": "The payment request reference" }, "description": { "type": "string", "description": "Short description of the payment request" }, "totalAmount": { "type": "number", "description": "The payment request amount" }, "principalAmount": { "type": "number", "description": "The principal amount of the payment request, excluding fees" }, "paidAmount": { "type": "number", "description": "The total amount that is paid" }, "dueAmount": { "type": "number", "description": "The amount that is due" }, "fees": { "type": "array", "description": "The outstanding fees on this payment request", "items": { "$ref": "#/components/schemas/FeeResponse" } }, "currencyCode": { "type": "string", "description": "The currency in which the payment request is raised", "enum": [ "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" ] }, "taxRate": { "type": "number", "description": "Tax rate percentage" }, "payByDate": { "type": "string", "format": "date-time", "description": "The (optional) date until when user recommended the payer to pay" }, "creationTime": { "type": "string", "format": "date-time", "description": "The date the payment request was created" }, "distributionTime": { "type": "string", "format": "date-time", "description": "The time when the payment request was distributed to the customer" }, "lastNotificationSentTime": { "type": "string", "format": "date-time", "description": "The date the payment request was last sent to the customer" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The date the payment request was last updated" }, "paidTime": { "type": "string", "format": "date-time", "description": "The date the payment request paid" }, "paymentInitiationDate": { "type": "string", "format": "date-time", "description": "The date when payment is initiated for this payment request (only for Direct Debit)" }, "chargeDate": { "type": "string", "format": "date-time", "description": "The date on which the customer will have their account debited" }, "payoutDate": { "type": "string", "format": "date-time", "description": "The date on which the biller will get paid out for the payment" }, "status": { "type": "string", "description": "The payment request status", "enum": [ "DRAFT", "UNPAID", "OVERDUE", "SCHEDULED", "SUBMITTED", "PAID", "VOID", "SETTLED" ] }, "statusReasonCode": { "type": "string", "description": "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", "DIRECT_DEBIT_MANDATE_BANK_ACCOUNT_CHANGED" ] }, "statusReason": { "type": "string", "description": "Custom details on why the payment request is in a certain status" }, "paymentRequestSource": { "type": "string", "description": "The source of the payment request", "enum": [ "MANUAL", "SCHEDULE", "INVOICE", "EXTERNAL", "OVERPAYMENT", "GENERIC_PAYMENT_LINK", "PAYMENT_ALLOCATION", "PAYMENT_OVER_PHONE" ] }, "payments": { "type": "array", "description": "The payments made as part of this payment request", "items": { "$ref": "#/components/schemas/PaymentAllocationResponse" } }, "discounts": { "type": "array", "description": "The discounts applied to this payment request", "items": { "$ref": "#/components/schemas/DiscountDetails" } }, "paymentLink": { "$ref": "#/components/schemas/PaymentLinkDetails", "description": "The payment link associated with this request." }, "redirectUrl": { "type": "string", "description": "The (optional) redirect URL to redirect the user after they complete the payment" }, "invoices": { "type": "array", "description": "The invoices associated to this payment request", "items": { "$ref": "#/components/schemas/InvoiceDetails" } }, "customer": { "$ref": "#/components/schemas/CustomerResponse", "description": "The customer for which this payment request was created" }, "distribution": { "$ref": "#/components/schemas/DistributionDetails", "description": "The payment request distribution information" }, "associationType": { "type": "string", "description": "The payment request association type", "enum": [ "SINGLE", "ONE_TO_ONE", "PARTIAL", "BATCH" ] }, "creditControlStatus": { "type": "string", "description": "The credit control status of the payment request", "enum": [ "AT_RISK", "EXPECTED", "CONFIRMED" ] }, "workflowType": { "type": "string", "description": "The workflow type of the payment request", "enum": [ "AUTO_COLLECT", "ON_DEMAND", "NONE" ] }, "scheduleDetails": { "$ref": "#/components/schemas/ScheduleDetails", "description": "The details of the schedule associated with the payment request" }, "instalmentDetails": { "$ref": "#/components/schemas/InstalmentDetails", "description": "Instalment details" }, "customFields": { "type": "array", "description": "The list of custom fields that are applied to the payment request", "items": { "$ref": "#/components/schemas/CustomField" } }, "tags": { "type": "array", "description": "The list of tag ids that are applied to the payment request", "items": { "type": "string" } }, "createdBy": { "type": "string", "description": "The creator of the payment request" }, "applicableFees": { "type": "array", "description": "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.", "items": { "$ref": "#/components/schemas/FeeResponse" } } } }, "Person": { "type": "object", "description": "The data defining a person.", "properties": { "id": { "type": "string", "description": "The internal id of the person." }, "firstName": { "type": "string", "description": "The first name of the person." }, "lastName": { "type": "string", "description": "The last name of the person." }, "email": { "type": "string", "description": "The email of the person." }, "phoneNo": { "type": "string", "description": "The phone number of the person." }, "isPrimaryContact": { "type": "boolean", "description": "True if this person is a primary contact." }, "isIncludedInCommunications": { "type": "boolean", "description": "True if this person is included in the customers communications." }, "validForEmailCommunication": { "type": "boolean" }, "validForPhoneCommunication": { "type": "boolean" } } }, "PrAllocation": { "type": "object", "properties": { "prId": { "type": "string", "format": "uuid" }, "amount": { "type": "number" }, "currencyCode": { "type": "string", "description": "The default currency of the biller.", "enum": [ "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" ] }, "splitDetails": { "$ref": "#/components/schemas/SplitDetails" } } }, "ProductDetailsResponse": { "type": "object", "description": "The product details response.", "properties": { "id": { "type": "string", "description": "The ID of the product." }, "code": { "type": "string", "description": "The product code value." } } }, "ScheduleDetails": { "type": "object", "description": "The details about the schedule associated with a payment request", "properties": { "scheduleId": { "type": "string", "description": "The internal id of the schedule" }, "scheduleNo": { "type": "string", "description": "The schedule number" }, "type": { "type": "string", "description": "The schedule type", "enum": [ "RECURRING" ] } }, "required": [ "scheduleId", "scheduleNo" ] }, "SplitDetails": { "type": "object", "properties": { "billerAmount": { "type": "number" }, "surchargeAmount": { "type": "number" }, "fixedLateFeeAmount": { "type": "number" } } }, "TaxDetailsResponse": { "type": "object", "description": "The tax details response.", "properties": { "id": { "type": "string", "description": "The ID of the tax rate." }, "rate": { "type": "number", "description": "The actual rate value." } } }, "TrackingItemCatalogueResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The id of the tracking item catalogue entry" }, "name": { "type": "string", "description": "The name of the tracking item catalogue entry" }, "externalData": { "type": "array", "description": "The external data of the tracking item catalogue entry", "items": { "$ref": "#/components/schemas/CatalogueExternalDataRequest" } }, "items": { "type": "array", "description": "The child tracking items (options) of this category", "items": { "$ref": "#/components/schemas/TrackingItemCatalogueResponse" } } } }, "TrackingItemDetailsResponse": { "type": "object", "description": "The tracking item details response.", "properties": { "id": { "type": "string", "description": "The ID of the tracking item." }, "name": { "type": "string", "description": "The name of the tracking item." } } }, "ActivateInvoiceRequest": { "type": "object", "description": "Activate an invoice. Sends it to collection via One time payment or Direct Debit", "properties": { "collectionMethod": { "type": "string", "description": "How the payment is expected to be collected for this invoice.", "enum": [ "ONE_TIME_PAYMENT", "DIRECT_DEBIT_PAYMENT", "NONE" ] }, "customMessage": { "type": "string", "description": "An optional message that will be sent to the customer when the invoice is activated." }, "templateId": { "type": "string", "description": "The schedule template id used for sending the invoice to customer." } } }, "UpdateDistributionDetailsRequest": { "type": "object", "description": "Request for updating the distribution details for a list of payment requests", "properties": { "paymentRequestIds": { "type": "array", "description": "The IDs of the payment requests for which to update the distribution details", "items": { "type": "string" } }, "distributionDetails": { "$ref": "#/components/schemas/CollectionDetails", "description": "The new distribution details" } } }, "InstalmentPlanDetails": { "type": "object", "description": "Instalment plan details", "properties": { "cadence": { "$ref": "#/components/schemas/Cadence", "description": "The instalment cadence" } }, "required": [ "cadence" ] }, "UpdateInvoiceRequest": { "type": "object", "description": "Update an invoice.", "properties": { "invoiceNo": { "type": "string", "description": "The unique number of the invoice. Acts as an idempotency key.", "example": "INV-12345" }, "customer": { "$ref": "#/components/schemas/CustomerDetails", "description": "Change the customer for this invoice or leave it null to keep the current customer. Use the Adfin Customer Id for this", "example": "80349480-490b-4234-92e7-fad697e3d446" }, "description": { "type": "string", "description": "A short description or summary of the invoice.", "example": "Monthly subscription fee for January" }, "dueDate": { "type": "string", "format": "date-time", "description": "The due date for the invoice payment.", "example": "2025-12-15T23:59:59Z" }, "issueDate": { "type": "string", "format": "date-time", "description": "The date the invoice is issued.", "example": "2025-12-15T09:00:00Z" }, "itemsTaxType": { "type": "string", "description": "How tax is applied to line items from the invoice", "enum": [ "EXCLUSIVE", "INCLUSIVE", "NONE" ] }, "items": { "type": "array", "description": "The list of items included in this invoice.", "items": { "$ref": "#/components/schemas/UpdateLineItemRequest" } }, "instalmentPlanDetails": { "$ref": "#/components/schemas/InstalmentPlanDetails", "description": "Instalment plan details" }, "paymentRequests": { "type": "array", "description": "Details for the invoice's payment requests. Only required for invoices with multiple payment requests (ex: instalments).", "items": { "$ref": "#/components/schemas/UpdatePaymentRequestDetails" } }, "officeId": { "type": "string", "format": "uuid", "description": "The unique identifier of the office associated with this invoice.", "example": "80349480-490b-4234-92e7-fad697e3d446" } } }, "UpdateLineItemRequest": { "type": "object", "description": "Update a line item.", "properties": { "id": { "type": "string", "description": "The ID of the line item to update. To add a new item, do not include ID and it will be returned on succesful PUT request." }, "description": { "type": "string", "description": "The description of the item." }, "unitAmount": { "type": "number", "description": "The price per unit of the item." }, "quantity": { "type": "number", "description": "The quantity of items." }, "taxRate": { "type": "number", "description": "The tax rate percentage applied on the line item amount (quantity * unit amount)." }, "taxRateId": { "type": "string", "description": "Tax rate id for this line item." }, "accountCodeId": { "type": "string", "description": "Sales account id for this line item." }, "productId": { "type": "string", "description": "The base product id for this line item." }, "externalData": { "type": "array", "description": "Information about this line item captured from external systems", "items": { "$ref": "#/components/schemas/LineItemExternalData" } }, "trackingItemIds": { "type": "array", "description": "Tracking item catalogue IDs for this line item.", "items": { "type": "string", "format": "uuid" } } } }, "UpdatePaymentRequestDetails": { "type": "object", "description": "Details for the payment request", "properties": { "id": { "type": "string", "description": "The ID of the payment request to update. Not required for new payment requests.", "example": "3d6be112-2825-4ee6-8287-ea9171e20b36" }, "amount": { "type": "number", "description": "The payment request amount.", "example": 100, "minimum": 0.01 }, "payByDate": { "type": "string", "format": "date-time", "description": "The date by which the payment request should be paid", "example": "2025-03-25T11:36:55.243Z" } }, "required": [ "amount", "payByDate" ] }, "InvoiceResponse": { "type": "object", "description": "Invoice response object.", "properties": { "id": { "type": "string", "description": "The internal id of the invoice" }, "invoiceNo": { "type": "string", "description": "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.\n" }, "description": { "type": "string", "description": "Short description of the invoice" }, "totalAmount": { "type": "string", "description": "The invoice total amount. Includes tax amount, amount paid or reduced with credit notes)" }, "taxAmount": { "type": "string", "description": "The invoice tax amount." }, "dueAmount": { "type": "string", "description": "The invoice amount due (remaining to be paid)." }, "creditNotesAmount": { "type": "string", "description": "The total amount that is credited." }, "dueDate": { "type": "string", "format": "date-time", "description": "The due date of the invoice" }, "issueDate": { "type": "string", "format": "date-time", "description": "The issue date date of the invoice" }, "creationTime": { "type": "string", "format": "date-time", "description": "The date the invoice was created" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The date the invoice was last updated" }, "paidTime": { "type": "string", "format": "date-time", "description": "The date the invoice was paid" }, "status": { "type": "string", "description": "The invoice status", "enum": [ "DRAFT", "UNPAID", "OVERDUE", "SCHEDULED", "SUBMITTED", "PAID", "VOID", "SETTLED" ] }, "statusReasonCode": { "type": "string", "description": "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", "DIRECT_DEBIT_MANDATE_BANK_ACCOUNT_CHANGED" ] }, "statusReason": { "type": "string", "description": "Custom details on why the invoice is in a certain status" }, "invoiceSource": { "type": "string", "description": "The source of the invoice", "enum": [ "FILE_UPLOAD", "MANUAL", "PR", "EXTERNAL", "SCHEDULE", "PLATFORM" ] }, "customer": { "$ref": "#/components/schemas/CustomerResponse", "description": "The customer for which this invoice is created" }, "itemsTaxType": { "type": "string", "description": "How tax is applied to line items from the invoice", "enum": [ "EXCLUSIVE", "INCLUSIVE", "NONE" ] }, "instalmentPlanDetails": { "$ref": "#/components/schemas/InstalmentPlanDetails", "description": "Instalment details" }, "items": { "type": "array", "description": "The list of items from the invoice", "items": { "$ref": "#/components/schemas/LineItemResponse" } }, "paymentRequests": { "type": "array", "description": "The payment requests that were created for this invoice", "items": { "$ref": "#/components/schemas/PaymentRequestDetails" } }, "scheduleDetails": { "$ref": "#/components/schemas/ScheduleDetails", "description": "The details of the schedule associated with the invoice" }, "creditNotes": { "type": "array", "description": "The list of credit notes from the invoice", "items": { "$ref": "#/components/schemas/CreditNoteResponse" } }, "fileSource": { "type": "string", "description": "The file source of invoice", "enum": [ "NONE", "FILE_UPLOAD", "EXTERNAL", "ADFIN", "PENDING_ADFIN" ] }, "externalData": { "type": "array", "description": "References about this invoice from external platforms Adfin integrates with. Such as ID etc", "items": { "$ref": "#/components/schemas/InvoiceExternalData" } }, "creditControlStatus": { "type": "string", "description": "The credit control status of the invoice", "enum": [ "AT_RISK", "EXPECTED", "CONFIRMED" ] }, "workflowType": { "type": "string", "description": "The workflow type of the invoice", "enum": [ "AUTO_COLLECT", "ON_DEMAND", "NONE" ] }, "customFields": { "type": "array", "description": "The list of custom fields that are applied to the invoice", "items": { "$ref": "#/components/schemas/CustomField" } }, "office": { "$ref": "#/components/schemas/InvoiceOfficeResponse", "description": "The office associated with the invoice" } } }, "PaymentRequestDetails": { "type": "object", "description": "Payment Request details.", "properties": { "id": { "type": "string", "description": "The internal id of the payment request" }, "paymentRequestNo": { "type": "string", "description": "The payment request number" }, "description": { "type": "string", "description": "Short description of the payment request" }, "totalAmount": { "type": "number", "description": "The payment request amount" }, "principalAmount": { "type": "number", "description": "The principal amount of the payment request (excluding fees and discounts)" }, "paidAmount": { "type": "number", "description": "The total amount that is paid" }, "currencyCode": { "type": "string", "description": "The currency in which the payment request is raised", "enum": [ "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" ] }, "fees": { "type": "array", "description": "The active (non-waived) fees on this payment request.", "items": { "$ref": "#/components/schemas/FeeResponse" } }, "payByDate": { "type": "string", "format": "date-time", "description": "The (optional) date until when user recommended the payer to pay" }, "creationTime": { "type": "string", "format": "date-time", "description": "The date the payment request was created" }, "lastNotificationSentTime": { "type": "string", "format": "date-time", "description": "The date the payment request was last sent to the customer" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The date the payment request was last updated" }, "paidTime": { "type": "string", "format": "date-time", "description": "The date the payment request paid" }, "paymentInitiationDate": { "type": "string", "format": "date-time", "description": "The date when payment is initiated for this payment request (only for Direct Debit)" }, "chargeDate": { "type": "string", "format": "date-time", "description": "The date on which the customer will have their account debited" }, "payoutDate": { "type": "string", "format": "date-time", "description": "The date on which the biller will get paid out for the payment" }, "distributionTime": { "type": "string", "format": "date-time", "description": "The date when the payment request was distributed" }, "status": { "type": "string", "description": "The payment request status", "enum": [ "DRAFT", "UNPAID", "OVERDUE", "SCHEDULED", "SUBMITTED", "PAID", "VOID", "SETTLED" ] }, "statusReasonCode": { "type": "string", "description": "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", "DIRECT_DEBIT_MANDATE_BANK_ACCOUNT_CHANGED" ] }, "statusReason": { "type": "string", "description": "Custom details on why the payment request is in a certain status" }, "reference": { "type": "string", "description": "The payment request reference" }, "payments": { "type": "array", "description": "The payments made as part of this payment request", "items": { "$ref": "#/components/schemas/PaymentAllocationResponse" } }, "discounts": { "type": "array", "description": "The discounts applied to this payment request", "items": { "$ref": "#/components/schemas/DiscountDetails" } }, "paymentLink": { "$ref": "#/components/schemas/PaymentLinkDetails", "description": "The payment link associated with this request." }, "distribution": { "$ref": "#/components/schemas/DistributionDetails", "description": "The payment request distribution information" }, "workflowType": { "type": "string", "description": "The workflow type of the payment request", "enum": [ "AUTO_COLLECT", "ON_DEMAND", "NONE" ] }, "customFields": { "type": "array", "description": "The list of custom fields that are applied to the payment request", "items": { "$ref": "#/components/schemas/CustomField" } } } }, "VoidInvoiceRequest": { "type": "object", "properties": { "reasonCode": { "type": "string" }, "reason": { "type": "string" } } }, "UpdateCustomerRequest": { "type": "object", "description": "Details to update a customer.", "properties": { "id": { "type": "string", "description": "The Adfin id of the customer." }, "externalId": { "type": "string", "description": "The id of the customer from the platform that is integrating with Adfin." }, "name": { "type": "string", "description": "The full name of the customer." }, "people": { "type": "array", "description": "The list of people assigned to the customer.", "items": { "$ref": "#/components/schemas/Person" } }, "addresses": { "type": "array", "description": "The list of the addresses for the customer. Only 1 pe supported for now", "items": { "$ref": "#/components/schemas/Address" } }, "externalData": { "$ref": "#/components/schemas/CustomerExternalData", "description": "References about this customer from external platforms Adfin integrates with, such as ID, etc." }, "trackingItemIds": { "type": "array", "description": "The list of tracking item catalogue IDs associated with the customer.", "items": { "type": "string", "format": "uuid" } }, "officeId": { "type": "string", "format": "uuid", "description": "The office ID associated with the customer." } }, "required": [ "id" ] }, "UpdateCustomerByIdRequest": { "type": "object", "description": "Details to update a customer.", "properties": { "externalId": { "type": "string", "description": "The id of the customer from the platform that is integrating with Adfin." }, "name": { "type": "string", "description": "The full name of the customer." }, "people": { "type": "array", "description": "The list of people assigned to the customer.", "items": { "$ref": "#/components/schemas/Person" } }, "addresses": { "type": "array", "description": "The list of the addresses for the customer. Only 1 pe supported for now", "items": { "$ref": "#/components/schemas/Address" } }, "externalData": { "$ref": "#/components/schemas/CustomerExternalData", "description": "References about this customer from external platforms Adfin integrates with, such as ID, etc." }, "trackingItemIds": { "type": "array", "description": "The list of tracking item catalogue IDs associated with the customer.", "items": { "type": "string", "format": "uuid" } }, "officeId": { "type": "string", "format": "uuid", "description": "The office ID associated with the customer." }, "controlAgentId": { "type": "string", "format": "uuid", "description": "The control agent ID to associate with the customer. Null values are ignored (use the unlink endpoint to remove the association)." } } }, "CreateDirectDebitMandateRequest": { "type": "object", "description": "The request containing the redirect URL", "properties": { "redirectUrl": { "type": "string", "description": "The redirect URL to redirect the user after they sign the mandate" } } }, "DirectDebitMandateResponse": { "type": "object", "description": "Direct Debit mandate details", "properties": { "id": { "type": "string", "description": "The ID of the mandate" }, "creationTime": { "type": "string", "format": "date-time", "description": "The creation time of the mandate" }, "lastUpdateTime": { "type": "string", "format": "date-time", "description": "The last time when the mandate was updated" }, "distributionTime": { "type": "string", "format": "date-time", "description": "The time when the mandate was sent to the customer" }, "authorisationTime": { "type": "string", "format": "date-time", "description": "The time when the mandate was signed by the customer" }, "submissionTime": { "type": "string", "format": "date-time", "description": "The time when the mandate was submitted to the payment provider" }, "status": { "type": "string", "description": "The mandate status", "enum": [ "CREATED", "PENDING", "ACTIVE", "PENDING_CANCELLATION", "CANCELLED", "MIGRATING" ] }, "failureReason": { "type": "string", "description": "The reason for failing to set up the mandate" }, "statusReasonCode": { "type": "string", "description": "The reason as predefined code why the mandate is in a certain status", "enum": [ "PENDING_DD_CAPABILITY", "PENDING_ACTIVATION", "MIGRATED", "BANK_ACCOUNT_CHANGED", "INCORRECT_BANK_DETAILS", "INSTRUCTION_CANCELLED_BY_PAYER", "PAYER_DECEASED", "ACCOUNT_TRANSFERRED", "ADVANCE_NOTICE_DISPUTED", "AMOUNT_DISPUTED", "MANDATE_NOT_FOUND", "DISPUTE_TOO_EARLY", "DISPUTE_TOO_LATE", "INVALID_SORT_CODE", "INVALID_ACC_NUMBER", "ACCOUNT_CLOSED", "CANCELLED_ON_DEMAND", "REINSTATED", "MIGRATION_TIMEOUT", "DISCARDED_BY_BILLER", "ACCEPTED_ON_CREATION", "OTHER" ] }, "statusReason": { "type": "string", "description": "Reason explaining the current status of the direct debit mandate, especially useful for failure cases." }, "customer": { "$ref": "#/components/schemas/CustomerResponse", "description": "The customer details" }, "url": { "type": "string", "description": "The URL where the customer can sign the direct debit mandate." }, "redirectUrl": { "type": "string", "description": "The (optional) redirect URL to redirect the user after they sign the mandate" }, "sender": { "$ref": "#/components/schemas/SenderResponse", "description": "The sender details" }, "bankAccountNumber": { "type": "string", "description": "The mandate bank account number" }, "sortCode": { "type": "string", "description": "The mandate sort code" }, "bankAccountHolderName": { "type": "string", "description": "The mandate bank account holder name" }, "mandateContactId": { "type": "string", "description": "The ID of the person linked as the mandate contact" } } }, "SenderResponse": { "type": "object", "description": "The sender details.", "properties": { "name": { "type": "string", "description": "The registration name of the sender." } } }, "UpsertCustomerAutopilotSettingsRequest": { "type": "object", "properties": { "guidance": { "type": "string", "description": "Free-text guidance for autopilot workflow generation. Maximum 2000 characters.", "maxLength": 2000, "minLength": 0 } }, "required": [ "guidance" ] }, "CustomerAutopilotSettingsResponse": { "type": "object", "properties": { "customerId": { "type": "string", "description": "The unique identifier of the customer." }, "settings": { "$ref": "#/components/schemas/Settings", "description": "The autopilot settings, or null if not configured." } } }, "Settings": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the guidance record." }, "guidance": { "type": "string", "description": "The autopilot guidance text." }, "creationTime": { "type": "string", "format": "date-time", "description": "The time the guidance was created." }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The time the guidance was last updated." } } }, "AutoCollectSettings": { "type": "object", "description": "Auto-collect workflow settings", "properties": { "isEnabled": { "type": "boolean", "description": "Indicates whether auto-collect workflow is enabled" }, "isDefault": { "type": "boolean", "description": "Indicates whether auto-collect is the default workflow" }, "pauseCollection": { "type": "boolean", "description": "When `true`, payment collection is paused.\nWhile paused, no automatic retries or scheduled collection attempts will occur.\n", "example": true }, "resumeCollectionAt": { "type": "string", "format": "date-time", "description": "The timestamp when automatic collection should resume.\nIf `null`, collection remains paused until updated manually.\n", "example": "2025-01-15T10:00:00Z" } }, "required": [ "isDefault", "isEnabled" ] }, "CustomerWorkflowSettings": { "type": "object", "description": "Customer workflow settings", "properties": { "workflowTransitions": { "type": "array", "description": "List of workflow transition configurations, each defining a source and target workflow type", "items": { "$ref": "#/components/schemas/WorkflowTransition" } }, "autoCollect": { "$ref": "#/components/schemas/AutoCollectSettings", "description": "Auto-collect workflow settings" }, "onDemand": { "$ref": "#/components/schemas/OnDemandSettings", "description": "On-demand workflow settings" }, "customerStatement": { "$ref": "#/components/schemas/CustomerStatementSettings", "description": "Customer statement workflow settings" } }, "required": [ "autoCollect", "customerStatement", "onDemand", "workflowTransitions" ] }, "OnDemandSettings": { "type": "object", "description": "On-demand workflow settings", "properties": { "isEnabled": { "type": "boolean", "description": "Indicates whether on-demand workflow is enabled" }, "isDefault": { "type": "boolean", "description": "Indicates whether on-demand is the default workflow" } }, "required": [ "isDefault", "isEnabled" ] }, "UpsertCustomerWorkflowSettingsRequest": { "type": "object", "description": "Request for upserting customer workflow settings", "properties": { "customerIds": { "type": "array", "description": "List of customer IDs to update", "items": { "type": "string" } }, "workflowSettings": { "$ref": "#/components/schemas/CustomerWorkflowSettings", "description": "Customer workflow settings" } }, "required": [ "customerIds", "workflowSettings" ] }, "WorkflowTransition": { "type": "object", "description": "Request object for configuring automatic transitions between workflow types", "properties": { "source": { "type": "string", "description": "The current workflow type from which it is transitioning", "enum": [ "AUTO_COLLECT", "ON_DEMAND", "NONE" ] }, "target": { "type": "string", "description": "The workflow type to which it is transitioning", "enum": [ "AUTO_COLLECT", "ON_DEMAND", "NONE" ] }, "type": { "type": "string", "description": "Defines how a workflow transition is triggered", "enum": [ "AUTOMATIC", "MANUAL" ] } }, "required": [ "source", "target", "type" ] }, "CustomerWorkflowSettingsResponse": { "type": "object", "description": "Customer workflow settings", "properties": { "workflowTransitions": { "type": "array", "description": "List of workflow transition configurations, each defining a source and target workflow type", "items": { "$ref": "#/components/schemas/WorkflowTransition" } }, "autoCollect": { "$ref": "#/components/schemas/AutoCollectSettings", "description": "Auto-collect workflow settings" }, "onDemand": { "$ref": "#/components/schemas/OnDemandSettings", "description": "On-demand workflow settings" }, "customerStatement": { "$ref": "#/components/schemas/CustomerStatementSettings", "description": "Customer statement workflow settings" } }, "required": [ "autoCollect", "customerStatement", "onDemand" ] }, "PaymentSettings": { "type": "object", "description": "Customer payment settings", "properties": { "allowPartialPayments": { "type": "boolean", "description": "Indicates whether partial payments are allowed" }, "minPartialPaymentAmount": { "type": "number", "description": "The minimum amount for partial payments" }, "surchargeIsEnabled": { "type": "boolean", "description": "Indicates whether a surcharge is applied to commercial card payments" }, "lateFeesIsEnabled": { "type": "boolean", "description": "Indicates whether late fees calculation is enabled" } } }, "UpsertCustomerPaymentSettingsRequest": { "type": "object", "description": "Request for upserting customer payment settings", "properties": { "customerIds": { "type": "array", "description": "The ids of the customers for which to upsert payment settings", "items": { "type": "string", "format": "uuid" }, "uniqueItems": true }, "paymentSettings": { "$ref": "#/components/schemas/PaymentSettings" } } }, "CancelDirectDebitMandateRequest": { "type": "object", "properties": { "reason": { "type": "string", "description": "The reason for cancelling a direct debit mandate" } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "description": "The url of the webhook target.", "example": "https://hooks.example.com/adfin/webhooks" }, "events": { "type": "array", "description": "The list of events to subscribe.", "example": [ "invoice", "dd-mandate" ], "items": { "type": "string", "description": "The supported event types for webhooks subscription", "enum": [ "payment", "dd-mandate", "invoice", "biller", "customer", "payment-request" ] } }, "name": { "type": "string", "description": "The name of the webhook.", "example": "Adfin Events" }, "description": { "type": "string", "description": "The description of the webhook.", "example": "Triggers for invoice lifecycle events." }, "enabled": { "type": "boolean", "description": "The state of the webhook configuration." } }, "required": [ "events", "name", "url" ] }, "WebhookResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The identifier of the webhook" }, "clientId": { "type": "string", "description": "The identifier of the application" }, "url": { "type": "string", "description": "The target URL of the webhook" }, "name": { "type": "string", "description": "Name of the webhook" }, "description": { "type": "string", "description": "Description of the webhook" }, "events": { "type": "array", "description": "The list of event types to trigger webhook instantiation", "items": { "type": "string" } }, "enabled": { "type": "boolean", "description": "The state of the webhook" }, "creationTime": { "type": "string", "format": "date-time", "description": "The creation timestamp of the webhook" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "The last updated timestamp of the webhook" } } }, "WebhookDigestResponse": { "type": "object", "properties": { "secretKey": { "type": "string" } } }, "ApiKeyAuthentication": { "type": "object", "properties": { "headerKey": { "type": "string", "description": "The header key of the API Key used by the webhook invocations" }, "headerValue": { "type": "string", "description": "The header value of the API Key used by the webhook invocations" } } }, "BasicAuthentication": { "type": "object", "properties": { "username": { "type": "string", "description": "The username used by the webhook invocations for basic authentication" }, "password": { "type": "string", "description": "The password used by the webhook invocations for basic authentication" } } }, "WebhookAuthenticationRequest": { "type": "object", "properties": { "basicAuthentication": { "$ref": "#/components/schemas/BasicAuthentication", "description": "Basic authentication credentials used for the webhook invocations." }, "apiKeyAuthentication": { "$ref": "#/components/schemas/ApiKeyAuthentication", "description": "API Key used for the webhook invocations authentication." } } }, "CreateRecurringPaymentRequestRequest": { "type": "object", "description": "This endpoint defines how payment request are generated on a recurring basis.\nThe `cadence` field controls when new payment request are created,\nwhile `paymentRequestDetails` defines what those payment request contain.\n", "example": { "cadence": { "type": "INTERVAL", "timeUnit": "MONTHS", "frequency": 1, "startDate": "2025-01-01T00:00:00Z" }, "paymentRequestDetails": { "customer": { "id": "80349480-490b-4234-92e7-fad697e3d446" }, "paymentTerm": { "timeUnit": "DAYS", "value": 30 }, "distribution": { "collectionMethod": "AUTO_COLLECT", "templateId": "d290f1ee-6c54-4b01-90e6-d701748f0851", "customMessage": "Thank you for your business!", "approvedForSending": true }, "amount": "10.00", "taxRate": "0.1", "currencyCode": "GBP", "description": "Monthly subscription for January", "reference": "PR-01" } }, "properties": { "cadence": { "$ref": "#/components/schemas/IntervalCadence", "description": "Specifies the frequency and recurrence pattern for payment request generation.\n\nExample:\n- `INTERVAL`: Fixed interval (e.g., every 2 weeks).\n" }, "paymentRequestDetails": { "$ref": "#/components/schemas/RecurringPaymentRequestDetails", "description": "Specifies the details of payment request that will be automatically generated.\n\nContains metadata such as the customer, collection terms, amount and tax configuration.\n" } }, "required": [ "cadence", "paymentRequestDetails" ] }, "CreateRecurringInvoiceRequest": { "type": "object", "description": "This endpoint defines how invoices are generated on a recurring basis.\nThe `cadence` field controls when new invoices are created,\nwhile `invoiceDetails` defines what those invoices contain.\nA recurring invoice collected via `AUTO_COLLECT` is the direct debit schedule; there is no separate schedule object.\n", "example": { "cadence": { "type": "INTERVAL", "timeUnit": "MONTH", "frequency": 1, "startDate": "2025-01-01T00:00:00.000Z" }, "invoiceDetails": { "customer": { "id": "80349480-490b-4234-92e7-fad697e3d446" }, "paymentTerm": { "timeUnit": "DAY", "value": 30 }, "distribution": { "collectionMethod": "AUTO_COLLECT", "customMessage": "Please find your invoice attached. Thank you for your business!", "approvedForSending": true }, "description": "Monthly subscription for January", "currencyCode": "GBP", "itemsTaxType": "INCLUSIVE", "items": [ { "description": "Pro Plan Subscription", "unitAmount": 5000, "quantity": 1 } ] } }, "properties": { "cadence": { "$ref": "#/components/schemas/IntervalCadence", "description": "Specifies the frequency and recurrence pattern for invoice generation.\n\nExample:\n- `INTERVAL`: Fixed interval (e.g., every 2 weeks).\n" }, "invoiceDetails": { "$ref": "#/components/schemas/RecurringInvoiceDetails", "description": "Specifies the details of invoices that will be automatically generated.\n\nContains metadata such as the customer, collection terms, line items and tax configuration.\n" } }, "required": [ "cadence", "invoiceDetails" ] }, "ImportPaymentRequest": { "type": "object", "properties": { "invoiceId": { "type": "string", "description": "ID of the invoice to apply payment to", "example": "123e4567-e89b-12d3-a456-426614174000" }, "amount": { "type": "number", "description": "Payment amount", "example": 100.5 }, "reference": { "type": "string", "description": "Unique payment reference identifier for tracking", "example": "REF-20250104" } }, "required": [ "amount", "invoiceId", "reference" ] }, "CreatePaymentRequestRequest": { "type": "object", "description": "Create a payment request", "properties": { "customer": { "$ref": "#/components/schemas/CustomerDetails", "description": "Relates the Payment request to the customer record. Use the Adfin Customer Id for this", "example": "80349480-490b-4234-92e7-fad697e3d446" }, "description": { "type": "string", "description": "A short description or summary of the payment request.", "example": "Monthly subscription fee for January", "maxLength": 200, "minLength": 0 }, "totalAmount": { "type": "number", "description": "The payment request amount.", "example": 100, "minimum": 0.01 }, "currencyCode": { "type": "string", "description": "The payment request currency.", "enum": [ "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" }, "taxRate": { "type": "number", "description": "Optional tax rate percentage applied on the payment request amount.", "example": 20, "maximum": 100, "minimum": 0 }, "reference": { "type": "string", "description": "Optional reference for the payment request.", "example": "REF 123456", "maxLength": 22, "minLength": 0, "pattern": "^[a-zA-Z0-9 .]*$" }, "payByDate": { "type": "string", "format": "date-time", "description": "The date by which the payment request should be paid", "example": "2025-03-25T11:36:55.243Z" }, "distribution": { "$ref": "#/components/schemas/DistributionDetails", "description": "Information about how a payment request is distributed and collected." }, "redirectUrl": { "type": "string", "description": "The (optional) redirect URL to redirect the user after they complete the payment" }, "createPaymentRequest": {} }, "required": [ "createPaymentRequest", "currencyCode", "customer", "description", "totalAmount" ] }, "BulkPaymentRequestImportResponse": { "type": "object", "description": "Bulk payment request import response", "properties": { "jobId": { "type": "string", "description": "The internal id of the bulk import job" }, "type": { "type": "string", "description": "The type of the import job", "enum": [ "BULK_PAYMENT_REQUEST_IMPORT" ] }, "status": { "type": "string", "description": "The status of the import job", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "DELETED" ] }, "creationTime": { "type": "string", "format": "date-time", "description": "The creation time of the import job" }, "countsByItemStatus": { "type": "array", "description": "The count of items for each review session item status", "items": { "$ref": "#/components/schemas/ReviewSessionItemCountByStatus" } } }, "required": [ "countsByItemStatus", "creationTime", "jobId", "status", "type" ] }, "ReviewSessionItemCountByStatus": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of review session item", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "count": { "type": "integer", "format": "int32", "description": "The count of items for this status" } }, "required": [ "count", "status" ] }, "AuthorizeRequest": { "type": "object", "properties": { "clientId": { "type": "string" }, "refreshToken": { "type": "string" }, "redirectUri": { "type": "string" }, "scopes": { "type": "string" }, "state": { "type": "string" } } }, "CreateInvoiceRequest": { "type": "object", "description": "Create an invoice.", "properties": { "invoiceNo": { "type": "string", "description": "The unique number of the invoice. Acts as an idempotency key. Will be generated if not provided.", "example": "INV-12345" }, "customer": { "$ref": "#/components/schemas/CustomerDetails", "description": "Relates the invoice to the customer record. Supports Adfin Customer ID", "example": "80349480-490b-4234-92e7-fad697e3d446" }, "description": { "type": "string", "description": "A short description or summary of the invoice.", "example": "Monthly subscription fee for January" }, "amount": { "type": "number", "description": "The invoice amount." }, "dueDate": { "type": "string", "format": "date-time", "description": "The due date for the invoice payment.", "example": "2025-12-15T23:59:59.000Z" }, "issueDate": { "type": "string", "format": "date-time", "description": "The date the invoice is issued.", "example": "2025-12-15T23:59:59.000Z" }, "itemsTaxType": { "type": "string", "description": "How tax is applied to line items from the invoice", "enum": [ "EXCLUSIVE", "INCLUSIVE", "NONE" ] }, "instalmentPlanDetails": { "$ref": "#/components/schemas/InstalmentPlanDetails", "description": "Instalment plan details (only needed when creating instalments)" }, "items": { "type": "array", "description": "The list of items included in this invoice.", "items": { "$ref": "#/components/schemas/NewLineItemRequest" } }, "paymentRequests": { "type": "array", "description": "Details for the invoice's payment requests. Only required for invoices with multiple payment requests (ex: instalments).", "items": { "$ref": "#/components/schemas/CreatePaymentRequestDetails" } }, "officeId": { "type": "string", "format": "uuid", "description": "The unique identifier of the office associated with this invoice.", "example": "80349480-490b-4234-92e7-fad697e3d446" } } }, "CreatePaymentRequestDetails": { "type": "object", "description": "Details for the payment request", "properties": { "amount": { "type": "number", "description": "The payment request amount.", "example": 100, "minimum": 0.01 }, "payByDate": { "type": "string", "format": "date-time", "description": "The date by which the payment request should be paid", "example": "2025-03-25T11:36:55.243Z" } }, "required": [ "amount", "payByDate" ] }, "PreviewInvoiceInstalmentPlanRequest": { "type": "object", "properties": { "cadence": { "$ref": "#/components/schemas/Cadence" }, "totalAmount": { "type": "number", "description": "Total amount to distribute across instalments. Defaults to the invoice total if not provided." } }, "required": [ "cadence" ] }, "CreateCustomerRequest": { "type": "object", "description": "Details to create a customer.", "properties": { "name": { "type": "string", "description": "The full name of the customer.", "example": "John Doe" }, "people": { "type": "array", "description": "A list of people associated with the customer. Can include contacts, representatives, or stakeholders.", "example": [ { "name": "Jane Smith", "email": "jane.smith@example.com" } ], "items": { "$ref": "#/components/schemas/Person" } }, "addresses": { "type": "array", "description": "A list of addresses for the customer. Currently, only one address is supported.", "example": [ { "line1": "2 Catherine Pl", "city": "London", "state": "NY", "postCode": "SW1E 6HF" } ], "items": { "$ref": "#/components/schemas/Address" } }, "externalData": { "$ref": "#/components/schemas/CustomerExternalData", "description": "References or metadata about this customer from external platforms integrated with Adfin, such as IDs or other related information.", "example": { "connectorType": "QuickBooks", "id": "QB-56789", "name": "My First Customer" } }, "trackingItemIds": { "type": "array", "description": "The list of tracking item catalogue IDs associated with the customer.", "items": { "type": "string", "format": "uuid" } }, "officeId": { "type": "string", "format": "uuid", "description": "The office ID associated with the customer." } } }, "CreateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "description": "The url of the webhook target.", "example": "https://hooks.example.com/adfin/webhooks" }, "events": { "type": "array", "description": "The list of events to subscribe.", "example": [ "invoice", "dd-mandate" ], "items": { "type": "string", "description": "The supported event types for webhooks subscription", "enum": [ "payment", "dd-mandate", "invoice", "biller", "customer", "payment-request" ] } }, "name": { "type": "string", "description": "The name of the webhook.", "example": "Adfin Events" }, "description": { "type": "string", "description": "The description of the webhook.", "example": "Triggers for invoice lifecycle events." } }, "required": [ "events", "name", "url" ] }, "AddOperation": { "allOf": [ { "$ref": "#/components/schemas/JsonPatchOperation" }, { "type": "object", "properties": { "path": { "$ref": "#/components/schemas/JsonPointer", "writeOnly": true }, "value": { "$ref": "#/components/schemas/JsonNode" } } } ] }, "CopyOperation": { "allOf": [ { "$ref": "#/components/schemas/JsonPatchOperation" }, { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/JsonPointer" }, "path": { "$ref": "#/components/schemas/JsonPointer", "writeOnly": true } } } ] }, "JsonNode": {}, "JsonPatchOperation": { "discriminator": { "propertyName": "op" }, "properties": { "op": { "type": "string" } }, "required": [ "op" ] }, "JsonPointer": { "type": "object", "properties": { "empty": { "type": "boolean" } } }, "MoveOperation": { "allOf": [ { "$ref": "#/components/schemas/JsonPatchOperation" }, { "type": "object", "properties": { "from": { "$ref": "#/components/schemas/JsonPointer" }, "path": { "$ref": "#/components/schemas/JsonPointer", "writeOnly": true } } } ] }, "PatchBillerRequest": { "type": "object", "properties": { "operations": { "type": "array", "description": "Patch operations to be applied to biller", "items": { "oneOf": [ { "$ref": "#/components/schemas/AddOperation" }, { "$ref": "#/components/schemas/CopyOperation" }, { "$ref": "#/components/schemas/MoveOperation" }, { "$ref": "#/components/schemas/RemoveOperation" }, { "$ref": "#/components/schemas/ReplaceOperation" }, { "$ref": "#/components/schemas/TestOperation" } ] } } } }, "RemoveOperation": { "allOf": [ { "$ref": "#/components/schemas/JsonPatchOperation" }, { "type": "object", "properties": { "path": { "$ref": "#/components/schemas/JsonPointer", "writeOnly": true } } } ] }, "ReplaceOperation": { "allOf": [ { "$ref": "#/components/schemas/JsonPatchOperation" }, { "type": "object", "properties": { "path": { "$ref": "#/components/schemas/JsonPointer", "writeOnly": true }, "value": { "$ref": "#/components/schemas/JsonNode" } } } ] }, "TestOperation": { "allOf": [ { "$ref": "#/components/schemas/JsonPatchOperation" }, { "type": "object", "properties": { "path": { "$ref": "#/components/schemas/JsonPointer", "writeOnly": true }, "value": { "$ref": "#/components/schemas/JsonNode" } } } ] }, "Pagination": { "type": "object", "description": "Contains pagination information for a set of results", "properties": { "page": { "type": "integer", "format": "int32", "description": "The current page number One-based page index (1..N)." }, "size": { "type": "integer", "format": "int32", "description": "The size of the page, i.e., the number of elements per page." }, "totalPages": { "type": "integer", "format": "int32", "description": "The total number of pages available." }, "totalElements": { "type": "integer", "format": "int64", "description": "The total number of elements across all pages." }, "numberOfElements": { "type": "integer", "format": "int64", "description": "The number of elements in the current page." }, "sort": { "type": "string", "description": "Sorting criteria in the format: property,(asc|desc)." } } }, "PaymentRequestStatusCount": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the payment request.\n* DRAFT: The payment request does not contain contact details for the payer or it is not yet distributed.\n* UNPAID: The payment request is not yet paid.\n* OVERDUE: THe payment request is not yet paid and is past the pay by date.\n* SCHEDULED: The payment request is scheduled to collect the payment via Direct Debit.\n* SUBMITTED: The remaining due amount on the payment request is covered by submitted (but not yet confirmed) Direct debit payments.\n* PAID: The payment request payment is captured.\n* VOID: The payment request is voided.\n* SETTLED: The payment request is paid out.\n", "enum": [ "DRAFT", "UNPAID", "OVERDUE", "SCHEDULED", "SUBMITTED", "PAID", "VOID", "SETTLED" ] }, "count": { "type": "integer", "format": "int64" } } }, "PaymentRequestStatusCountResponse": { "type": "object", "properties": { "total": { "type": "integer", "format": "int64" }, "statusCounts": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRequestStatusCount" } } } }, "PaymentRequestsResponse": { "type": "object", "description": "Wrapper for a list of payment requests", "properties": { "paymentRequests": { "type": "array", "description": "List of payment requests", "items": { "$ref": "#/components/schemas/PaymentRequestResponse" } }, "count": { "$ref": "#/components/schemas/PaymentRequestStatusCountResponse", "description": "Payment request count details" }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination details" } } }, "BulkPaymentRequestImportItemResponse": { "type": "object", "description": "A bulk payment request import job item", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the import job item" }, "jobId": { "type": "string", "format": "uuid", "description": "The ID of the import job" }, "paymentRequestNo": { "type": "string", "description": "The payment request number" }, "bulkPrImportOperation": { "type": "string", "description": "The operation to perform on the import job item", "enum": [ "UPSERT", "DELETE" ] }, "status": { "type": "string", "description": "The status of the import job item", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "statusReason": { "type": "string", "description": "The reason behind the item's current status" }, "creationTime": { "type": "string", "format": "date-time", "description": "The creation time of import job item" } }, "required": [ "bulkPrImportOperation", "creationTime", "id", "jobId", "paymentRequestNo", "status", "statusReason" ] }, "BulkPaymentRequestImportItemsResponse": { "type": "object", "description": "Paginated bulk payment request import job items", "properties": { "items": { "type": "array", "description": "The bulk payment request import job items for the current page", "items": { "$ref": "#/components/schemas/BulkPaymentRequestImportItemResponse" } }, "pagination": { "$ref": "#/components/schemas/Pagination", "description": "Pagination metadata" } } }, "AppResponse": { "type": "object", "properties": { "name": { "type": "string" }, "redirectUri": { "type": "array", "items": { "type": "string" } }, "scopes": { "type": "array", "items": { "type": "string" } }, "logoFilePath": { "type": "string" } } }, "StreamingResponseBody": {}, "CustomersResponse": { "type": "object", "description": "The list of customers for the specified filter.", "properties": { "customers": { "type": "array", "description": "The list of customers for the specified filter.", "items": { "$ref": "#/components/schemas/CustomerResponse" } }, "page": { "$ref": "#/components/schemas/Pagination" }, "pagination": { "$ref": "#/components/schemas/Pagination" } } }, "DirectDebitMandatesResponse": { "type": "object", "description": "The list of direct debit mandates for the specified filter.", "properties": { "mandates": { "type": "array", "description": "The list of all direct debit mandates for the specified filter.", "items": { "$ref": "#/components/schemas/DirectDebitMandateResponse" } } } }, "CardOnFileResponse": { "type": "object", "description": "A customer's card on file", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ID of the card on file" }, "status": { "type": "string", "description": "The current status of the card on file", "enum": [ "REQUESTED", "ACTIVE", "CANCELLED", "EXPIRED" ] }, "brand": { "type": "string", "description": "The card brand, e.g. visa or mastercard" }, "lastFour": { "type": "string", "description": "The last four digits of the card" }, "holderName": { "type": "string", "description": "The name of the cardholder" }, "expiryMonth": { "type": "integer", "format": "int32", "description": "The month the card expires (1-12)" }, "expiryYear": { "type": "integer", "format": "int32", "description": "The year the card expires" }, "isBusinessCard": { "type": "boolean", "description": "Whether the card is a business card" }, "creationTime": { "type": "string", "format": "date-time", "description": "When the card was first added" } }, "required": [ "creationTime", "id", "isBusinessCard", "status" ] }, "CardsOnFileResponse": { "type": "object", "description": "The cards a customer has on file", "properties": { "cards": { "type": "array", "description": "The customer's cards on file", "items": { "$ref": "#/components/schemas/CardOnFileResponse" } } }, "required": [ "cards" ] }, "GetTaxRateCatalogueResponse": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of tax rates", "items": { "$ref": "#/components/schemas/TaxRateCatalogueResponse" } } } }, "TaxRateCatalogueResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The id of the tax rate catalogue entry" }, "name": { "type": "string", "description": "The name of the tax rate catalogue entry" }, "taxRate": { "type": "number", "description": "The tax rate. Must be a positive value in the [0,1] interval" }, "isDefault": { "type": "boolean", "description": "Boolean flag specifying if the entry is the default tax rate to be used for new line items." }, "creationTime": { "type": "string", "format": "date-time", "description": "Creation time of the entry" } } }, "GetLineItemCatalogueResponse": { "type": "object", "properties": { "items": { "type": "array", "description": "The list of line items catalogue", "items": { "$ref": "#/components/schemas/LineItemCatalogueResponse" } } } }, "LineItemCatalogueResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The id of the item" }, "code": { "type": "string", "description": "The code of the line item" }, "description": { "type": "string", "description": "The name of the line item" }, "unitAmount": { "type": "number", "description": "The line item price per unit" }, "taxDetails": { "$ref": "#/components/schemas/TaxDetailsResponse", "description": "Tax rate details for this line item." }, "accountDetails": { "$ref": "#/components/schemas/AccountDetailsResponse", "description": "Account details for this line item." }, "externalData": { "type": "array", "description": "The external data of the line item.", "items": { "$ref": "#/components/schemas/CatalogueExternalDataRequest" } }, "creationTime": { "type": "string", "format": "date-time", "description": "Creation time of element" } } }, "AccountingConnectorResponse": { "type": "object", "properties": { "type": { "type": "string", "description": "The accounting connector type", "enum": [ "XERO", "QUICKBOOKS", "PLATFORM" ] }, "status": { "type": "string", "description": "The status of the accounting connector", "enum": [ "CONNECTED", "NOT_CONNECTED", "PENDING" ] }, "externalCode": { "type": "string", "description": "The unique public facing identifier of the organisation" }, "collectionMethodSettings": { "$ref": "#/components/schemas/CollectionMethodSettings", "description": "Settings used to determine how payments are collected (e.g. on demand or auto collect)" }, "actionHints": { "$ref": "#/components/schemas/ActionHints", "description": "User-facing prompts for follow-up actions" } } }, "AccountingSettingsResponse": { "type": "object", "properties": { "connectors": { "type": "array", "description": "The list of available accounting connectors", "items": { "$ref": "#/components/schemas/AccountingConnectorResponse" } } } }, "ActionHints": { "type": "object", "properties": { "reconnectRequired": { "type": "boolean", "description": "Whether the user must re-auth/reconnect the accounting connector." }, "disconnectionWarningRequired": { "type": "boolean", "description": "Whether a disconnection warning banner should be displayed to the user." } } }, "AmountLimitResponse": { "type": "object", "properties": { "min": { "type": "string", "description": "The min amount limit" }, "max": { "type": "string", "description": "The max amount limit" }, "currencyCode": { "type": "string", "description": "The currency in which the amount limit is applied", "enum": [ "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" ] } }, "required": [ "max", "min" ] }, "BankAccountResponse": { "type": "object", "description": "The bank accounts of the biller.", "properties": { "id": { "type": "string", "description": "The unique identifier of the bank account.", "minLength": 1 }, "billerId": { "type": "string", "description": "The unique identifier of the biller.", "minLength": 1 }, "name": { "type": "string", "description": "The name of the bank account.", "maxLength": 255, "minLength": 0 }, "paymentDetails": { "$ref": "#/components/schemas/PaymentDetails", "description": "The payment details of the bank account." }, "currencyCode": { "type": "string", "description": "The currency of the bank account.", "enum": [ "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" ] }, "countryCode": { "type": "string", "description": "The default country code of the bank account.", "minLength": 1 } }, "required": [ "billerId", "countryCode", "currencyCode", "id", "name" ] }, "BillerExternalData": { "type": "object", "description": "References about the biller from external platforms Adfin integrates with.", "properties": { "connectorType": { "type": "string", "description": "The name of the platform for which this data is stored for.", "enum": [ "XERO", "QUICKBOOKS" ] }, "id": { "type": "string", "description": "The ID of the Biller in the external platform." }, "code": { "type": "string", "description": "The code of the Biller in the external platform." } }, "required": [ "connectorType", "id" ] }, "BillerResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the biller.", "minLength": 1 }, "name": { "type": "string", "description": "The legal registration name of the company.", "maxLength": 255, "minLength": 0 }, "statementName": { "type": "string", "description": "The biller statement name shown on bank and credit card statements.", "maxLength": 22, "minLength": 0 }, "directDebitStatementName": { "type": "string", "description": "The biller statement name shown on Direct Debit bank statements." }, "alias": { "type": "string", "description": "The short name of the biller.", "maxLength": 50, "minLength": 0 }, "registrationNo": { "type": "string", "description": "The registration number of the company.", "minLength": 1 }, "currencyCode": { "type": "string", "description": "The default currency of the biller.", "enum": [ "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" ] }, "countryCode": { "type": "string", "description": "The default country code of the biller.", "minLength": 1 }, "timezone": { "type": "string", "description": "The default timezone of the biller.", "minLength": 1 }, "website": { "type": "string", "description": "The website of the biller." }, "categoryCode": { "type": "string", "description": "The merchant category code (MCC) representing the business type." }, "industryCode": { "type": "string", "description": "The industry code that represents the industry of the biller." }, "legalEntityType": { "type": "string", "description": "The legal entity type of the biller.", "enum": [ "organization", "soleProprietorship" ] }, "businessType": { "type": "string", "description": "The business type of the biller.", "enum": [ "PRIVATE_COMPANY", "PUBLIC_COMPANY", "OTHER_COMPANY", "INCORPORATED_PARTNERSHIP", "UNINCORPORATED_PARTNERSHIP", "INDIVIDUAL", "NON_PROFIT" ] }, "vatRegistrationNo": { "type": "string", "description": "The VAT registration number of the biller." }, "billingEmail": { "type": "string", "description": "The email address for billing purposes." }, "emailDomain": { "type": "string", "description": "The email domain of the biller." }, "paymentDetails": { "type": "array", "description": "The list of payment details associated with the biller.", "items": { "$ref": "#/components/schemas/PaymentDetails" } }, "bankAccounts": { "type": "array", "description": "The list of bank accounts associated with the biller.", "items": { "$ref": "#/components/schemas/BankAccountResponse" } }, "locations": { "type": "array", "description": "The registered business locations of the biller.", "items": { "$ref": "#/components/schemas/Location" } }, "status": { "type": "string", "description": "The status of the biller.", "enum": [ "PENDING", "RESTRICTED", "VERIFIED", "ACTIVE", "INACTIVE", "LAPSED", "BLACKLISTED", "CLOSED" ] }, "channelBillerId": { "type": "string", "description": "The identifier of the biller associated with the payment provider." }, "paymentSettings": { "$ref": "#/components/schemas/PaymentSettingsResponse", "description": "The payment settings of the biller." }, "accountingSettings": { "$ref": "#/components/schemas/AccountingSettingsResponse", "description": "The accounting settings of the biller." }, "creationTime": { "type": "string", "format": "date-time", "description": "The date and time when the biller was created." }, "externalData": { "type": "array", "description": "References about this biller from external platforms Adfin integrates with, such as ID, etc.", "items": { "$ref": "#/components/schemas/BillerExternalData" } }, "type": { "type": "string", "description": "The type of the biller.", "enum": [ "STANDARD", "DEMO", "E2E" ] } }, "required": [ "alias", "countryCode", "currencyCode", "id", "legalEntityType", "name", "registrationNo", "statementName", "status", "timezone", "type" ] }, "CollectionMethodSetting": { "type": "object", "description": "A single setting (e.g. term or branding theme) used to define a collection method for an invoice.", "properties": { "externalId": { "type": "string", "description": "The unique identifier of the collection method setting, such as a QuickBooks invoice term or a Xero branding theme ID. This value is used to match against the corresponding configuration in the external accounting platform." }, "type": { "type": "string", "description": "The type of the setting, indicating its source or format.", "enum": [ "TERM", "BRANDING_THEME" ] } } }, "CollectionMethodSettings": { "type": "object", "description": "Settings used to determine how payments are collected (e.g. on demand or auto collect).", "properties": { "onDemand": { "type": "array", "description": "The list of settings that configure on demand payment collection.", "items": { "$ref": "#/components/schemas/CollectionMethodSetting" } }, "autoCollect": { "type": "array", "description": "The list of settings that configure auto collect payment collection.", "items": { "$ref": "#/components/schemas/CollectionMethodSetting" } } } }, "Location": { "type": "object", "description": "The location of the biller.", "properties": { "address": { "$ref": "#/components/schemas/Address", "description": "The address of a biller location." }, "person": { "$ref": "#/components/schemas/Person", "description": "The personal contact details from a biller location." } } }, "PaymentDetails": { "type": "object", "description": "The payment details of the biller.", "properties": { "bankName": { "type": "string", "description": "The name of the bank." }, "sortCode": { "type": "string", "description": "The sort code, without separators or whitespace." }, "accountNo": { "type": "string", "description": "The bank account number (without separators)." }, "accountType": { "type": "string", "description": "The account type. For example: Main Account." } } }, "PaymentMethodResponse": { "type": "object", "description": "Payment method details", "properties": { "paymentMethod": { "type": "string", "description": "The method used for making the payment", "enum": [ "BANK_PAYMENT", "CARD", "APPLE_PAY", "GOOGLE_PAY", "DIRECT_DEBIT", "IMPORTED", "MANUAL_BANK_TRANSFER", "BANK_TRANSFER", "AMEX" ] }, "enabled": { "type": "boolean", "description": "Indicates whether the payment method is enabled (true) or disabled (false)." }, "allowed": { "type": "boolean", "description": "Indicates whether receiving payments via provided payment method is allowed." }, "status": { "type": "string", "description": "The current payment method status", "enum": [ "ACTIVE", "INACTIVE" ] }, "amountLimits": { "type": "array", "description": "The amount limits", "items": { "$ref": "#/components/schemas/AmountLimitResponse" } }, "paymentServiceProvider": { "type": "string", "description": "The payment service provider handling this payment method" } }, "required": [ "allowed", "amountLimits", "enabled", "paymentMethod", "status" ] }, "PaymentSettingsResponse": { "type": "object", "description": "Payment settings response details", "properties": { "status": { "type": "string", "description": "The current status of payment settings, indicating if the payments can be processed or not.", "enum": [ "ACTIVE", "INACTIVE" ] }, "paymentMethods": { "type": "array", "description": "The list of payment methods", "items": { "$ref": "#/components/schemas/PaymentMethodResponse" } }, "entityId": { "type": "string", "description": "The internal id of the entity for whom this payment setting was created." }, "entityType": { "type": "string", "description": "Attribute that specifies the type of entity", "enum": [ "BILLER", "CUSTOMER", "INVOICE", "PAYMENT_REQUEST" ] } }, "required": [ "entityId", "entityType", "paymentMethods", "status" ] }, "WebhooksResponse": { "type": "object", "description": "The list of webhooks configured for an application.", "properties": { "webhooksResponse": { "type": "array", "description": "The list of webhooks for an application identifier.", "items": { "$ref": "#/components/schemas/WebhookResponse" } } } } }, "securitySchemes": { "Biller Access Token (Production)": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://api.adfin.com/api/oauth2/token", "scopes": {} } } }, "Platform Bearer Token": { "type": "http", "scheme": "Bearer" }, "Biller Access Token (Staging)": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://api.staging.adfin.com/api/oauth2/token", "scopes": {} } } } } } }