What is Direct Debit?
Direct debit is a process by which you can automatically trigger payments from an enrolled bank account without a debit card or having the account owner do a transfer.
Consent to debit accounts is granted through a contract called a Mandate.

The Neocollect API enables you to:

• Discover your clients' bank accounts with various banks

• Setup and manage paper or electronic direct debit mandates

• Directly Debit your customer's bank accounts at variable or scheduled intervals

The Process

To charge your customers' bank accounts you have do the following:

• Add them as a customer using the Create Customer endpoint.

• (Optional) Call the Account Number Discovery endpoint to discover all their bank accounts if you want to create a global mandate. This step isn't required if you already know the account(s) you wish to debit. A good use case for account discovery is lending.

• Create one or more mandates on the accounts you want to debit using the Create Mandate endpoint.

• Debit the customers account(s) using the Charge Mandate endpoint

Using The API

✋🏾Before you begin!
You should create a free Neocollect account that you can test the API against. We will provide you with test keys that you can use to make API calls.

Authentication

Requests to the Neocollect api are authenticated with session tokens. Every request you make to the api must include a session token passed in an X-Auth-Token header. To get your session token, you should call the Get Token endpoint with your assigned secret key and key id. You are encouraged to persist this token using a secret manager or KV store.

⚠️ KEYS MUST BE KEPT SECRET AT ALL TIMES ⚠️
Please note that your key-id, secret-key and any auth tokens generated by them must be kept secret at all times. We strongly advise that you do not store these keyes in plain text.

Authorization

Permissions-Based Access Control (PBAC) is used to manage access to resources. Features not included in the API resources list can only be accessed through your dashboard.

Error Handling

Errors from this api will either be in the form of a 500 - Our fault, or 4** - your fault. 4** errors will usually provide more context about the error in the message field of the response object. If the message field contains the string "field errors" then you may parse the "data" field of the response object to get even more detail about which specific field in your request object was invalid.

{
    "message": "field errors",
    "data": {
        "first_name": "Customer's first name is required",
        "email": "This email address already belongs to an existing user"
    }
}

Customers

A customer is an individual with one or more bank accounts which you want to be able to collect direct payments from. Customer's must have a bvn and must provide consent before you can succesfuly create mandates for them.

Adding Customers

The first step to charging users with NeoCollect is to profile them on our service. You can do this easily using the Create Customer endpoint. After succesfully adding a customer, you will be able to do an Account Number Discovery or Create Mandates for later debit.

You can view all added customers using the List Customers endpoint or a specific customer using the Get Customer endpoint.

You only need to add a customer once. There is no limit to the number of mandates you can create per customer.

Account Number Discovery

Account discovery is a process that allows you to view a list of all bank accounts you customer has as long as you know their BVN and have their consent.

Your customers must complete an authorization flow before this information can be provided to you. To begin, simply call the Account Discovery endpoint. The endpoint will return a url which you can pass to your customer through your application or by email. The link allows the customer to complete a 2FA process which confirms that they have given you authority to view their account numbers.

Once they complete the process their account numbers will now be visible from the dashboard or in the bank_accounts field of the Get Customer response. You can now initiate electronic or paper mandate creation on one or all of the customer's bank accounts.

Mandates

A mandate represents the authority a customer has given you to debit their account(s). Mandates can be authorized electronically (by transfer) or manually (by signature).

Mandate Lifecycle

Mandates go through three stages:

• Initiation by you. This is when you create the mandate for the customer to authorize.

• Authentication by the customer: Customers can authorize mandates in two ways

  • Electronically: by doing a transfer of N50.00 from the account they want to give you authority to debit. This instantly authorizes the mandate and you can begin to debit the account within a few hours.

  • Manually: by signing a paper mandate and uploading a picture of the signed mandate to our system (this can be done by api or through our dashboard by you)

• Authorization by the client's bank:

  • Instant for electronic mandates.

  • For paper mandates: we immedaitely share the mandate with your customer's bank to verify the signature. If the bank takes more than three days to respond, the mandate is aoutomatically approved. When this happens, we send you a webhook notification.

Direct Debit

Charging a Mandate

You can charge a mandate in two ways:

• Direct Charge:
  Use the Charge Mandate endpoint via the dashboard or API to directly debit a customer's account.

• Schedules:
  Automate your mandate charges by creating schedules. Using the Update Mandate endpoint, you can set up and configure charge schedules. Note that mandates can only be charged within the Start Date and End Date of the selected mandate.

Key Details to Note:

• Single Charge Limit:
  Each mandate charge is capped at the Amount specified when the mandate was created. This amount represents the maximum that can be deducted in a single charge, not the total deductible amount. You can process charges for variable amounts and intervals, as long as they remain within the mandate’s validity period and the set limit.

• Fraud Prevention:
  To safeguard against fraud, any amount debited via direct debit remains in the organization's account and cannot be withdrawn for 24 hours.