{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"bed859a9-147b-4c37-b097-a8223b10f20b","name":"NeoCollect API","description":"> **What is Direct Debit?**  \nDirect 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.  \nConsent to debit accounts is granted through a contract called a _Mandate._ \n  \n\nThe Neocollect API enables you to:\n\n- Discover your clients' bank accounts with various banks\n    \n- Setup and manage paper or electronic direct debit mandates\n    \n- Directly Debit your customer's bank accounts at variable or scheduled intervals\n    \n\n### The Process\n\nTo charge your customers' bank accounts you have do the following:\n\n1. Add them as a customer using the **Create Customer** endpoint.\n    \n2. _(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.\n    \n3. Create one or more mandates on the accounts you want to debit using the **Create Mandate** endpoint.\n    \n4. Debit the customers account(s) using the **Charge Mandate** endpoint\n    \n\n# Using The API\n\n> **✋🏾Before you begin!**  \nYou should [create a free Neocollect account](https://app.neocollect.ng/auth/sign-up) that you can test the API against. We will provide you with test keys that you can use to make API calls. \n  \n\n### Authentication\n\nRequests 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](https://go.postman.co/workspace/95ae6f86-ca78-4e11-bd69-c77578030e76/documentation/14568179-bed859a9-147b-4c37-b097-a8223b10f20b?entity=request-0dfa380a-5dcb-49db-bb0a-9868860d5978) endpoint with your assigned secret key and key id. You are encouraged to persist this token using a secret manager or KV store.\n\n> ⚠️ **KEYS MUST BE KEPT SECRET AT ALL TIMES** ⚠️  \nPlease 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. \n  \n\n### Authorization\n\nPermissions-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.\n\n### Error Handling\n\nErrors 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.\n\n``` json\n{\n    \"message\": \"field errors\",\n    \"data\": {\n        \"first_name\": \"Customer's first name is required\",\n        \"email\": \"This email address already belongs to an existing user\"\n    }\n}\n\n ```\n\n# Customers\n\nA 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.\n\n### Adding Customers\n\nThe 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.\n\nYou can view all added customers using the **List Customers** endpoint or a specific customer using the **Get Customer** endpoint.\n\nYou only need to add a customer once. There is no limit to the number of mandates you can create per customer.\n\n# Account Number Discovery\n\nAccount 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.\n\nYour 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.\n\nOnce 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.\n\n# Mandates\n\nA 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).\n\n|  | **Electronic** | Paper |\n| --- | --- | --- |\n| **Processing Time** | Instant | Up to 3 days |\n| **Authorization** | Customer does a transfer of N50 from the account in question to a designated account. This confirms ownership of the account. | Customer must sign a paper instruction which should be uploaded to our servers using the **Sign Mandate** endpoint. |\n| **Global Authorization**  <br>(This is when a user only authorizes once and a global mandate is setup across **all** their bank accounts.) | Not Possible, the user will have to authorize each account individually. | **Available**  <br>Users can sign a single mandate and grant consent to debit all their accounts. |\n\n## Mandate Lifecycle\n\nMandates go through three stages:\n\n1. Initiation by you. This is when you create the mandate for the customer to authorize.\n    \n2. Authentication by the customer: Customers can authorize mandates in two ways\n    \n    1. **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.\n        \n    2. **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)\n        \n3. Authorization by the client's bank:\n    \n    1. Instant for electronic mandates.\n        \n    2. 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.\n        \n\n# Direct Debit\n\n### Charging a Mandate\n\nYou can charge a mandate in two ways:\n\n1. **Direct Charge:**  \n    Use the **Charge Mandate** endpoint via the dashboard or API to directly debit a customer's account.\n    \n2. **Schedules:**  \n    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.\n    \n\n### Key Details to Note:\n\n- **Single Charge Limit:**  \n    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.\n    \n- **Fraud Prevention:**  \n    To safeguard against fraud, any amount debited via direct debit remains in the organization's account and cannot be withdrawn for 24 hours.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"14568179","team":3382659,"collectionId":"bed859a9-147b-4c37-b097-a8223b10f20b","publishedId":"2sAYBUEYRp","public":true,"publicUrl":"https://documenter-api.postman.tech/view/14568179/2sAYBUEYRp","privateUrl":"https://go.postman.co/documentation/14568179-bed859a9-147b-4c37-b097-a8223b10f20b","customColor":{"top-bar":"EAF3F9","right-sidebar":"C2E7FD","highlight":"5D87FF"},"documentationLayout":"classic-single-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"dark","themes":[{"name":"dark","logo":"https://content.pstmn.io/4b1502e5-e438-4d48-8593-0f8d162faf7f/TmVvQ29sbGVjdC1Mb2dvLnBuZw==","colors":{"top-bar":"C2E7FD","right-sidebar":"5D87FF","highlight":"F24C00"}},{"name":"light","logo":"https://content.pstmn.io/4b1502e5-e438-4d48-8593-0f8d162faf7f/TmVvQ29sbGVjdC1Mb2dvLnBuZw==","colors":{"top-bar":"EAF3F9","right-sidebar":"C2E7FD","highlight":"5D87FF"}}]}},"version":"8.11.6","publishDate":"2024-11-27T10:56:11.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":"https://content.pstmn.io/4b1502e5-e438-4d48-8593-0f8d162faf7f/TmVvQ29sbGVjdC1Mb2dvLnBuZw==","logoDark":"https://content.pstmn.io/4b1502e5-e438-4d48-8593-0f8d162faf7f/TmVvQ29sbGVjdC1Mb2dvLnBuZw=="}},"statusCode":200},"environments":[],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/55807f4a9b3b2a20c0f0cdaafd8f4797154780bd369e9ccdf47bcfd332e81701","favicon":""},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"}],"canonicalUrl":"https://documenter.gw.postman.com/view/metadata/2sAYBUEYRp"}