Initiate, Disburse, and Track Direct Debit Payments

Once a mandate is active, you can initiate individual debit transactions against it up to the mandate’s configured monthly limits. Each debit is identified by a unique payment_reference. Use the status endpoint or listen for webhook events to track the outcome of each debit.

The mandate must be fully activated before you attempt a debit. Attempting to debit a non-active mandate returns 409 Mandate is not active or authorized.

Debit a mandate

Pulls a specified amount from the customer’s bank account linked to an active mandate.

POST https://sandbox.lyseis-pay.com/direct-debits/debit

Headers

Header	Value
`X-Key-Id`	Your merchant key ID
`X-Timestamp`	Unix timestamp of the request
`X-Signature`	HMAC request signature
`Content-Type`	`application/json`

Request body

string

required

The unique reference of the active mandate to debit against.

number

required

Amount to debit. Must not exceed the mandate’s monthly_amount remaining limit for the current month.

string

required

A human-readable description of this debit that will appear on the customer’s bank statement.

string

required

Email address of the customer being debited. Must match the email on the mandate.

string

required

A unique reference you assign to this specific debit transaction. Used to query status and to identify the transaction in webhook payloads. Must be unique per debit.

Example request

{
  "mandate_reference": "mandate_123",
  "debit_amount": 1500.00,
  "narration": "Monthly subscription",
  "customer_email": "ada@example.com",
  "payment_reference": "subscription_2026_09"
}

Example response

{
  "status": "success",
  "message": "Debit initiated successfully",
  "data": {
    "payment_reference": "subscription_2026_09",
    "mandate_reference": "mandate_123",
    "debit_amount": 1500.00,
    "narration": "Monthly subscription",
    "status": "processing"
  }
}

Disburse collected funds

After funds are collected via a debit, use this endpoint to disburse them from your settlement balance to an external bank account.

POST https://sandbox.lyseis-pay.com/direct-debits/disburse

Headers

Header	Value
`X-Key-Id`	Your merchant key ID
`X-Timestamp`	Unix timestamp of the request
`X-Signature`	HMAC request signature
`Content-Type`	`application/json`

Get debit status

Returns the current processing status of a direct debit transaction.

GET https://sandbox.lyseis-pay.com/direct-debits/status/{payment_reference}

Headers

Header	Value
`X-Key-Id`	Your merchant key ID
`X-Timestamp`	Unix timestamp of the request
`X-Signature`	HMAC request signature

Path parameters

string

required

The unique payment reference assigned when the debit was initiated.

Example response

{
  "status": "success",
  "data": {
    "payment_reference": "subscription_2026_09",
    "mandate_reference": "mandate_123",
    "debit_amount": 1500.00,
    "narration": "Monthly subscription",
    "status": "success",
    "created_at": "2026-09-01T08:00:00Z",
    "updated_at": "2026-09-01T08:02:15Z"
  }
}

Webhook events

Paylink sends a webhook to your configured URL when a direct debit transaction or mandate reaches a terminal state.

Event	Description
`direct_debit_success`	The debit was processed and funds were successfully collected from the customer’s account.
`direct_debit_failure`	The debit was rejected by the bank or failed during processing. No funds were collected.
`mandate_activated`	A mandate has completed the activation flow and is now ready to accept debits.

Example webhook payload

{
  "event_type": "direct_debit_success",
  "status": "success",
  "message": "Direct debit transaction completed",
  "event_id": "evt_abc123xyz",
  "timestamp": "2026-09-01T08:02:15Z",
  "data": {
    "payment_reference": "subscription_2026_09",
    "mandate_reference": "mandate_123",
    "debit_amount": 1500.00,
    "status": "success"
  }
}

Error reference

HTTP status	Error message	Resolution
`409`	Mandate is not active or authorized	Complete the mandate activation flow before initiating a debit. See Mandates.

Payments

Virtual Accounts

Direct Debits

Refunds

Transfers

Banks

Initiate, Disburse, and Track Direct Debit Payments

Debit a mandate

Request body

Example request

Example response

Disburse collected funds

Get debit status

Path parameters

Example response

Webhook events

Example webhook payload

Error reference

​Debit a mandate

​Request body

​Example request

​Example response

​Disburse collected funds

​Get debit status

​Path parameters

​Example response

​Webhook events

​Example webhook payload

​Error reference

Debit a mandate

Request body

Example request

Example response

Disburse collected funds

Get debit status

Path parameters

Example response

Webhook events

Example webhook payload

Error reference