> ## 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.

# Direct Debit Mandates: Create, Activate, and Cancel

> Manage the full direct debit mandate lifecycle: create a mandate, initiate and validate bank authorization, retrieve details, and cancel when needed.

A direct debit mandate authorizes Paylink to pull funds from a customer's bank account on your behalf. The lifecycle follows a strict sequence: **create** the mandate, **initiate activation** to trigger the bank authorization flow, **validate activation** with the credentials returned by the bank, and then use the active mandate for debits. You may cancel a mandate at any time.

<Steps>
  <Step title="Create a Mandate">
    Registers a new direct debit mandate for a customer. The mandate is created in a pending state and must be activated before any debits can be processed.

    ```http theme={null}
    POST https://sandbox.lyseis-pay.com/direct-debits/mandates
    ```

    **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="customer_name" type="string" required>
      Full legal name of the customer.
    </ParamField>

    <ParamField body="customer_email" type="string" required>
      Email address of the customer.
    </ParamField>

    <ParamField body="account_number" type="string" required>
      Customer's bank account number to be debited.
    </ParamField>

    <ParamField body="bank_code" type="string" required>
      Bank code for the customer's account. Use `GET /banks` to retrieve valid codes.
    </ParamField>

    <ParamField body="start_date" type="string" required>
      The date the mandate becomes effective. Must be a future date. Format: `YYYY-MM-DD`.
    </ParamField>

    <ParamField body="end_date" type="string" required>
      The date the mandate expires. Must be at least 30 days after `start_date`. Format: `YYYY-MM-DD`.

      <Note>The mandate duration must be at least 30 days.</Note>
    </ParamField>

    <ParamField body="monthly_amount" type="number" required>
      Maximum total amount (in the lowest currency unit) that may be debited within a single calendar month.
    </ParamField>

    <ParamField body="monthly_debit_count" type="integer" required>
      Maximum number of individual debit transactions allowed per calendar month.
    </ParamField>

    **Example request**

    ```json theme={null}
    {
      "customer_name": "Ada Lovelace",
      "customer_email": "ada@example.com",
      "account_number": "0123456789",
      "bank_code": "058",
      "start_date": "2026-02-01",
      "end_date": "2027-02-01",
      "monthly_amount": 50000.00,
      "monthly_debit_count": 4
    }
    ```

    **Example response**

    ```json theme={null}
    {
      "status": "success",
      "message": "Mandate created successfully",
      "data": {
        "mandate_reference": "mandate_123",
        "status": "pending",
        "start_date": "2026-02-01",
        "end_date": "2027-02-01",
        "monthly_amount": 50000.00,
        "monthly_debit_count": 4,
        "customer_name": "Ada Lovelace",
        "customer_email": "ada@example.com",
        "account_number": "0123456789",
        "bank_code": "058",
        "created_at": "2026-01-15T10:00:00Z"
      }
    }
    ```
  </Step>

  <Step title="Initiate Activation">
    Triggers the bank authorization flow for a pending mandate. The bank returns a set of authorization parameters (such as OTP prompts or PIN challenges) that the customer must complete in the next step.

    ```http theme={null}
    POST https://sandbox.lyseis-pay.com/direct-debits/mandates/{mandate_reference}/initiate-activation
    ```

    **Path parameters**

    <ParamField path="mandate_reference" type="string" required>
      The unique reference of the mandate returned when it was created.
    </ParamField>

    **Example response**

    ```json theme={null}
    {
      "status": "success",
      "message": "Activation initiated",
      "data": {
        "mandate_reference": "mandate_123",
        "param1": "otp",
        "value1": "Enter the OTP sent to your registered phone number",
        "param2": "pin",
        "value2": "Enter your 4-digit bank PIN"
      }
    }
    ```

    Collect the values for `param1` / `param2` and their corresponding prompts from `value1` / `value2`, then present them to the customer to complete authorization.
  </Step>

  <Step title="Validate Activation">
    Submits the customer's authorization credentials to complete mandate activation. Use the `param1`, `value1`, `param2`, and `value2` keys returned by the initiate step.

    ```http theme={null}
    POST https://sandbox.lyseis-pay.com/direct-debits/mandates/{mandate_reference}/validate-activation
    ```

    **Path parameters**

    <ParamField path="mandate_reference" type="string" required>
      The unique reference of the mandate being activated.
    </ParamField>

    **Request body**

    <ParamField body="mandate_reference" type="string" required>
      Must match the `mandate_reference` path parameter.
    </ParamField>

    <ParamField body="param1" type="string" required>
      The first authorization parameter key returned by the initiate step (e.g. `"otp"`).
    </ParamField>

    <ParamField body="value1" type="string" required>
      The customer's response to the first authorization challenge (e.g. the OTP value).
    </ParamField>

    <ParamField body="param2" type="string" required>
      The second authorization parameter key returned by the initiate step (e.g. `"pin"`).
    </ParamField>

    <ParamField body="value2" type="string" required>
      The customer's response to the second authorization challenge (e.g. the PIN value).
    </ParamField>

    **Example request**

    ```json theme={null}
    {
      "mandate_reference": "mandate_123",
      "param1": "otp",
      "value1": "123456",
      "param2": "pin",
      "value2": "1234"
    }
    ```

    **Example response**

    ```json theme={null}
    {
      "status": "success",
      "message": "Mandate activated successfully",
      "data": {
        "mandate_reference": "mandate_123",
        "status": "active"
      }
    }
    ```

    <Warning>
      If you attempt to validate before calling initiate, the API returns:
      `409 Mandate activation needs to be initiated first`
    </Warning>
  </Step>

  <Step title="Get Mandate">
    Retrieves the current state of a mandate, including its status, configured limits, and customer details.

    ```http theme={null}
    GET https://sandbox.lyseis-pay.com/direct-debits/mandates/{mandate_reference}
    ```

    **Path parameters**

    <ParamField path="mandate_reference" type="string" required>
      The unique reference of the mandate to retrieve.
    </ParamField>

    **Example response**

    ```json theme={null}
    {
      "status": "success",
      "data": {
        "mandate_reference": "mandate_123",
        "status": "active",
        "start_date": "2026-02-01",
        "end_date": "2027-02-01",
        "monthly_amount": 50000.00,
        "monthly_debit_count": 4,
        "customer_name": "Ada Lovelace",
        "customer_email": "ada@example.com",
        "account_number": "0123456789",
        "bank_code": "058",
        "created_at": "2026-01-15T10:00:00Z",
        "updated_at": "2026-01-15T10:30:00Z"
      }
    }
    ```
  </Step>

  <Step title="Cancel Mandate">
    Cancels an active or pending mandate. Once cancelled, no further debits may be initiated against it.

    ```http theme={null}
    PATCH https://sandbox.lyseis-pay.com/direct-debits/mandates/{mandate_reference}/cancel
    ```

    **Path parameters**

    <ParamField path="mandate_reference" type="string" required>
      The unique reference of the mandate to cancel.
    </ParamField>

    **Example response**

    ```json theme={null}
    {
      "status": "success",
      "message": "Mandate cancelled successfully",
      "data": {
        "mandate_reference": "mandate_123",
        "status": "cancelled"
      }
    }
    ```
  </Step>
</Steps>

## Error Reference

| HTTP status | Error message                                  | Resolution                                                                                                 |
| ----------- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `409`       | Mandate is not active or authorized            | Ensure the mandate has completed the full activation flow before debiting.                                 |
| `409`       | Mandate activation needs to be initiated first | Call `POST /direct-debits/mandates/{mandate_reference}/initiate-activation` before attempting to validate. |