Using payment requests

Resources at a glance

Field	Description
id	Immutable ID of the payment request
paymentRequestNo	Human-readable number
totalAmount / currencycode	Declare the total amount and currency (GBP only supported)
status	See the guide below on all payment request statuses.
workflowType	On demand (card) or Auto Collect
Distribution	How the payment link is used or completed
associationType	How are they related to invoices or payment requests
paymentLink.url	A hosted page where the payment can be completed
redirectURI	Where to send the user after the user has completed the payment

Create a draft payment request

Endpoint: POST /payment_requests

Example request for creating a payment, for full details see the API docs: docs.adfin.com. Payment requests must be created against a customer, so you must have completed the create customer step.

{
  "customer": {
    "id": "123"
  },
  "currencyCode": "GBP",
  "distribution": {
    "collectionMethod": "ONE_TIME_PAYMENT",
    "customMessage": "Payment for ACME services",
    "templateId": "123"
  },
  "description": "Payment for ACME service",
  "totalAmount": 100,
    "payByDate": "2025-03-25T11:36:55.243Z"
}

This will return the following important information (sample)

ID of the payment request
payment link to use with the user

{
    "id": "36c7b2d4-a8f5-43e2-84b1-e9774f187f23",
    "paymentRequestNo": "PR-98",
		"paymentLink": {
        "url": "https://app.staging.adfin.com/pay/o5J7Id8DSNm4E4EsSJ"
    },

Optional: Activate the payment request

Endpoint: PUT payment_requests/[id]:activate

Used to activate the payment request. This will trigger any workflows associated with this, including distribution (via email, WhatsApp, etc).

This will activate the workflow defined in the distribution.templateId

Share or embed the link

Redirect the payer from your UI.
Paste into email, chat, or a PDF.

Payment Request Lifecycle

DRAFT: The payment request does not contain contact details for the payer, or it has not yet been distributed.
REQUESTED: The payment request has not yet been paid.
SCHEDULED: The payment request is scheduled to collect the payment via Direct Debit.
SUBMITTED: The remaining due amount on the payment request is covered by submitted (but not yet confirmed) Direct debit payments.
PAID: The payment request is captured.
CANCELLED: The payment request is cancelled.
SETTLED: The payment request is paid out.

Best practices

Always set a redirectUrl so the payer lands back in your platform after completing the payment.
Display amount & description before redirecting—conversion rates improve when payers know the cost.
Monitor lastSeenTime and trigger follow-up emails after 48 hours of inactivity.
Subscribe to payment_request. Paid to mark invoices paid and release goods or services instantly.