Direct Debit

The Direct Debit API allows you to collect recurring payments from customer bank accounts with their authorization. Use it to fetch mandates, initiate a debit, and track the status of a debit request.

ℹ️
The payload must be encrypted using RSA PKCS#1 v1.5 before making the request.

Endpoints Overview

Endpoint	Method	Description
`/payment/order/direct-debit/history`	`GET`	Fetch customer’s existing mandates
`/payment/order/direct-debit/create`	`POST`	Initiate a new direct debit mandate
`/payment/order/direct-debit/status`	`GET`	Check the status of a mandate
`/payment/order/direct-debit/otp`	`POST`	To trigger OTP email to process payment
`/payment/order/pay`	`POST`	Process a payment using an approved mandate

1. Fetch Direct Debit History

Endpoint

GET /payment/order/direct-debit/history

Base URL:

https://payment-api-service.transactpay.ai

Query Parameter

Name	Type	Required	Description
`emailAddress`	string	✅ Yes	Email of the customer whose debit history you want to retrieve

Headers

api-key: Your public key (required for authorization)

Sample Request

GET /payment/order/direct-debit/[email protected]

Sample Response

{
  "customerName": "John Doe",
  "hasExistingDebitMandate": true,
  "directDebitMandates": [
    {
      "accountNumber": "1234567890",
      "bankName": "Example Bank",
      "directDebitId": 1234,
      "dateCreated": "2025-03-11T16:21:43.090Z",
      "bankCode": "033"
    }
  ]
}

2. Create Direct Debit Mandate

Endpoint

POST /payment/order/direct-debit/create

Base URL:

https://payment-api-service.transactpay.ai

Headers

api-key: Your public key (required for authorization)
Content-Type: application/json

Sample Request Payload

{
  "recurringPaymentId": 98765,
  "orderReference": "ORD-12345",
  "bankName": "Example Bank",
  "accountNumber": "1234567890",
  "bankCode": "033",
  "address": "123 Customer Address"
}

Sample Response

{
  "message": "Mandate created successfully",
  "code": "200",
  "status": true,
  "data": {
    "message": "Mandate created",
    "mandateCode": "MDTC-987654",
    "bankName": "Example Bank",
    "accountNumber": "1234567890",
    "amount": 5000,
    "directDebitId": 987
  }
}

⚠️
Note:
Store the mandateCode securely. You'll need it to initiate a direct debit.

3. Check Direct Debit Mandate Status

Endpoint

GET /payment/order/direct-debit/status

Base URL:

https://payment-api-service.transactpay.ai

Query Parameter

Name	Type	Required	Description
`mandateCode`	string	✅ Yes	Unique code assigned when mandate was created

Headers

api-key: Your public key (required)

Sample Request

GET /payment/order/direct-debit/status?mandateCode=MDTC-987654

Sample Response

{
  "message": "Mandate is active",
  "code": "200",
  "status": true,
  "data": {
    "mandateCode": "MDTC-987654"
  }
}

4. To trigger OTP to process payment

Use this endpoint to To trigger Email OTP to process Direct Debit payment.

Endpoint

POST /payment/order/direct-debit/otp

Headers

api-key: Your public key
Content-Type: application/json

Sample Request Payload

{
    "mandateCode": "MDTC-987654"
}

Sample Response

{
    "message": "OTP successfully sent",
    "code": "00",
    "status": true,
    "data": "OTP Successfully sent"
}

5. Process Payment Using Direct Debit

Use this endpoint to charge a customer using an approved direct debit mandate.

Endpoint

POST /payment/order/pay

Headers

api-key: Your public key
Content-Type: application/json

Sample Request Payload

{
  "paymentOption": "NDD",
  "reference": "ORD-12345",
  "directDebitPaymentRequest": {
    "otp": "123456",
    "mandateCode": "MDTC-987654",
    "accountName": "John Doe",
    "bankCode": "000001"
  }
}

Sample Response

{
    "data": {
        "paymentDetail": {
            "redirectUrl": null,
            "recipientAccount": "1305080049",
            "paymentReference": "NIPMINI/118089260303161141639081123456/123456475013",
            "cardToken": null
        },
        "bankTransferDetails": null,
        "orderPayment": {
            "orderId": 123456,
            "orderPaymentReference": "PGW-PAYREF-29509EEDD3D047D8A2EF3E56C3123456",
            "currency": "NGN",
            "statusId": 1,
            "orderPaymentResponseCode": "01",
            "orderPaymentResponseMessage": "Initiated",
            "orderPaymentInstrument": null,
            "remarks": "Order payment initiated",
            "totalAmount": 10.00,
            "fee": 0.15
        }
    },
    "status": "success",
    "statusCode": "02",
    "message": "Direct Debit order created successfully"
}

Summary

Feature	Description
Fetch Mandates	Retrieve customer’s existing direct debit setup
Create Mandate	Set up a new authorization for recurring debits
Check Status	Verify if a mandate is active before using it
Initiate Debit	Charge the customer automatically using the mandate

💬
Need help?
Contact Transactpay Support or visit the Developer Hub.