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/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

JSON

{
  "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

JSON

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

Sample Response

JSON

{
  "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

HTTP

GET /payment/order/direct-debit/status

Base URL:

HTTP

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

HTTP

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

Sample Response

JSON

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

---

4. Process Payment Using Direct Debit

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

Endpoint

HTTP

POST /payment/order/pay

Headers

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

Sample Request Payload

JSON

{
  "paymentOption": "DIRECT_DEBIT",
  "reference": "ORD-12345",
  "directDebitPaymentRequest": {
    "mandateCode": "MDTC-987654",
    "accountName": "John Doe",
    "bankCode": "033"
  }
}

Sample Response

JSON

{
  "message": "Payment initiated",
  "status": true,
  "data": {
    "reference": "ORD-12345",
    "status": "pending"
  }
}

---

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.