> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lyseis-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Initiate, Disburse, and Track Direct Debit Payments

> Pull funds from an active direct debit mandate, disburse collected funds, and track debit status in real time via polling or webhook events.

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.

<Warning>
  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`.
</Warning>

***

## Debit a mandate

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

```http theme={null}
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

<ParamField body="mandate_reference" type="string" required>
  The unique reference of the active mandate to debit against.
</ParamField>

<ParamField body="debit_amount" type="number" required>
  Amount to debit. Must not exceed the mandate's `monthly_amount` remaining limit for the current month.
</ParamField>

<ParamField body="narration" type="string" required>
  A human-readable description of this debit that will appear on the customer's bank statement.
</ParamField>

<ParamField body="customer_email" type="string" required>
  Email address of the customer being debited. Must match the email on the mandate.
</ParamField>

<ParamField body="payment_reference" type="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.
</ParamField>

### Example request

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

### Example response

```json theme={null}
{
  "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.

```http theme={null}
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.

```http theme={null}
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

<ParamField path="payment_reference" type="string" required>
  The unique payment reference assigned when the debit was initiated.
</ParamField>

### Example response

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/api-reference/direct-debits/mandates). |