Neero Baas Gateway

## Sections
• [Neero Baas Gateway](https://app.theneo.io/neero/neero-baas-gateway/neero-baas-gateway.md): The Neero Baas API is a modular banking API platform designed for fintechs, digital banks, and any organization looking to embed financial services into their applications. It provides out-of-the-box capabilities for managing customer lifecycle (onboarding, verification), cards (issuance, retrieval, freeze, termination), and will soon support additional core banking services, all through a standardized RESTful API. This API is part of a Banking-as-a-Service (BaaS) strategy that enables: Rapid integration of banking services into your business workflows; Granular control over entities (clients, cards, accounts) through well-scoped endpoints; KYC compliance , via automated document collection and session status tracking; A scalable and secure architecture , with authentication and JSON-structured responses. Operations are organized around independent business modules , allowing flexible coupling with CRM, ERP, or mobile/web frontend systems. Key Use Cases Issuing a virtual card for a newly verified customer; Creating onboarding sessions with document upload; Retrieving detailed KYC data (personal info, address, contact) for a party; Temporarily freezing a suspicious card; Securely displaying card details; Listing and filtering entities or sessions by status. The API is versioned and follows strict REST conventions (HTTP verbs, stateless design), making it easily consumable by various clients — backend Java, NodeJS, Flutter/Dart, etc. Important Terminology Card Category value Description PHYSICAL A physical card that can be used at ATMs and POS terminals. VIRTUAL A digital-only card typically used for online transactions. Virtual Card Statuses Name Description PRE_ACTIVE The status right after the card is created ACTIVE The card can accept transactions FROZEN Card cannot accept transctions but still exists TERMINATED Card has been deleted IN_TERMINATION Card is in the process of being deleted SUSPENDED Neero has internally stopped all transactions on the card. Party Capacity Code Description CAN_MANAGE_CARDS Grants the user permission to manage and configure payment cards. Party Contact Point Type Description EMAIL Contact method using an email address. PHONENUMBER Contact method using a phone number. SITEWEB Contact method via a personal or business website. SOCIALNETWORK Contact method via a social network profile or platform. Party Location Type Description DELIVERYPOINTADDRESS The address used for receiving deliveries or correspondence. DOMICILEADDRESS The residential address of the individual. PLACEOFBIRTH The address where the person was born. WORKADDRESS The individual’s current place of work address. Party Onboarding Session Status Type Description INIT Initial state of the onboarding process. WAITING_FOR_INFORMATION The process is waiting for required information to proceed. UNDER_VERIFICATION The submitted documents and data are currently being verified. REFUSED The onboarding process has been rejected. REFUSED_TIMEOUT The onboarding request was automatically rejected due to inactivity or timeout. VERIFIED The party has successfully passed the verification process. Party type Type Description ORGANISATION Represents a legal entity or business organization. This type may include company registration details, legal representatives, and official headquarters. PERSON Represents a natural person, such as an individual customer or user. This type includes personal identity details, birthdate, nationality, and residential address. Party Required document group type Type Description ALL_REQUIRED Indicates that all documents listed in the group are mandatory and must be submitted. ANY_REQUIRED Indicates that at least one document from the group can be submitted to proceed.
  • [Neero offers](https://app.theneo.io/neero/neero-baas-gateway/neero-baas-gateway/neero-offers.md): Core Offerings: Neero’s Business Solutions Financial Management Tools : Card Management: Easily create and manage Visa and Mastercard bank cards for employees and customers. Salary and Invoice Payments: Automate salary payments and invoice generation, simplifying payroll and billing processes. Money Transfers: Facilitate quick and secure money transfers within and across borders. Team Budget Management: Monitor and control team budgets with real-time tracking and reporting. Neero Gateway : International and Local Payment Methods: Accept payments from various channels, ensuring flexibility and convenience for your customers. Neero flow : Ideal for businesses that manage payments on behalf of third parties, such as marketplaces, on-demand service platforms, and crowdfunding sites. It simplifies the complexity of multi-party payments by enabling quick user onboarding, automated fund distribution, and robust compliance and security management. Instant Transfers: Diaspora companies can transfer funds instantly to recipients in Africa, enhancing operational efficiency. Security Features: Tools like dispute resolution and Katika ensure that every transaction is protected, fostering a safe environment for both businesses and consumers. Security and Trust : Building Confidence in Neero Transaction Security : Dispute Resolution : Our integrated dispute resolution system ensures that all parties have recourse in the event of transaction issues, maintaining trust. Neero Radar : This security feature monitors transactions in real-time, flagging suspicious activity to prevent fraud and unauthorized access. Compliance and Regulation : Regulatory Adherence: Neero complies with local and international financial regulations, ensuring that your business operations are always within legal frameworks. Data Protection: We prioritize data security, employing advanced encryption and storage techniques to safeguard sensitive information. Why Choose Neero Gateway ? Ease of Integration : Our API is designed for quick and seamless integration, allowing businesses to start accepting payments without significant delays. Customer Support : Neero offers 24/7 support to assist with any technical issues or queries, ensuring a smooth user experience. Incentives for Implementation : Exclusive Offers: Take advantage of discounts or bonuses when you implement Neero Gateway within the next few months. Referral Program: Earn rewards by referring other businesses to Neero, fostering a network of trusted partners. Scalability : Growth with Neero: As your business expands, Neero Gateway scales with you, offering advanced features and higher transaction limits to meet your growing needs. Continuous Improvement: Feature Updates : Stay ahead with regular updates that introduce new features and enhancements, keeping your business competitive. Feedback Mechanism : We value your input—share your experiences and suggestions to help us refine and improve our services. Community and Networking: User Community: Join our community of Neero users to exchange best practices, success stories, and innovative ideas, creating a collaborative environment for growth.
• [Getting Started](https://app.theneo.io/neero/neero-baas-gateway/getting-started.md): The Neero API is organized around REST . Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. You can use the Neero API in test mode, which doesn’t affect your live data or interact with the banking networks. The API key you use to authenticate the request determines whether the request is live mode or test mode. The Neero API doesn’t support bulk updates. You can work on only one object per request.
  • [Authentication](https://app.theneo.io/neero/neero-baas-gateway/getting-started/authentication-1.md): All API calls need to be authenticated using a secret key. You can get this secret key from your merchant dashboard or contact us to acquire one. We use Basic Authentication to pass the Secret Key. This key is passed in the user field and the password field is left empty. You can view and manage the keys in the Neero Dashboard. Test mode and live mode keys are distinguished by their prefixes. Security Reminder : Your API keys are powerful, so keep them safe. Don’t share them in public places like GitHub or in client-side code. All API requests must be made over HTTPS. Requests made over plain HTTP or without proper authentication will fail. Below is an example request on how we to use the secret key in a request. Plain text curl --location 'https://api.dev.neero.io/payment-gateway/api/v1/payment-methods' -u 'test_secret_key' --header 'Content-Type: application/json' --data-raw '{ "type":"PAYPAL", "paypalDetails":{ "email":"florianlowe@gmail.com", "countryIso":"FR" }}'
  • [Request and Responses Payloads](https://app.theneo.io/neero/neero-baas-gateway/getting-started/request-and-responses-payloads-1.md): The payloads consumed and produced by the API are strictly JSON encoded data or HTTP query parameters.
  • [Errors](https://app.theneo.io/neero/neero-baas-gateway/getting-started/errors-1.md): Neero uses standard HTTP response codes to indicate whether an API request was successful or not. Here's how they generally work: 2xx codes : These indicate that the request was successful. 4xx codes : These indicate an error due to the information provided (like a missing parameter or a failed charge). 5xx codes : These indicate a server error on Neero’s end (which are rare). Some 4xx errors, like a declined card, include an error code that provides a brief explanation of what went wrong. This can help you handle these errors programmatically. Http Status Codes Title Description Title 200 OK Everything worked as expected. 400 Bad Request The request was unacceptable, often due to missing a required parameter. 401 Unauthorized No valid API key provided. 402 Request Failed The parameters were valid but the request failed. 403 Forbidden The API key doesn’t have permissions to perform the request. 404 Not Found The requested resource doesn’t exist. 409 Conflict The request conflicts with another request (perhaps due to using the same idempotent key). 429 Too Many R equests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. 500, 502 , 503, 504 Server Errors Something went wrong on Neero’s end. (These are rare.) Response Body Error Code These error codes give more information the error and what has caused it. They have 2 components: A prefix and a number. The prefix identifies from which resource the error originates e.g From a Transaction Intent, Session etc. The number uniquely identifies the error in that resource. For example, below is a response body of Payment Type Not Found error that can be triggered from a Transaction Intent Resource. Plain text { "code": "TI-0001", "title": "Payment type not found", "detail": null, "fieldErrors": null } The field code can have the following value: code description PM-0001 Party entity could not be located in the system PM-0002 The specified party is not currently active PM-0003 The number of uploaded files exceeds the maximum allowed PM-0004 The total size of uploaded files exceeds the allowed limit PM-0005 The requested onboarding session does not exist PM-0006 The current onboarding session status does not allow this action PM-0007 The onboarding session has expired PM-0008 Document definition could not be found PM-0010 The system failed to delete the party's old document PM-0011 File type is not allowed, only PDF and image formats are supported PM-0012 The system could not read the uploaded file stream PM-0013 Some required documents are missing CM-0001 The specified card could not be found CM-0002 An error occurred while attempting to create the card CM-0003 The card needs to be recharged before proceeding CM-0004 Current Status does not permit this action CM-0005 The card view token has expired and is no longer valid CM-0006 The card still has balance and cannot be processed CM-0007 The party location information is missing GE-0001 The store entity could not be found GE-0004 The data provided in the request is invalid or incomplete
• [Webhook](https://app.theneo.io/neero/neero-baas-gateway/webhook.md): What's a webhook? A webhook is a way for one application to send real-time information to another application. Think of it like a phone call where one app tells another app, "Hey, something just happened, and here’s the details." What Does a Webhook Do? Real-Time Updates: When something significant happens in an application (like a payment being processed or a new user signing up), a webhook sends an instant update to another system. This means you don’t have to wait for the other system to check for updates; it gets them immediately. Automation: Webhooks can trigger automatic actions. For example, if a customer makes a purchase, a webhook can automatically update the inventory and send a confirmation email. Communication: It’s a way for different systems or apps to communicate with each other without needing constant manual intervention. In short, webhooks help keep different systems in sync and allow them to respond quickly to changes. Why use webhooks ? When integrating with Neero, you might want your application to receive real-time events from your Neero account so your backend systems can react appropriately. Insert line aboveInsert line belowDelete To set this up, you need to register webhook endpoints. Once registered, Neero will send real-time event data to your application's webhook endpoint whenever events occur in your Neero account. Neero uses HTTPS to deliver these events as JSON payloads containing an Event object. Insert line aboveInsert line belowDelete Receiving webhook events is especially useful for tracking asynchronous events, such as when a customer's bank confirms a payment, a charge is disputed, a recurring payment is successful, or subscription payments are collected.
  • [The webhook endpoint object](https://app.theneo.io/neero/neero-baas-gateway/webhook/the-webhook-endpoint-object.md): You can set a url in your merchant dashboard in order to receive various webhook events. Structure All webhook events have the same basic stucture. Below is an example Webhook Verification Webhooks are sent over the internet. Therefore, you need a mechanism to make sure that the webhooks you receive actually come from us. First you need to retrieve your API's Webhook Secret. Similar to the secret key, you can get this from your merchant dashboard or contact us. JSON { "id": "66b1fd478dcc6462fa3c4933", "createdAt": "2024-08-06T10:39:03.895Z", "type": "partyOnboardingSession.statusUpdated", "data": { "object": {} }, "metadata": {}, "operatorDetails": { "operatorId": 26, "merchantKey": "mk_KrBiF6VwsDqJfo6g7UEs4QeVUSg0hAClO7u72NXCz8v8BJ8kWS" }, "updatedAt": "2024-08-06T10:39:03.896Z", "webhookStatusUpdates": [ { "webhookUrl": "https://webhook-test.com/2184a8f10c8d404a2f2c2f5b7eb8c26c", "status": "SUCCESS", "createdAt": "2024-08-05T21:30:00.154Z" } ] } Here is a sample Javascript code on how to verify a webhook request Plain text const crypto = require('crypto'); function checkSignature(request) { const timeStamp = request.headers['X-TIMESTAMP']; const webhookSecret = 'get this from your server's properties'; // Replace with actual secret // Assuming 'request.body()' returns the body content as a string const bodyContent = request.body; // Replace with actual way to get request body const stringToSign = timeStamp + bodyContent; // Calculate HMAC using SHA-512 algorithm const hmac = crypto.createHmac('sha512', webhookSecret); hmac.update(stringToSign); const calculatedSignature = hmac.digest('hex'); const signatureFromRequest = request.headers['X-SIGNATURE']; return calculatedSignature === signatureFromRequest; }
• [list Nationalities](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/list-nationalities.md)
• [list Required Documents](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/list-required-documents.md)
• [create Onboarding Session](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/create-onboarding-session.md)
• [upload Documents](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/upload-documents.md)
• [submit Onboarding Session](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/submit-onboarding-session.md)
• [get Onboarding Session](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/get-onboarding-session.md)
• [get Onboarding Session Party](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/get-onboarding-session-party.md)
• [get Party Object](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/get-party-object.md)
• [get Active Party Object](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/get-active-party-object.md)
• [list Onboarding Session Party](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/list-onboarding-session-party.md)
• [list Party](https://app.theneo.io/neero/neero-baas-gateway/parties-controller/list-party.md)
• [card issuing](https://app.theneo.io/neero/neero-baas-gateway/card-controller.md): The card-controller section provides functionality for managing card-related actions within the system. Users can freeze, view details, terminate, and perform other operations on cards through this section. It serves as a central hub for handling card-related tasks efficiently.
  • [Card Online Transactions Webhook](https://app.theneo.io/neero/neero-baas-gateway/card-controller/card-online-transactions-webhook.md): You will be notified of all online transactions on your user's card through the webhook you have configured.
  • [freeze Card](https://app.theneo.io/neero/neero-baas-gateway/card-controller/freeze-card.md)
  • [Create Virtual Card](https://app.theneo.io/neero/neero-baas-gateway/card-controller/create-virtual-card.md)
  • [get View Details Link](https://app.theneo.io/neero/neero-baas-gateway/card-controller/get-view-details-link.md)
  • [get Saved View Card Details](https://app.theneo.io/neero/neero-baas-gateway/card-controller/get-saved-view-card-details.md)
  • [terminate Card](https://app.theneo.io/neero/neero-baas-gateway/card-controller/terminate-card.md)