Documentation

Direct Debit

A direct debit is a financial transaction in which one person (or company) withdraws funds from another person's bank account. Formally, the person who directly draws the funds ("the payee") instructs their bank to collect (i.e., debit) an amount directly from another's ("the payer's") bank account designated by the payer and pay those funds into a bank account designated by the payee.

Direct debits can be highly useful in several scenarios, such as:

  • Regular payments: Direct debits are ideal for making regular payments like monthly utility bills, rent, or subscriptions. This ensures that payments are made on time, every time.
  • Large purchases: Direct debits can be used to pay for large purchases over time, such as a car or furniture, by breaking the cost down into manageable monthly payments.
  • Business transactions: Businesses can use direct debits to ensure steady cash flow by automating payments from customers or clients.
  • Charitable donations: Regular contributions to a favourite charity can be automated using direct debits, ensuring consistent support.

How to create a direct debit

Here's a brief overview of the necessary steps to execute a Direct Debit, which will be covered in detail in this document:

  1. Create a Mandate: The mandate is a reusable entity that can be employed each time a new payment needs to be extracted from the payee's account.
  2. Create a Payment Request: Use the directDebit as the payment method. The merchant will then use the mandateId to automatically pay this Payment Request.
  3. Execute the Payment: Carry out the payment for the Payment Request using the mandateID created in the first step. Important note: once a mandateID was created for the customer, this one can be reused to pay for any number of new Payment Requests.

Creating a Mandate

What is a ‘Mandate’?

A mandate is a form of consent given by the payer, authorising the payee to collect payments from their bank account as per agreed terms. It's crucial because it provides legal authorisation for the transaction, and safeguards the interests of both parties. It's typically used when setting up recurring payments, such as subscriptions or regular bills, allowing for automated transactions without requiring manual approval each time.

How to create it

Endpoint

POST https://api.nofrixion.com/api/v1/mandates

POST https://api-sandbox.nofrixion.com/api/v1/mandates

Request Body

For different testing scenarios in the sandbox environment, alter the IBAN to any from the list provided here. Each will produce the specific case outlined in the table.

{
    "merchantId": "{YOUR_MERCHANT_ID}", // Payee's merchant ID inside MoneyMoov
    "firstName": "John", // Payer's first name
    "lastName": "Doe", // Payer's last name
    "addressLine1": "123 John St", // Payer's address
    "postalCode": "1234-567", // Payer's postal code
    "city": "Dublin", // Payer's city
    "countryCode": "IE", // Payer's country
    "iban": "DE64100000001234400021", // Payer's bank account
    "emailAddress": "[email protected]", // Payer's email
    "currency": "EUR", // Payee's bank account currency. At the moment direct debit only accept EUR accounts
    "amount": 99.99 // Optional field. If sent, will check that this amount is present in the bank account when creating the mandate. This could be beneficial for cases where one-time mandate is gonna be used so it pre-checks this amount is available in the bank account
}

Response

{
    "id": "daebe723-589c-4f5d-6fed-08dc54b2eafc", // <- Field which is gonna be used to pay the Payment Request in next steps
    "merchantID": "2c4163a8-6c64-408a-7ef2-08db79640d79",
    "supplierName": "BankingCircleDirectDebit",
    "supplierMandateID": "cf79a6275ef0659432c5736d8fd68c74",
    "supplierBankAccountID": "9649806712cfcb9b6d9aba976a14db9e",
    "supplierCustomerID": "547c1c206dfd702779b2ad0205e37886",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "customerCountryCode": "IE",
    "customerCity": "Dublin",
    "customerEmailAddress": "[email protected]",
    "customerIban": "DE86100000001234400013",
    "isRecurring": false,
    "currency": "EUR",
    "amount": 1,
    "supplierStatus": "created",
    "status": "Unknown",
    "inserted": "2024-04-04T14:24:20.4480068+00:00",
    "lastUpdated": "2024-04-04T14:24:20.4380435+00:00"
}

Executing a Direct Debit Payment

A Direct Debit Payment is executed by first creating a Payment Request, then paying that Payment Request with the mandate.

Creating a Payment Request

A Payment Request is an object that represents the merchant's intention to get paid, similar to an invoice. It contains information such as the amount, currency, and available payment methods. A Payment Request is vital for direct debits as it indicates the merchant's intent to collect a specific amount from the customer's account. Once created, this Payment Request can be paid using the mandate, which represents the customer's pre-authorisation for the merchant to initiate direct debit transactions from their account.

Endpoint

POST https://api.nofrixion.com/api/v1/paymentrequests

POST https://api-sandbox.nofrixion.com/api/v1/paymentrequests

Request Body

{
  "merchantID": "{YOUR_MERCHANT_ID}",
  "currency": "EUR",
  "amount": "1.00",
  "paymentMethodTypes": "directDebit"
}

Response

(Response object trimmed for demo purposes)

{
    "id": "df38d4d6-1012-45a0-afe3-db80a8b76968",
    "merchantID": "2c4163a8-6c64-408a-7ef2-08db79640d79",
    "amount": 1.00,
    "currency": "EUR",
    "paymentMethodTypes": "directDebit",
    // ...
}

Paying a Payment Request with the Mandate

With the previously created Payment Request and Mandate, you can now initiate the direct debit transaction. The two most important pieces of information you need are the PaymentRequestId and the MandateId. Once you send the request by calling the following endpoint and the system will request the money from the customer's bank. It usually takes up to 5 minutes for the Payment Request to change to an Authorized status. Once it changes to Authorized, it indicates that the money will be transferred soon.

Endpoint

POST https://api.nofrixion.com/api/v1/paymentrequests/{YOUR_PAYMENT_REQUEST_ID}/directdebit?mandateID={YOUR_MANDATE_ID}

POST https://api-sandbox.nofrixion.com/api/v1/paymentrequests/{YOUR_PAYMENT_REQUEST_ID}/directdebit?mandateID={YOUR_MANDATE_ID}

Response

The response is a 200 OK status code with no content in the body.

Still have questions?

If you have any questions or issues, please do not hesitate to reach out to our support team for assistance.