Direct Debit

👍

Use Case

Direct Debit is ideal for subscriptions, membership fees, rent, and any other recurring billing needs.

Prerequisites

Before you begin:

• Have a valid Transactpay account and access to your API key
• Ensure the customer has a bank account with direct debit support
• Be ready to store mandate codes securely in your database

ℹ️

Encryption

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

Step 1: Check If Customer Has an Existing Mandate

Use the GET /payment/order/direct-debit/history endpoint to check if the customer already has an active direct debit mandate.

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

✅

Note:

If a valid directDebitId is returned, skip to Step 4.

Step 2: Create a New Direct Debit Mandate

If the customer does not have an existing mandate, create one using:

POST /payment/order/direct-debit/create

Payload Example:

{
  "recurringPaymentId": 123,
  "orderReference": "ORD-456",
  "bankName": "Example Bank",
  "accountNumber": "1234567890",
  "bankCode": "033",
  "address": "123 Customer Street"
}

⚠️

Attention

You'll receive a mandateCode in the response. Save it for future charges.

Step 3: Verify Mandate Status (Optional but Recommended)

Check the status of the mandate using:

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

Confirm that the mandate is active before initiating a payment.

Step 4: Charge the Customer Using the Mandate

Once the mandate is verified, you can debit the customer directly:

POST /payment/order/pay

Payload Example:

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

This initiates the debit, and you can track the transaction using the reference.

Monitor Status and Handle Failures

• Use the Order Status or Webhook callbacks to track success or failure.

• Handle errors like:

  • Invalid bank code
  • Inactive or expired mandate
  • Insufficient funds

Best Practices

• Always log the mandate code against each customer
• Handle duplicate mandate attempts gracefully
• Use webhooks or polling to confirm payment status
• Inform the customer when their mandate is activated or canceled

Notes

• Mandates are linked to the customer's bank account
• Customers must authorize the first direct debit mandate
• Refunds are not supported through direct debit — initiate a manual refund if needed

📘

Need Help?

See API Reference → Direct Debit for full example

Contact Developer Support