The Scion BaaS API (SFAPI) is fully RESTful API set. Our API uses standard HTTP response codes, authentication, and verbs, and delivers JSON responses for all calls.
\nScion is the fintech extension of Medici Bank, an API designed to build on the bank’s core strengths while enabling new digital innovation. In this documentation, references to MB are shorthand for Medici Bank.
\nThe SFAPI allows clients to:
\nCreate & Manage Customers
\nCreate & Manage Customer Accounts and Balances
\nView Customer Account Transactions
\nInstantaneously Transfer Between Client-owned Accounts
\nGet Realtime Notifications on all Customer or Account Activity
\nLet's get started...
\nIn order to use our API, you will need to sign up for a Scion Client API Account. Please contact us for more information.
\nOnce you have your API keys, you can begin testing immediately. All keys are initially created in our Staging STAG environment. After you have finished testing and are satisfied with your integration, you can request keys for our Production PROD environment.
Next, we will take a look at how to authenticate your API calls...
\nAccess to our sandbox is for potential partners and clients. If you would like to have access to our API, please contact our Operations department operations@scionfi.com
\nThe MBAPI uses three main forms of credential verification for secure authentication.
\nAPI Keys
\nHMAC Signatures
\nWhen you sign up for an account, you will be granted your own unique set of API credentials. The two main credentials you will need is the API Key MBAPI-KEY and the API Secret MBAPI-SECRET.
Your API Key (MBAPI-KEY) is public and should be passed along within your API call headers. Your API Secret (MBAPI-SECRET) is private and should not be passed along (or exposed) in any public setting. Failure to do so can allow for a hacker to create API requests on your behalf. Your account will be suspended if a breach or unexpected activity is detected on your account.
In order to secure each request, we enforce that each call be sent as a Hash-based Message Authentication Code or HMAC Signature. For more on how to construct the HMAC signature, go to Making Requests section.
\nAuthorization: Bearer MBAPI-AUTHTOKEN\n\nNext, we will look at the API Methods we allow...
\nAll requests are regulated to the following API Methods. Any method used outside of these will be rejected by the API with a 403 Forbidden status code.
Method | Usage |
GET | Requests that retrieve information concerning a data representation. |
POST | Requests that create a new data representation. Information can be passed back based on the type of request. |
PUT | Requests that update partial information of a current data representation. |
DELETE | Requests that remove (or archive) a data representation. |
Next, we will take a look at all the statuses the API will respond with, including successful and unsuccessful (error) responses...
\nBelow is a full list of possible status codes. In the case of an error code, we will respond with additional information if more details about an error is provided.
\nThese are codes that mean that your API request was correct and without errors. Some calls are Idempotent. For more information on what means, visit the
\n\nsection.
\nCode | Reason | Description |
2xx | Successful | \"Your request was right!\" |
200 | OK | \"The call was successful\" |
201 | Created | \"The resource was created\" |
202 | Accepted | \"The resource was updated successfully\" |
204 | No Content | \"The resource was deleted successfully\" |
Code | Reason | Description |
4xx | Client Error | \"Your request is wrong!\" |
400 | Bad Request | \"Your syntax is incorrect\" |
401 | Unauthorized | \"You have wrong API credentials\" |
403 | Forbidden | \"Your credentials don't have the permissions to allow this request\" |
404 | Not Found | \"The resources/endpoint is invalid\" |
405 | Method Not Allowed | \"Content-type method is not allowed\" |
429 | Too Many Requests | \"Rate limit reached for this request\" |
Code | Reason | Description |
5xx | Server Error | \"We are wrong!\" |
500 | Internal Server Error | \"Server error on our side\" |
502 | Bad Gateway | \"Invalid response from the server\" |
503 | Service Unavailable | \"An internal service is unavailable\" |
504 | Gateway Time-out | \"The request took too long to process on the server\" |
To secure all requests, we require all requests to include a specific set of HEADERS.
\nMBAPI-KEY | Your unique PUBLIC API key |
MBAPI-TIMESTAMP | The user generated timestamp for the request. Must be number of seconds since Unix Epoch |
MBAPI-SIGNATURE | The user generated message signature. The MBAPI-SIGNATURE header is generated by creating a SHA512 HMAC message digest with base64 encoding, using your MBAPI-SECRET as the secret key. See below for an example of how to construct the HMAC signed request |
MBAPI-NONCE | A unique string that identifies this request and prevents the replaying of a past request. Please see below on how to construct this nonce |
Please note: For POST requests, you should JSON.stringify the body to avoid a mismatch in formatting for the signed request.
\n\n\nIn cryptography, an HMAC (sometimes expanded as either keyed-hash message authentication code or hash-based message authentication code) is a specific type of message authentication code (MAC) involving a cryptographic hash function and a secret cryptographic key.
\n
In regular terms, HMAC is the process of using a key, in this case, your MBAPI-SECRET, and encrypting a concatenated string version of your entire API request. By encrypting the entire request, we can not only hide the contents of that request, but we can also ensure that all information can only be decrypted by those who have key permissions to do so.
\nSigning your API request is straightforward.
Below is an example of how to do so:
Node.js Example
var hash = crypto.createHmac(‘sha512’, {Your MBAPI SECRET}); // your MBAPI-SECRET e.g. “dONgcyGwBVupn/U2y8AdONGWkjfGomJqiKXk2BYaK4sd”\nhash.update(\"Your MBAPI Key\"); // your MBAPI-KEY e.g. \"1234567-ABCD-234RT-98yuT-8YHTjkUtf8klJF9m\"\nhash.update(\"API Request Method\"); // e.g. GET\nhash.update(\"API Path/URL\"); // encoded API request URL e.g. \"https://api.mb.io/dev/transfers\"\nhash.update(\"Unix Timestamp\"); // e.g. \"1574184580246\"\nhash.update(\"JSON.stringify(API Request Body)\"); // your request body\nvar hmacSignedRequest = hash.digest('base64');\n\nA Nonce is a number or string, that can be used only once. The reason for using a nonce in API requests, is to ensure that once a request has been sent, regardless of whether that request is successful, it still cannot be used (or resent) again. This guards against Replay Attacks and some Man-in-the-Middle Attacks.
\nThere are a number of ways to create a nonce. However, we ask that you create this nonce in a specific way. The MBAPI-NONCE should be constructed using your MBAPI-KEY + MBAPI-TIMESTAMP + A random 32-character string. Then taking that string and creating a base64_encoded hash. Very similar to the process of creating your HMAC signed request.
Below is an example of how to do so:
Node.js Example
var hash = crypto.createHash(‘sha512’);\nhash.update(\"Your MBAPI-KEY\");\nhash.update(\"Your MBAPI-TIMESTAMP\");\nhash.update(\"Your Random 32 Character String\");\nvar MBAPI-NONCE = hash.digest('base64');\n\n\n\nHTTPS Only!
\n
Below are a list of standards that we enforce for our data structures.
\nContent-type: application/json\n\nAny content request (even if valid) that is not application/json will return a 400 Bad Request HTTP status code with errorMessage: \"Invalid request headers\"
All timestamps are returned in ISO 8601 format:
\nYYYY-MM-DDTHH:MM:SSZ\n\nAn Idempotent Request is a request that may change the state of the resource once, but will not continue to change if that identical request is sent again.
\nFor example, a PUT request will update some (or all) of the information on a resource, based on what is being asked to be changed. But once the resource has been changed, sending in another request, that is identical to the first request, will not result in anything changing. Because no new information was changed.
This is the same for DELETE requests. Once a resource is deleted, it can not be re-deleted.
Response 200 (application/json)
\n{\n \"total\":2,\n \"data\": [\n {\"field\":\"value1\"},\n {\"field\":\"value2\"}\n ],\n \"url\":\"the URL used in the API call\",\n \"status\":\"The HTTP Status Code\",\n \"timestamp\":\"the timestamp of the API call\",\n \"links\": {\n \"first\":\"link to the first available paginated resource\",\n \"next\":\"link to next available paginated resource\",\n \"prev\":\"link to previously available paginated resource\",\n \"last\":\"link to the last available paginated resource\"\n }\n}\n\nResponse 200 (application/json)
\n{\n \"data\": {\n \"field\":\"value\" \n },\n \"url\":\"the URL used in the API call\",\n \"status\":\"The HTTP Status Code\",\n \"timestamp\":\"the timestamp of the API call\"\n}\n\nResponse 404 (application/json)
\n{\n \"error\": {\n \"status\": \"Bad Request\",\n \"reason\": \"Missing Requirements\",\n \"description\": \"The following parameters are missing: ['name']\"\n }\n}\n\nPlease note: the \"links\" and \"total\" fields are not used when errors are returned
\nSome of our responses are \"shortcut\" responses and will only return a short data set. For example, the Get Account Balance route only returns the Balance and the Available Balance
Every API result that produces a collection of data can be manually sorted and/or filtered. By default, collections of data are sorted by the createdAt timetsamp DESC. This means the newest record in that data collection is first on the list (and the oldest is last).
You can dictate sorting by passing the sort= parameter in any route and detailing the field (or fields) by which you'd like to sort.
/example?sort=['name':'ASC']\n\nTo manually change number of records returned in a single API call, use the limit= parameter. By default, value of limit is set to 50. If you do not provide limit parameter or do not modify its default value then 50 records are returned.
For example, to return 60 records per page, you would do the following:
/example/?limit=60\n\nlimit parameter works with page parameter. Also refer PAGE section for more details.
Every API result that produces a collection of data is automatically paginated. The default number of records per page is 50. This page and limit parameters works with each other. Value of limit parameter determines the number of records contained in one page.
By default, if no page and limit parameters are specified then page=1 and limit=50 is considered and so record from 1 to 50 are returned in first page.
For example, if you want to retrieve 51 to 100 records then specify page=2
/example/?page=2 (would return results from 51 to 100, provided records are available)\n\nYou must have below available with you before making any of MBAPI call.
\nMBAPI-KEY and MBAPI-SECRET issued to you.Please contact Scion to get your MBAPI-KEY and MBAPI-SECRET pair
\nYou are now ready to start using our API. We look forward to seeing what great financial applications you will be able to create with us and we appreciate your business.
\nWebhook Setup:
\nRegister your webhook endpoint but submitting this to us.
\nUse HTTPS endpoints for secure communication.
\nRequest Authentication:
\nAuthorization header with every webhook request. Validate this header to ensure the request’s authenticity.Response Handling:
\nRespond with a 200 HTTP status code within 10 seconds.
\nAny non-200 response will trigger a retry mechanism.
\nWebhook Secret Rotation:
\nCustomers**
\nCustomer Created
\nDescription: Triggered when a new customer profile is created.
\nEvent Code: customer.created
Payload Example:
\n{\n \"event\": \"customer.created\",\n \"data\": {\n \"customer_id\": \"67890\",\n \"name\": \"John Doe\",\n \"email\": \"john.doe@example.com\",\n \"timestamp\": \"2024-12-19T10:00:00Z\"\n }\n}\n\nCustomer Update
\nDescription: Triggered when a the customer info is updated.
\nEvent Code: customer.updated
Payload Example:
\n{\n \"eventnt\": \"customer.updated\",\n \"data\": {\n \"customer_id\": \"67890\",\n \"name\": \"John Doe\",\n \"email\": \"john.doe@newdomain.com\",\n \"timestamp\": \"2024-12-19T11:00:00Z\"\n }\n}\n\nBusiness Created
\nDescription: Triggered when a new business is created.
\nEvent Code: business.created
Payload Example:
\n{\n \"eventnt\": \"business.created\",\n \"data\": {\n \"business_id\": \"67890\",\n \"name\": \"ACME Business\",\n \"email\": \"john.doe@newdomain.com\",\n \"timestamp\": \"2024-12-19T11:00:00Z\"\n }\n}\n\nBusiness Updated
\nDescription: Triggered when the business info is updated.
\nEvent Code: business.created
Payload Example:
\n{\n \"eventnt\": \"business.updated\",\n \"data\": {\n \"business_id\": \"67890\",\n \"name\": \"ACME Business\",\n \"email\": \"john.doe@newdomain.com\",\n \"timestamp\": \"2024-12-19T11:00:00Z\"\n }\n}\n\nAccount Created
\nDescription: Triggered when a new account is created for a customer.
\nEvent Code: account.created
Payload Example:
\n{\n \"event\": \"account.created\",\n \"data\": {\n \"account_id\": \"13579\",\n \"customer_id\": \"67890\",\n \"type\": \"savings\",\n \"balance\": 0.00,\n \"currency\": \"USD\",\n \"timestamp\": \"2024-12-19T09:00:00Z\"\n }\n}\n\nAccount Updated
\nDescription: Triggered when an account’s details are updated.
\nEvent Code: account.updated
Payload Example:
\n{\n \"event\": \"account.updated\",\n \"data\": {\n \"account_id\": \"13579\",\n \"balance\": 500.00,\n \"currency\": \"USD\",\n \"timestamp\": \"2024-12-19T12:30:00Z\"\n }\n}\n\nAccount Closed:
\nDescription: Triggered when an account is closed.
\nEvent Code: account.closed
Payload Example:
\n{\n \"event\": \"account.closed\",\n \"data\": {\n \"account_id\": \"13579\",\n \"customer_id\": \"67890\",\n \"timestamp\": \"2024-12-19T16:00:00Z\"\n }\n}\n\nTransaction Created
\nDescription: Triggered when a new transaction is initiated.
\nEvent Code: transaction.created
Payload Example:
\n{\n \"event\": \"transaction.created\",\n \"data\": {\n \"transaction_id\": \"24680\",\n \"amount\": 250.00,\n \"currency\": \"USD\",\n \"status\": \"pending\",\n \"timestamp\": \"2024-12-19T14:30:00Z\"\n }\n}\n\nTransaction Settled
\nDescription: Triggered when a transaction is settled.
\nEvent Code: transaction.settled
Payload Example:
\n{\n \"event\": \"transaction.settled\",\n \"data\": {\n \"transaction_id\": \"24680\",\n \"amount\": 250.00,\n \"currency\": \"USD\",\n \"status\": \"settled\",\n \"timestamp\": \"2024-12-19T15:30:00Z\"\n }\n}\n\nReversed
\nDescription: Triggered when a transaction is reversed.
\nEvent Code: transaction.reversed
Payload Example:
\n{\n \"event\": \"transaction.reversed\",\n \"data\": {\n \"transaction_id\": \"24680\",\n \"amount\": 250.00,\n \"currency\": \"USD\",\n \"status\": \"reversed\",\n \"timestamp\": \"2024-12-19T16:30:00Z\"\n }\n}\n\nTo ensure clarity, our naming convention and meanings are as follows:
\nClients are business entities that have contracted with Scion for its Banking as a Service offering.
\nPrograms are distinct offerings offered by Clients to their own prospects and customers. For example, a wallet program or a prepaid card program or a credit card program. Clients and Programs are established outside the API. Programs are operated via the API.
\nCustomers represents individuals who have User Profiles with a Client’s Program. These Customers can be Applicants, Owners of Accounts, Owners of Entities, Users of Accounts, or some combination thereof (for example, a business owner would be a Customer but not necessarily a User of the Account whereas an employee might be a Customer that is authorized as a User of the Account but is not necessarily an Owner of the entity.
\nAccounts are bank accounts that are always attached to a Customer.
\nEntities are organizations, such as a business, that are always attached to one or more Customers and, upon Bank approval, can have one or more Accounts. Customers do not have Entity accounts; Customers may have Entities and Entities may have Accounts.
\nSend Money effects external transfers, including Customer or Business payments (eg via wire or ACH) to their own account elsewhere, and payments to others, either at other banks or other Programs.
\nTransfers are book-entry, or ledger, transfers either between a Customer’s own Accounts or between the Accounts of separate Customers within the same Program and do not use the Wire or ACH payment networks. Note that while money transfers across Programs sponsored by Scion might be executed as book transfers by the Bank, they are invoked via the Send Money calls.
\nTransactions are any type of debit or credit that has already occurred and ledgered on the system.
\nThe Ping endpoint is used to verify that the system is accessible and operational. Think of this as a quick \"heartbeat\" check to confirm your connection to the API.
\n","urlObject":{"path":["ping"],"host":["{{baseURL}}"],"query":[],"variable":[]}},"response":[{"id":"0b516d27-a380-41cc-8c3e-b70aa4274dcc","name":"ping","originalRequest":{"method":"GET","header":[],"url":"{{baseURL}}/ping"},"status":"OK","code":200,"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\n \"success\": true,\n \"data\": {\n \"message\": \"Pong\"\n },\n \"url\": \"/ping\",\n \"status\": 200,\n \"timestamp\": \"2025-01-01T19:40:21Z\"\n}"}],"_postman_id":"d1b6d4c6-c8cb-414c-ae7b-4873d252b3ec"},{"name":"info","event":[{"listen":"prerequest","script":{"id":"7a4c85db-44ba-42ce-9430-7507a7da1a87","exec":["// Use CryptoJS for HMAC and hashing operations\r","const CryptoJS = require('crypto-js');\r","\r","// Retrieve environment variables\r","const apiKey = pm.environment.get('MBAPI-KEY');\r","const apiSecret = pm.environment.get('MBAPI-SECRET');\r","\r","// Generate a random 32-character string\r","const generateRandomString = () => {\r"," const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';\r"," let randomString = '';\r"," for (let i = 0; i < 32; i++) {\r"," randomString += characters.charAt(Math.floor(Math.random() * characters.length));\r"," }\r"," return randomString;\r","};\r","\r","// Generate a nonce\r","const timestamp = Math.floor(Date.now() / 1000); // Unix timestamp in seconds\r","const randomString = generateRandomString();\r","const nonceStringToHash = `${apiKey}${timestamp}${randomString}`;\r","const nonce = CryptoJS.SHA512(nonceStringToHash).toString(CryptoJS.enc.Base64);\r","\r","// Extract the path and query string from the URL\r","const method = pm.request.method.toUpperCase();\r","const rawUrl = pm.request.url.getPathWithQuery(); // Includes the query string\r","\r","// Include the body only for methods that support it\r","let body = '';\r","if (['POST', 'PUT', 'PATCH'].includes(method)) {\r"," body = pm.request.body ? JSON.stringify(pm.request.body.raw || '') : '';\r","}\r","\r","// Construct the string to sign\r","const stringToSign = `${apiKey}${method}${rawUrl}${timestamp}${body}`;\r","\r","// Generate the HMAC signature\r","const signature = CryptoJS.HmacSHA512(stringToSign, apiSecret).toString(CryptoJS.enc.Base64);\r","\r","// Set headers\r","pm.request.headers.add({ key: 'mbapi-key', value: apiKey });\r","pm.request.headers.add({ key: 'mbapi-timestamp', value: timestamp.toString() });\r","pm.request.headers.add({ key: 'mbapi-signature', value: signature });\r","pm.request.headers.add({ key: 'mbapi-nonce', value: nonce });\r","\r","// Log details for debugging (optional)\r","// console.log('HMAC Authentication Details:', {\r","// apiKey,\r","// timestamp,\r","// randomString,\r","// nonce,\r","// stringToSign,\r","// signature\r","// });\r",""],"type":"text/javascript","packages":{}}}],"id":"6e239836-9768-4196-a251-92c8e3a3b539","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"MBAPI-TIMESTAMP","value":"{{MBAPI-TIMESTAMP}}","type":"text"},{"key":"MBAPI-SIGNATURE","value":"{{MBAPI-SIGNATURE}}","type":"text"},{"key":"MBAPI-NONCE","value":"{{MBAPI-NONCE}}","type":"text"},{"key":"MBAPI-KEY","value":"{{MBAPI-KEY}}","type":"text"}],"url":"{{baseURL}}/info","description":"The Info endpoint is designed for testing your API keys and validating your HMAC signature creation process. This call allows clients to confirm their authentication setup is correct and their keys are properly configured.
\nAfter confirming system accessibility with the Ping endpoint and validating your API keys with the Info endpoint, you’re ready to explore the full range of API functionality. Use the provided documentation to integrate additional features, such as managing customers, uploading documents, and more.
\n","urlObject":{"path":["info"],"host":["{{baseURL}}"],"query":[],"variable":[]}},"response":[{"id":"0a7afa8d-3b93-4204-a7a7-fce560a9b924","name":"info","originalRequest":{"method":"GET","header":[{"key":"MBAPI-TIMESTAMP","value":"{{MBAPI-TIMESTAMP}}","type":"text"},{"key":"MBAPI-SIGNATURE","value":"{{MBAPI-SIGNATURE}}","type":"text"},{"key":"MBAPI-NONCE","value":"{{MBAPI-NONCE}}","type":"text"},{"key":"MBAPI-KEY","value":"{{MBAPI-KEY}}","type":"text"}],"url":"{{baseURL}}/info"},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\r\n \"success\": true,\r\n \"data\": {\r\n \"name\": \"Medici Bank\",\r\n \"client_id\": \"CLIDXXXXXXXXXXXXXXX\",\r\n \"createdAt\": \"2024-12-31 00:10:27\"\r\n },\r\n \"url\": \"/info\",\r\n \"status\": 200,\r\n \"timestamp\": \"2025-01-03T05:08:10Z\"\r\n}"}],"_postman_id":"6e239836-9768-4196-a251-92c8e3a3b539"}],"id":"8593a8e3-ca47-4601-b3d5-0bdbed26e14c","description":"Welcome to the API documentation! This guide will help you get started with using our API to integrate seamlessly with your systems. Our platform is designed to be robust, secure, and easy to use, offering tools to validate connectivity and test your integration.
\nThe Create Customer API allows clients to register a new customer in the system. A customer must be associated with a specific client, and the provided information must meet all validation requirements.
\nPOST /customers
This API creates a new customer profile with all relevant details, including personal information, contact details, residential and mailing addresses, and compliance-related fields.
\nfirstName (in body) – The first name of the customer.
\nlastName (in body) – The last name of the customer.
\nemail (in body) – The email address of the customer.
\nmobile (in body) – An object containing:
\nnumber – The mobile phone number.
\ncountryCode – The country code of the mobile number.
\ncountry – The country associated with the phone number.
\nDOB (in body) – The date of birth of the customer (YYYY-MM-DD format).
\nresidential_address (in body) – An object containing:
\naddressLine1 – The primary address line.
\ncityLocale – The city or locale.
\nstateRegion – The state or region.
\npostalCode – The postal code.
\ncountry – The country of residence.
\nmailing_address (in body) – Same structure as residential_address.
\ntaxPayer_id (in body) – The customer's taxpayer identification number.
\ntaxPayer_id_type (in body) – The type of taxpayer ID.
\nprimaryCitizenship (in body) – The country of primary citizenship.
\nisPEP (in body) – Boolean flag indicating if the customer is a Politically Exposed Person (PEP).
\nisUS (in body) – Boolean flag indicating if the customer is a U.S. citizen.
\nisSeniorPolFig (in body) – Boolean flag indicating if the customer is a senior political figure.
\nisFamilySeniorPolFig (in body) – Boolean flag indicating if the customer has a family member who is a senior political figure.
\nmiddleName – Middle name of the customer.
\nmaidenName – Maiden name (if applicable).
\nsuffix – Name suffix (e.g., Jr., Sr.).
\nnickname – Nickname or preferred name.
\nhomePhone – Home phone number.
\nworkPhone – Work phone number.
\nbirthplace – City or country where the customer was born.
\nnationality – Additional nationality details.
\noccupation – Customer's occupation.
\nsecondaryCitizenship – Secondary citizenship if applicable.
\nAll required fields must be present.
\nEmail must be a valid email format.
\nMobile number must follow proper formatting.
\nDOB must be in YYYY-MM-DD format.
\nThe taxPayer_id must match the format based on taxPayer_id_type.
\nCitizenship-related flags must be boolean (true or false).
If any required fields are missing, a 400 Bad Request error is returned.
\nIf the email format is invalid, a 400 Bad Request error is returned.
\nIf the taxPayer_id does not match its expected format, a 400 Bad Request error is returned.
\nIf the customer already exists in the system, a 409 Conflict error is returned.
\nIf an unexpected error occurs, a 500 Internal Server Error is returned.
\nWhen creating or managing customers, a taxpayer ID is required to ensure compliance with regulatory and taxation requirements. Below is a detailed explanation of the supported taxpayer ID types:
\nSSN (Social Security Number)
A unique nine-digit number assigned to individuals by the United States Social Security Administration. The format is XXX-XX-XXXX and is used primarily for tax and identification purposes within the U.S.
EIN (Employer Identification Number)
A unique nine-digit number assigned by the IRS to businesses operating in the United States. The format is XX-XXXXXXX and is used for tax filings and employer-related activities.
ETIN (Electronic Taxpayer Identification Number)
A unique identifier issued for specific electronic tax filing purposes. It is typically assigned by the IRS or equivalent authorities. There is no standardized format, as it can vary depending on its use.
TIN (Taxpayer Identification Number)
A generic term that encompasses various taxpayer ID types (e.g., SSN, EIN, ITIN) issued for tax-related identification.
ITIN (Individual Taxpayer Identification Number)
A nine-digit number issued by the IRS to individuals who are not eligible for an SSN but need to file U.S. taxes. The format is 9XX-XX-XXXX.
NINO (National Insurance Number)
A nine-character alphanumeric identifier issued by the United Kingdom for tax and social security purposes. The format is XX999999X.
GSTIN (Goods and Services Taxpayer Identification Number)
A 15-character alphanumeric identifier assigned to businesses in India under the GST regime.
ABN (Australian Business Number)
An 11-digit identifier assigned to businesses operating in Australia. It is used for tax and other business-related purposes.
PAN (Permanent Account Number)
A ten-character alphanumeric identifier issued by the Indian Income Tax Department. The format is XXXXX9999X.
NIF (Número de Identificación Fiscal)
A tax identification number used in Spain. The format is nine characters, typically starting with a letter and ending with a letter or number (e.g., X9999999T).
CPF (Cadastro de Pessoas Físicas)
An 11-digit tax identification number issued to individuals in Brazil. The format is XXX.XXX.XXX-XX.
CNPJ (Cadastro Nacional da Pessoa Jurídica)
A 14-digit identifier for businesses in Brazil. The format is XX.XXX.XXX/0001-XX.
OTHER
Used for taxpayer ID types not explicitly listed above. Additional context should be provided to ensure proper identification and processing.
The taxPayer_id_type must match one of the supported types listed above.
\nThe taxPayer_id must conform to the specific format for the chosen type.
\nUse the OTHER type only when the taxpayer ID does not fall into any predefined categories.
\nYour unique PUBLIC API Key.
\n","type":"text"},{"key":"MBAPI-TIMESTAMP","value":"{{MBAPI-TIMESTAMP}}","description":"The user generated timestamp for the request. Must be the number of seconds since Unix Epoch. In addition, requests will be rejected if the timestamp used isn't close to the real time.
\n","type":"text"},{"key":"MBAPI-NONCE","value":"{{MBAPI-NONCE}}","description":"A Nonce is a number or string, that can be used only once. The reason for using a nonce in API requests, is to ensure that once a request has been sent, regardless of whether that request is successful, it still cannot be used (or resent) again. This guards against Replay Attacks and some Man-in-the-Middle Attacks. There are a number of ways to create a nonce. However, we ask that you create this nonce in a specific way. The MBAPI-NONCE should be constructed using your MBAPI-KEY + MBAPI-TIMESTAMP + A random 32-character string. Then taking that string and creating a base64_encoded hash. Very similar to the process of creating your HMAC signed request.
The user generated message signature. The MBAPI-SIGNATURE header is generated by creating a SHA512 HMAC message digest with base64 encoding, using your MBAPI-SECRET as the secret key. The message is a concatenated string containing the following, in this order: Your MBAPI-KEY + http request method in all caps + encoded path of requested url in all lower case + MBAPI-TIMESTAMP + body (where + represents string concatenation). The body is the requested body string and should be omitted if there is no request body (this is typical for GET and DELETE requests).
Indicates the media type of the resource. Valid values are: application/json
The List Customers API allows clients to retrieve a paginated list of all customers associated with their client account.
\nGET /customers
This API retrieves all customers for the authenticated client. The response is paginated, and clients can filter results, set limits, and specify sorting preferences.
\nsort (optional) – Defines sorting field and direction.
\nsort=firstName:ASClimit (optional) – Number of records to return per page. Default is 50.
\npage (optional) – Page number for pagination. Default is 1.
\nfilter (optional) – Allows filtering by specific fields.
\ntotal – Total number of customers found.
\ndata – Array of customer records.
\nurl – The request URL.
\nnext – The URL for the next page if available.
\nThe sort parameter must specify a valid field and direction (ASC/DESC).
\nThe limit parameter must be a positive integer.
\nThe page parameter must be a positive integer.
\nIf the sorting field or direction is invalid, a 400 Bad Request error is returned.
\nIf an unexpected error occurs, a 500 Internal Server Error is returned.
\nYour unique PUBLIC API Key.
\n","type":"text"},{"key":"MBAPI-TIMESTAMP","value":"{{MBAPI-TIMESTAMP}}","description":"The user generated timestamp for the request. Must be the number of seconds since Unix Epoch. In addition, requests will be rejected if the timestamp used isn't close to the real time.
\n","type":"text"},{"key":"MBAPI-NONCE","value":"{{MBAPI-NONCE}}","description":"A Nonce is a number or string, that can be used only once. The reason for using a nonce in API requests, is to ensure that once a request has been sent, regardless of whether that request is successful, it still cannot be used (or resent) again. This guards against Replay Attacks and some Man-in-the-Middle Attacks. There are a number of ways to create a nonce. However, we ask that you create this nonce in a specific way. The MBAPI-NONCE should be constructed using your MBAPI-KEY + MBAPI-TIMESTAMP + A random 32-character string. Then taking that string and creating a base64_encoded hash. Very similar to the process of creating your HMAC signed request.
The user generated message signature. The MBAPI-SIGNATURE header is generated by creating a SHA512 HMAC message digest with base64 encoding, using your MBAPI-SECRET as the secret key. The message is a concatenated string containing the following, in this order: Your MBAPI-KEY + http request method in all caps + encoded path of requested url in all lower case + MBAPI-TIMESTAMP + body (where + represents string concatenation). The body is the requested body string and should be omitted if there is no request body (this is typical for GET and DELETE requests).
Indicates the media type of the resource. Valid values are: application/json
The Get Customer Details API allows clients to retrieve detailed information about a specific customer, including their profile information and any associated accounts.
\nGET /customers/:customer_id
This API fetches all available details of a specific customer, including their personal details, addresses, and phone numbers. Additionally, it retrieves any accounts associated with the customer.
\ncustomer – Contains all personal details of the customer.
\naccounts – A list of accounts associated with the customer.
\nThe customer_id parameter is required.
The customer must belong to the authenticated client.
\nThe customer record must not be deleted.
\nIf the customer_id is missing or invalid, a 400 Bad Request error is returned.
If the customer does not exist or is deleted, a 404 Not Found error is returned.
\nIf an unexpected error occurs, a 500 Internal Server Error is returned.
\nYour unique PUBLIC API Key.
\n","type":"text"},{"key":"MBAPI-TIMESTAMP","value":"{{MBAPI_TIMESTAMP}}","description":"The user generated timestamp for the request. Must be the number of seconds since Unix Epoch. In addition, requests will be rejected if the timestamp used isn't close to the real time.
\n","type":"text"},{"key":"MBAPI-NONCE","value":"{{MBAPI-NONCE}}","description":"A Nonce is a number or string, that can be used only once. The reason for using a nonce in API requests, is to ensure that once a request has been sent, regardless of whether that request is successful, it still cannot be used (or resent) again. This guards against Replay Attacks and some Man-in-the-Middle Attacks. There are a number of ways to create a nonce. However, we ask that you create this nonce in a specific way. The MBAPI-NONCE should be constructed using your MBAPI-KEY + MBAPI-TIMESTAMP + A random 32-character string. Then taking that string and creating a base64_encoded hash. Very similar to the process of creating your HMAC signed request.
The user generated message signature. The MBAPI-SIGNATURE header is generated by creating a SHA512 HMAC message digest with base64 encoding, using your MBAPI-SECRET as the secret key. The message is a concatenated string containing the following, in this order: Your MBAPI-KEY + http request method in all caps + encoded path of requested url in all lower case + MBAPI-TIMESTAMP + body (where + represents string concatenation). The body is the requested body string and should be omitted if there is no request body (this is typical for GET and DELETE requests).
Indicates the media type of the resource. Valid values are: application/json
The Update Customer API allows clients to modify an existing customer's details. Only non-ID fields can be updated, ensuring that unique identifiers remain unchanged.
\nPUT /customers/:customer_id
This API enables clients to update customer details selectively. Only the fields provided in the request body will be modified, and all changes will be logged.
\nfirstName – The updated first name of the customer.
\nlastName – The updated last name of the customer.
\nemail – The updated email address of the customer.
\nmobile – An object containing updated mobile details:
\nnumber – The new mobile number.
\ncountryCode – The updated country code.
\ncountry – The updated country name.
\nresidential_address – An object containing updated residential address fields.
\nmailing_address – An object containing updated mailing address fields.
\noccupation – The updated occupation of the customer.
\ntaxPayer_id – The updated taxpayer ID.
\ntaxPayer_id_type – The updated taxpayer ID type.
\nprimaryCitizenship – The updated primary citizenship.
\nsecondaryCitizenship – The updated secondary citizenship (if applicable).
\nThe customer_id must exist in the system.
\nThe email must follow a valid email format.
\nThe mobile number must follow proper formatting.
\nThe taxPayer_id must adhere to the correct format for its type.
\nThe residential_address and mailing_address fields must include valid address components if provided.
\nIf the customer is not found, a 404 Not Found error is returned.
\nIf the email format is invalid, a 400 Bad Request error is returned.
\nIf the taxPayer_id format is incorrect, a 400 Bad Request error is returned.
\nIf an unexpected error occurs, a 500 Internal Server Error is returned.
\nYour unique PUBLIC API Key.
\n","type":"text"},{"key":"MBAPI-TIMESTAMP","value":"{{MBAPI_TIMESTAMP}}","description":"The user generated timestamp for the request. Must be the number of seconds since Unix Epoch. In addition, requests will be rejected if the timestamp used isn't close to the real time.
\n","type":"text"},{"key":"MBAPI-NONCE","value":"{{MBAPI-NONCE}}","description":"A Nonce is a number or string, that can be used only once. The reason for using a nonce in API requests, is to ensure that once a request has been sent, regardless of whether that request is successful, it still cannot be used (or resent) again. This guards against Replay Attacks and some Man-in-the-Middle Attacks. There are a number of ways to create a nonce. However, we ask that you create this nonce in a specific way. The MBAPI-NONCE should be constructed using your MBAPI-KEY + MBAPI-TIMESTAMP + A random 32-character string. Then taking that string and creating a base64_encoded hash. Very similar to the process of creating your HMAC signed request.
The user generated message signature. The MBAPI-SIGNATURE header is generated by creating a SHA512 HMAC message digest with base64 encoding, using your MBAPI-SECRET as the secret key. The message is a concatenated string containing the following, in this order: Your MBAPI-KEY + http request method in all caps + encoded path of requested url in all lower case + MBAPI-TIMESTAMP + body (where + represents string concatenation). The body is the requested body string and should be omitted if there is no request body (this is typical for GET and DELETE requests).
Indicates the media type of the resource. Valid values are: application/json
The Update Customer API allows clients to modify an existing customer's details. Only non-ID fields can be updated, ensuring that unique identifiers remain unchanged.
\nPUT /customers/:customer_id
This API enables clients to update customer details selectively. Only the fields provided in the request body will be modified, and all changes will be logged.
\nfirstName – The updated first name of the customer.
\nlastName – The updated last name of the customer.
\nemail – The updated email address of the customer.
\nmobile – An object containing updated mobile details:
\nnumber – The new mobile number.
\ncountryCode – The updated country code.
\ncountry – The updated country name.
\nresidential_address – An object containing updated residential address fields.
\nmailing_address – An object containing updated mailing address fields.
\noccupation – The updated occupation of the customer.
\ntaxPayer_id – The updated taxpayer ID.
\ntaxPayer_id_type – The updated taxpayer ID type.
\nprimaryCitizenship – The updated primary citizenship.
\nsecondaryCitizenship – The updated secondary citizenship (if applicable).
\nThe customer_id must exist in the system.
\nThe email must follow a valid email format.
\nThe mobile number must follow proper formatting.
\nThe taxPayer_id must adhere to the correct format for its type.
\nThe residential_address and mailing_address fields must include valid address components if provided.
\nIf the customer is not found, a 404 Not Found error is returned.
\nIf the email format is invalid, a 400 Bad Request error is returned.
\nIf the taxPayer_id format is incorrect, a 400 Bad Request error is returned.
\nIf an unexpected error occurs, a 500 Internal Server Error is returned.
\nThe Remove Customer API allows clients to deactivate a customer record by setting the isDeleted flag to true. This ensures that customer data remains in the system but is no longer considered active.
DELETE /customers/:customer_id
This API marks a customer as removed without physically deleting their record. The removal action must include a reason for tracking purposes.
\ncustomer_id (in path) – The unique identifier of the customer to be removed.
\nnotes (in body) – The reason for removing the customer.
\nThe customer_id must exist in the system.
\nThe notes field is required and must contain a valid reason.
\nIf the customer does not exist, a 404 Not Found error is returned.
\nIf the notes field is missing, a 400 Bad Request error is returned.
\nIf an unexpected error occurs, a 500 Internal Server Error is returned.
\nThe Reinstate Customer API allows clients to reactivate a previously removed customer by setting the isDeleted flag back to false.
PUT /customers/:customer_id/reinstate
This API restores a deactivated customer record, allowing the customer to become active again. A reason must be provided to track the reinstatement action.
\ncustomer_id (in path) – The unique identifier of the customer to be reinstated.
\nnotes (in body) – The reason for reinstating the customer.
\nThe customer_id must exist in the system and be in a removed state (isDeleted: true).
The notes field is required and must contain a valid reason.
\nIf the customer does not exist or is not removed, a 404 Not Found error is returned.
\nIf the notes field is missing, a 400 Bad Request error is returned.
\nIf an unexpected error occurs, a 500 Internal Server Error is returned.
\nYour unique PUBLIC API Key.
\n","type":"text"},{"key":"MBAPI-TIMESTAMP","value":"{{mbAPITimeStamp}}","description":"The user generated timestamp for the request. Must be the number of seconds since Unix Epoch. In addition, requests will be rejected if the timestamp used isn't close to the real time.
\n","type":"text"},{"key":"MBAPI-NONCE","value":"{{mbAPINonce}}","description":"A Nonce is a number or string, that can be used only once. The reason for using a nonce in API requests, is to ensure that once a request has been sent, regardless of whether that request is successful, it still cannot be used (or resent) again. This guards against Replay Attacks and some Man-in-the-Middle Attacks. There are a number of ways to create a nonce. However, we ask that you create this nonce in a specific way. The MBAPI-NONCE should be constructed using your MBAPI-KEY + MBAPI-TIMESTAMP + A random 32-character string. Then taking that string and creating a base64_encoded hash. Very similar to the process of creating your HMAC signed request.
The user generated message signature. The MBAPI-SIGNATURE header is generated by creating a SHA512 HMAC message digest with base64 encoding, using your MBAPI-SECRET as the secret key. The message is a concatenated string containing the following, in this order: Your MBAPI-KEY + http request method in all caps + encoded path of requested url in all lower case + MBAPI-TIMESTAMP + body (where + represents string concatenation). The body is the requested body string and should be omitted if there is no request body (this is typical for GET and DELETE requests).
Indicates the media type of the resource. Valid values are: multipart/form-data
File to upload i.e GIF, PNG, JPG, PDF, max size 6 MB
\n","src":"postman-cloud:///1efc95d5-a9c0-42d0-8abf-239a781694ea"},{"key":"customer_id","value":"CID250101234154-YJ2VP4-XA52UL","description":"CustomerID for which to upload the document
\n","type":"text"},{"key":"document_type","value":"PASSPORT","description":"This is the type of document you are uploading for the customer. The optional values are: 'DRIVERSL, 'PASSPORT', 'GOVERNID', 'OTHER'
\n","type":"text"}]},"url":"{{baseURL}}/documents","description":"KYC Doc Statuses:
\nPND - Pending
\nAPR - Approved
\nREJ - Rejected
\nDocument Types:
\nDRIVERSL - Driver's License
\nPASSPORT - Passport
\nGOVERNID - Official Government ID
\nOTHER - Other
\nYour unique PUBLIC API Key.
\n","type":"text"},{"key":"MBAPI-TIMESTAMP","value":"{{mbAPITimeStamp}}","description":"The user generated timestamp for the request. Must be the number of seconds since Unix Epoch. In addition, requests will be rejected if the timestamp used isn't close to the real time.
\n","type":"text"},{"key":"MBAPI-NONCE","value":"{{mbAPINonce}}","description":"A Nonce is a number or string, that can be used only once. The reason for using a nonce in API requests, is to ensure that once a request has been sent, regardless of whether that request is successful, it still cannot be used (or resent) again. This guards against Replay Attacks and some Man-in-the-Middle Attacks. There are a number of ways to create a nonce. However, we ask that you create this nonce in a specific way. The MBAPI-NONCE should be constructed using your MBAPI-KEY + MBAPI-TIMESTAMP + A random 32-character string. Then taking that string and creating a base64_encoded hash. Very similar to the process of creating your HMAC signed request.
The user generated message signature. The MBAPI-SIGNATURE header is generated by creating a SHA512 HMAC message digest with base64 encoding, using your MBAPI-SECRET as the secret key. The message is a concatenated string containing the following, in this order: Your MBAPI-KEY + http request method in all caps + encoded path of requested url in all lower case + MBAPI-TIMESTAMP + body (where + represents string concatenation). The body is the requested body string and should be omitted if there is no request body (this is typical for GET and DELETE requests).
Indicates the media type of the resource. Valid values are: application/json
This will return the KYC doc information with status. The actual file will not be returned.
\n","urlObject":{"path":["documents",":customer_id",":doc_id"],"host":["{{baseURL}}"],"query":[],"variable":[{"description":{"content":"The unique customer ID
\n","type":"text/plain"},"type":"any","value":"","key":"customer_id"},{"type":"any","value":"","key":"doc_id"}]}},"response":[{"id":"b3a1dca4-ea50-4801-a2ef-4f829850ceb8","name":"Get KYC Document","originalRequest":{"method":"GET","header":[{"key":"MBAPI-KEY","value":"{{mbAPIKey}}","description":"Your unique PUBLIC API Key.","type":"text"},{"key":"MBAPI-TIMESTAMP","value":"{{mbAPITimeStamp}}","description":"The user generated timestamp for the request. Must be the number of seconds since Unix Epoch. In addition, requests will be rejected if the timestamp used isn't close to the real time.","type":"text"},{"key":"MBAPI-NONCE","value":"{{mbAPINonce}}","description":"A Nonce is a number or string, that can be used only once. The reason for using a nonce in API requests, is to ensure that once a request has been sent, regardless of whether that request is successful, it still cannot be used (or resent) again. This guards against Replay Attacks and some Man-in-the-Middle Attacks. There are a number of ways to create a nonce. However, we ask that you create this nonce in a specific way. The MBAPI-NONCE should be constructed using your `MBAPI-KEY` + `MBAPI-TIMESTAMP` + `A random 32-character string`. Then taking that string and creating a base64_encoded hash. Very similar to the process of creating your HMAC signed request.","type":"text"},{"key":"MBAPI-SIGNATURE","value":"{{mbHmacSig}}","description":"The user generated message signature. The `MBAPI-SIGNATURE` header is generated by creating a SHA512 HMAC message digest with base64 encoding, using your `MBAPI-SECRET` as the secret key. The message is a concatenated string containing the following, in this order: `Your MBAPI-KEY` + `http request method in all caps` + `encoded path of requested url in all lower case` + `MBAPI-TIMESTAMP` + `body` (where + represents string concatenation). The body is the requested body string and should be omitted if there is no request body (this is typical for GET and DELETE requests).","type":"text"},{"key":"Content-Type","value":"application/json","description":"Indicates the media type of the resource. Valid values are: `application/json`","type":"text"}],"url":{"raw":"{{baseURL}}/documents/:customer_id/:doc_id","host":["{{baseURL}}"],"path":["documents",":customer_id",":doc_id"],"variable":[{"key":"customer_id","value":"","description":"The unique customer ID\n"},{"key":"doc_id","value":""}]}},"_postman_previewlanguage":"json","header":[{"key":"Content-Type","value":"application/json","description":"","type":"text"}],"cookie":[],"responseTime":null,"body":"{\r\n \"success\": true,\r\n \"data\": {\r\n \"doc_id\": \"0193e4dc-16bd-75b6-923b-24dce8f371ea\",\r\n \"doc_type\": \"PASSPORT\",\r\n \"original_fileName\": \"my_passpowrd.jpg\",\r\n \"mime_type\": \"JPG\",\r\n \"status\": \"APR\",\r\n \"uploadedAt\": \"2022-01-01 13:14:54\",\r\n \"updatedAt\": \"2022-01-01 13:14:54\"\r\n },\r\n \"timestamp\": \"2022-01-01 13:14:54\"\r\n}"}],"_postman_id":"6736a97b-26f0-4cee-9844-714b8330627e"}],"id":"87a3d4b9-16c6-4b6b-9e52-f9641e399bb9","description":"Customers are equivalent to Accountholders who have access to accounts. When creating a Customer, you are essentially creating a user profile. Customers can (and should be) vetted (KYC/KYB) before requesting the opening of an account for that Customer.
\n","_postman_id":"87a3d4b9-16c6-4b6b-9e52-f9641e399bb9"},{"name":"Customer Authentication","item":[{"name":"Create Authentication Access","event":[{"listen":"prerequest","script":{"id":"cb8a89f4-9de8-4825-a463-24facbcb958e","exec":["// Use CryptoJS for HMAC and hashing operations","const CryptoJS = require('crypto-js');","","// Retrieve environment variables","const apiKey = pm.environment.get('MBAPI-KEY');","const apiSecret = pm.environment.get('MBAPI-SECRET');","","// Generate a random 32-character string","const generateRandomString = () => {"," const characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';"," let randomString = '';"," for (let i = 0; i < 32; i++) {"," randomString += characters.charAt(Math.floor(Math.random() * characters.length));"," }"," return randomString;","};","","// Generate a nonce","const timestamp = Math.floor(Date.now() / 1000); // Unix timestamp in seconds","const randomString = generateRandomString();","const nonceStringToHash = `${apiKey}${timestamp}${randomString}`;","const nonce = CryptoJS.SHA512(nonceStringToHash).toString(CryptoJS.enc.Base64);","","// Extract only the path from the full URL","const method = pm.request.method.toUpperCase();","const rawUrl = pm.request.url.getPath(); // Extracts only the path (e.g., /info)","// Include the body only for methods that support it","let body = '';","if (['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {"," body = pm.request.body && pm.request.body.raw ? JSON.stringify(JSON.parse(pm.request.body.raw)) : \"\"; // Ensure body is stringified","}","","// Construct the string to sign","const stringToSign = `${apiKey}${method}${rawUrl}${timestamp}${body}`;","","// Generate the HMAC signature","const signature = CryptoJS.HmacSHA512(stringToSign, apiSecret).toString(CryptoJS.enc.Base64);","","// Set headers","pm.request.headers.add({ key: 'mbapi-key', value: apiKey });","pm.request.headers.add({ key: 'mbapi-timestamp', value: timestamp.toString() });","pm.request.headers.add({ key: 'mbapi-signature', value: signature });","pm.request.headers.add({ key: 'mbapi-nonce', value: nonce });","","// Log details for debugging (optional)","// console.log('HMAC Authentication Details:', {","// apiKey,","// timestamp,","// randomString,","// nonce,","// stringToSign,","// signature","// });","","// console.log('String to Sign (Postman):', stringToSign);","// console.log('String to Sign Length (Postman):', stringToSign.length);",""],"type":"text/javascript","packages":{}}}],"id":"e601c426-e64a-4750-b43f-105e14f5ada1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"POST","header":[{"key":"MBAPI-TIMESTAMP","value":"{{MBAPI-TIMESTAMP}}","type":"text"},{"key":"MBAPI-NONCE","value":"{{MBAPI-NONCE}}","type":"text"},{"key":"MBAPI-SIGNATURE","value":"{{MBAPI-SIGNATURE}}","type":"text"},{"key":"MBAPI-KEY","value":"{{MBAPI-KEY}}","type":"text"},{"key":"Content-Type","value":"application/json","type":"text"}],"body":{"mode":"raw","raw":"{\n \"password\": \"04x$?S84p!IFHk\"\n}"},"url":"{{baseURL}}/authentication/create/CID250103014042-RAFVZE-98TWFD","description":"The Create Customer Access API allows clients to establish authentication credentials for a customer, enabling them to log in to the system. This API ensures that a customer access record is created only once; if access has been removed, the user must use the Restore Access API instead.
\nPOST /authentication/create/:customer_id
This API is used to create an authentication record for a customer. A customer can only have one authentication record; if the record already exists, a new one cannot be created. If access was previously removed, the customer must restore access instead of creating a new record.
\ncustomer_id (in path) – The unique identifier of the customer whose access is being created.
\npassword (in body) – The password to be set for the customer.
\nA customer access record cannot be created if one already exists.
\nIf access was previously removed, this API will return an error instructing the client to use the Restore Access API.
\nPassword must meet complexity requirements:
\nAt least 8 characters long
\nMust contain at least one uppercase letter
\nMust contain at least one lowercase letter
\nMust contain at least one number
\nMust contain at least one special character
\nCannot contain spaces
\nThe Remove Customer Access API allows clients to disable authentication for a specific customer. This does not delete the authentication record but marks it as inactive.
\nDELETE /authentication/remove/:customer_id
This API is used to remove access for a customer. Once access is removed, the customer will no longer be able to log in. Access can be reinstated using the Restore Access API.
\nThe customer must have an existing authentication record.
\nIf the customer access is already removed, this API will return an error.
\nThe Restore Customer Access API allows clients to reinstate authentication for a customer whose access was previously removed.
\nPUT /authentication/restore/:customer_id
This API is used to restore access for a customer after it was previously removed. It reactivates the authentication record, allowing the customer to log in again.
\nThe customer must have an existing authentication record that was previously removed.
\nIf the customer’s access is already active, this API will return an error.
\nThe Change Customer Password API allows a customer to update their password while maintaining their authentication credentials.
\nPUT /authentication/changePwd/:customer_id
This API enables a customer to change their password by providing their current password and a new password. The old password must match the existing record for the change to be successful.
\ncustomer_id (in path) – The unique identifier of the customer whose password is being changed.
\npassword_old (in body) – The current password.
\npassword_new (in body) – The new password to be set.
\nThe current password must match the stored password.
\nThe new password must meet complexity requirements:
\nAt least 8 characters long
\nMust contain at least one uppercase letter
\nMust contain at least one lowercase letter
\nMust contain at least one number
\nMust contain at least one special character
\nCannot contain spaces
\nThe new password cannot be the same as the old password.
\nThe Create Business API allows a client to register a business entity associated with a specific customer. A business cannot exist independently; it must be linked to a customer. This API ensures compliance by requiring key details such as business description, industry, tax information, and compliance-related disclosures.
\nPOST /businesses
This API creates a new business entity linked to an existing customer. The request requires a valid customer_id, which must be active (ACT) and belong to the authenticated client_id.
Mandatory fields include:
\nBusiness Name and Description
\nTaxpayer ID (with type)
\nIndustry Type
\nCompliance-related questions
\nMain Address and Mailing Address (both required)
\nAll requests must comply with ISO standards for country codes (ISO 3166-1 alpha-3).
\nEach of these fields is required and must be either true or false.
Both main_address and mailing_address are mandatory and must be valid objects with the following structure:
\n{\n \"addressLine1\": \"123 Business Street\",\n \"addressLine2\": \"Suite 200\",\n \"cityLocale\": \"New York\",\n \"stateRegion\": \"NY\",\n \"postalCode\": \"10001\",\n \"country\": \"USA\"\n}\n\nindustryCustomer must be active (ACT) and belong to the authenticated client.
Country must be in ISO 3166-1 alpha-3 format (USA, GBR, etc.).
Main Address and Mailing Address are both required and must contain valid fields.
\nAll compliance fields must be explicitly true or false (no null/empty values).
Phone must reference an existing phone number record in the phoneNumbers model.
Industry must be one of the predefined values listed above.
\nRetrieves a list of businesses associated with the authenticated client.
\nGET /businesses
This API fetches a list of businesses linked to the authenticated client. The response includes essential business details such as business ID, name, status, industry, country, and creation date.
\nRetrieves the details of a specific business by its business_id, including customer information, industry, phone, and addresses.
GET /businesses/:business_id
This API fetches a single business record with full details, including linked customer information, industry, phone, and addresses. The business must belong to the authenticated client_id.
The Update Business API allows clients to update details of an existing business associated with a customer. Certain fields such as business_id, customer_id, client_id, createdAt, and updatedAt cannot be modified.
PUT /businesses/:business_id
This API updates the details of a specific business associated with a customer. The request must include the business_id in the URL path. The business must exist and belong to the authenticated client_id.
The following fields CANNOT be updated via this API:
\nbusiness_id
customer_id
client_id
createdAt
updatedAt
{\n \"number\": \"18005551234\",\n \"countryCode\": \"+1\",\n \"country\": \"USA\",\n \"type\": \"M\"\n}\n\n{\n \"addressLine1\": \"456 Corporate Ave\",\n \"addressLine2\": \"Suite 101\",\n \"cityLocale\": \"Los Angeles\",\n \"stateRegion\": \"CA\",\n \"postalCode\": \"90001\",\n \"country\": \"USA\"\n}\n\nRefer to the industry list used in the Create Business API for the valid industry IDs.
taxPayer_id must match the expected format for the provided taxPayer_id_type.
industry must be a valid industry ID from the list.
phone must be a valid phone object.
main_address and mailing_address, if provided, must follow the required address structure.
country must be in ISO 3166-1 alpha-3 format (e.g., USA, GBR, IND).
The Remove Business API allows a client to soft-delete a business associated with a customer. The business remains in the system but is marked as deleted (isDeleted: true), preventing further transactions or updates.
DELETE /businesses/:business_id
This API is used to remove a business by setting its isDeleted field to true. It does not permanently delete the business from the database. A removed business can be reinstated using the Reinstate Business API.
A history record of the removal action will be stored in the BusinessesHistory model.
The business_id must exist and belong to the authenticated client.
The business must not already be deleted.
The notes field is required and provides context for the removal.
The Reinstate Business API allows a client to restore a previously removed business by setting its isDeleted field back to false.
PATCH /businesses/:business_id/reinstate
This API reactivates a previously removed business, allowing it to be used for transactions and other operations. A history record of the reinstatement action will be stored in the BusinessesHistory model.
The Request Account API allows clients to create a new financial account for a customer. The account is initially set to Pending (PND) status, requiring approval by a bank administrator before activation. Each request must specify the account type, category, and currency.
\nPOST /accounts/request
This API enables clients to request the creation of a new account. The system will generate a unique account number based on the account type and ensure that duplicate pending requests for the same customer and account type are not allowed.
\nUpon successful creation, the account is logged in the account history with an action of \"REQUESTED\" and the default origin as \"API\".
\ncustomer_id (in body) – The unique identifier of the customer for whom the account is being created.
\naccount_type (in body) – The type of account being requested.
\ncategory (in body) – The category of the account, either B (Business) or C (Consumer/Personal).
\ncurrency (in body) – The currency type of the account. Accepted values: USD, GBP, EUR.
\nBusiness Accounts:
\nBDCA – Business Custody
\nBDDA – Business DDA
\nBSAV – Business Savings
\nBCOD – Business CD
\nBLON – Business Loan
\nConsumer Accounts:
\nCDCA – Consumer Custody
\nCDDA – Consumer DDA
\nCSAV – Consumer Savings
\nCCOD – Consumer CD
\nCLON – Consumer Loan
\nCNOW – Consumer NOW
\ncustomer_id, account_type, category, and currency are required fields.
\nThe account_type must match the category:
\nBusiness (B) can only request BDCA, BDDA, BSAV, BCOD, BLON.
\nConsumer (C) can only request CDCA, CDDA, CSAV, CCOD, CLON, CNOW.
\nThe currency must be one of USD, GBP, EUR.
\nA customer cannot request multiple accounts of the same account_type if there is already a pending (PND) request for that account type.
\nThe system ensures the generated account number is unique.
\nThe List Accounts API allows clients to retrieve all accounts associated with their client ID. This API supports filtering, sorting, and pagination to efficiently retrieve account data.
\nGET /accounts
This API enables clients to retrieve a list of accounts linked to their client ID. It supports optional query parameters for sorting, filtering, and pagination.
\nNone
\nsort (in query) – Specifies sorting of results in the format {field}:{direction}. Allowed fields: account_no, account_type, category, status, createdAt. Direction can be ASC or DESC.
limit (in query) – Defines the number of records to return per page. Default is 50.
page (in query) – Specifies the page number of results. Default is 1.
filter (in query) – Allows filtering of results based on account attributes.
\ntotal – The total number of accounts available.
\ndata – An array of account objects.
\nurl – The requested URL.
\nnext – The URL for the next page of results (if applicable).
\nstatus – The HTTP status code.
\ntimestamp – The timestamp when the response was generated.
\nThe sort parameter must be in the format {field}:{direction} and use only allowed fields.
The limit parameter must be a positive integer.
The page parameter must be a positive integer.
The Get Account Details API allows clients to retrieve full details for a specific account, including account history.
\nGET /accounts/:account_id
This API enables clients to fetch all details of a specific account using the account_id. It includes associated data such as currency details and account history.
account_id – The unique identifier of the account.
\nclient_id – The client to which the account belongs.
\ncustomer_id – The customer associated with the account.
\naccount_no – The account number.
\naccount_type – The type of the account.
\ncategory – Whether the account is Business (B) or Consumer (C).
status – The current status of the account.
\ndescription – The description of the account type.
\ncurrency – The currency type of the account.
\nbalance – The current account balance.
\nbalance_available – The available balance for transactions.
\nopenedAt – The date the account was opened.
\nclosedAt – The date the account was closed (if applicable).
\naccount_history – A list of recorded actions and changes associated with the account.
\ncreatedAt – The timestamp of account creation.
\nupdatedAt – The last update timestamp.
\nThe account_id must exist and belong to the requesting client.
The account must not be marked as deleted (isDeleted = false).
The Get Account Details API allows clients to retrieve full details for a specific account, including account history.
\nGET /accounts/:account_id
This API enables clients to fetch all details of a specific account using the account_id. It includes associated data such as currency details and account history.
account_id – The unique identifier of the account.
\nclient_id – The client to which the account belongs.
\ncustomer_id – The customer associated with the account.
\naccount_no – The account number.
\naccount_type – The type of the account.
\ncategory – Whether the account is Business (B) or Consumer (C).
status – The current status of the account.
\ndescription – The description of the account type.
\ncurrency – The currency type of the account.
\nbalance – The current account balance.
\nbalance_available – The available balance for transactions.
\nopenedAt – The date the account was opened.
\nclosedAt – The date the account was closed (if applicable).
\naccount_history – A list of recorded actions and changes associated with the account.
\ncreatedAt – The timestamp of account creation.
\nupdatedAt – The last update timestamp.
\nThe account_id must exist and belong to the requesting client.
The account must not be marked as deleted (isDeleted = false).
The Deactivate Account API allows clients to modify the status of an active account. This API ensures that only accounts in an Active (ACT) state can have their status changed. Pending accounts (PND) must be approved by a bank administrator before they can be modified.
\nPUT /accounts/:account_id/status
This API enables clients to change the status of an account for specific scenarios, including freezing, suspending, closing, marking as dormant, locking, and restricting an account. The status update must be accompanied by a reason in the notes field.
Only accounts in Active (ACT) status can be modified via this API.
\naccount_id (in path) – The unique identifier of the account to be modified.
\nstatus (in body) – The new status to be applied to the account.
\nnotes (in body) – A required description of the reason for the status change.
\nFRZ (Frozen) – Account is frozen due to investigation.
\nSUS (Suspended) – Account is suspended due to issues like missed payments.
\nCLO (Closed) – Account is permanently closed.
\nDRM (Dormant) – Account has had no activity for an extended period.
\nLCK (Locked) – Account is locked due to failed logins or security concerns.
\nRES (Restricted) – Account has limited functionality due to compliance or legal issues.
\nThe account must be in an ACT (Active) state to change its status.
\nThe notes field is required and must contain a reason for the status change.
Only the statuses listed above are allowed.
\nThe Reactivate Account API allows clients to restore a previously deactivated account to Active (ACT) status. This API ensures that only accounts that were Frozen (FRZ), Suspended (SUS), Dormant (DRM), Locked (LCK), or Restricted (RES) can be reactivated.
\nPUT /accounts/:account_id/reactivate
This API enables clients to restore an account's full functionality by reactivating it. Reactivation applies only to accounts that were previously deactivated but does not apply to accounts in a Closed (CLO) status.
\nThe request must include a reason for reactivation in the notes field.
account_id (in path) – The unique identifier of the account to be reactivated.
\nnotes (in body) – A required description of the reason for reactivating the account.
\nFRZ (Frozen) → ACT (Active) – Account was frozen and is now reactivated.
\nSUS (Suspended) → ACT (Active) – Account was suspended and is now reactivated.
\nDRM (Dormant) → ACT (Active) – Account was inactive for an extended period and is now reactivated.
\nLCK (Locked) → ACT (Active) – Account was locked due to security reasons and is now reactivated.
\nRES (Restricted) → ACT (Active) – Account had limited functionality and is now reactivated.
\nOnly accounts with a status of FRZ, SUS, DRM, LCK, or RES can be reactivated.
\nAccounts in CLO (Closed) status cannot be reactivated.
\nThe notes field is required and must contain a reason for the reactivation.
We offer a number of different Account products (types) when creating an Account:
\nBusiness Accounts
\nBDDA - Business Direct Deposit Account
\nBSAV - Business Savings Account
\nBNOW - Business NOW Account
\nBDCA - Business Custody Account (Escrow, Trust, FBO)
\nPersonal Accounts
\nCDDA - Personal Direct Deposit Account
\nCSAV - Personal Savings Account
\nCNOW - Personal NOW Account
\nCDCA - Personal Custody Account (Escrow, Trust, FBO)
\nThe Withdraw Wire API allows clients to initiate a wire transfer from their account to an external beneficiary. This withdrawal follows the SWIFT MT103 format, ensuring compliance with international and domestic wire transfer standards.
\nPOST /funding/withdraw/wire
This API processes an outgoing wire transfer, deducting funds from the client's account and sending them to a specified beneficiary. The required details differ depending on whether the wire is domestic (U.S.) or international (Non-U.S.).
\n{\n \"addressLine1\": \"123 Main St\",\n \"addressLine2\": \"Apt 4B\",\n \"cityLocale\": \"New York\",\n \"stateRegion\": \"NY\",\n \"postalCode\": \"10001\",\n \"country\": \"USA\"\n}\n\n{\n \"addressLine1\": \"456 Bank Ave\",\n \"addressLine2\": \"Suite 200\",\n \"cityLocale\": \"Los Angeles\",\n \"stateRegion\": \"CA\",\n \"postalCode\": \"90001\",\n \"country\": \"USA\"\n}\n\nisUS = false){\n \"addressLine1\": \"789 Finance Blvd\",\n \"addressLine2\": \"\",\n \"cityLocale\": \"London\",\n \"stateRegion\": \"\",\n \"postalCode\": \"SW1A 1AA\",\n \"country\": \"GBR\"\n}\n\nfour_block_23)amount must be a valid number and greater than zero.
account_id must exist and have sufficient balance for the withdrawal.
If isUS = false, intermediary bank details (intermediary_bank, intermediary_bank_account, intermediary_address) must be provided.
The wire reference (wire_reference) is automatically generated.
The sender's correspondent (four_block_53) is predefined.
beneficiary_address.country, beneficiary_bank_address.country, and intermediary_address.country (if applicable) must be in ISO 3166-1 alpha-3 format.
The Withdraw ACH API allows clients to initiate an ACH transfer from their account to an external beneficiary. This withdrawal follows the NACHA ACH format and adheres to U.S. and international banking standards.
\nPOST /funding/withdraw/ach
This API processes an outgoing ACH transfer, deducting funds from the client's account and sending them to a specified beneficiary. The required details differ depending on whether the ACH is domestic (U.S.) or international (Non-U.S.).
\n{\n \"addressLine1\": \"123 Beneficiary St\",\n \"addressLine2\": \"Suite 500\",\n \"cityLocale\": \"Los Angeles\",\n \"stateRegion\": \"CA\",\n \"postalCode\": \"90001\",\n \"country\": \"USA\"\n}\n\nisUS = false****){\n \"addressLine1\": \"456 Bank Ave\",\n \"addressLine2\": \"Floor 12\",\n \"cityLocale\": \"London\",\n \"stateRegion\": \"\",\n \"postalCode\": \"SW1A 1AA\",\n \"country\": \"GBR\"\n}\nstandard_entry_class (SEC Code)amount must be a valid number and greater than zero.
account_id must exist and have sufficient balance for the withdrawal.
ach_reference must be unique.
ach_type is required but not validated against predefined values.
standard_entry_class must be a valid NACHA SEC Code (see allowed values).
If isUS = false, intermediary bank details (intermediary_bank, intermediary_bank_account_number, intermediary_bank_address) must be provided.
receiver_address.country, intermediary_bank_address.country (if applicable) must be in ISO 3166-1 alpha-3 format.
The ACH Type (ach_type) is required but not validated against predefined values.
The standard_entry_class (SEC Code) is validated against official NACHA SEC Codes.
International ACH Transfers (isUS = false) require intermediary bank details.
Retrieves a list of wire transactions with optional filtering parameters.
\nGET /funding/wires
This API fetches a list of wire transactions based on optional filters such as status, customer, account, or date range. Only active transactions are returned, and soft-deleted (isDeleted: true) transactions are excluded.
statusdate_from and date_to must be in YYYY-MM-DD format.
If both date_from and date_to are provided, date_from must be before or equal to date_to.
Retrieves detailed information about a specific wire transaction.
\nGET /funding/wires/:wire_id
This API fetches detailed wire transaction data, including populated account, customer, and transaction details.
\nRetrieves a list of ACH transactions with optional filtering parameters.
\nGET /funding/achs
This API fetches a list of ACH transactions based on optional filters such as status, customer, account, or date range. Only active transactions are returned, and soft-deleted (isDeleted: true) transactions are excluded.
statusdate_from and date_to must be in YYYY-MM-DD format.
If both date_from and date_to are provided, date_from must be before or equal to date_to.
Retrieves detailed information about a specific ACH transaction.
\nGET /funding/achs/:ach_id
This API fetches detailed ACH transaction data, including populated account, customer, and transaction details.
\nThe Transfer Funds API allows clients to move funds between accounts. Transfers are instant and categorized as either Internal Transfers (INT) or Network Transfers (NET). This function ensures sufficient balance checks and proper transaction logging.
\nPOST /funding/transfer
This API facilitates fund transfers between two accounts. The transfer type is determined automatically:
\nInternal Transfer (INT): When the sender and receiver belong to the same customer.
\nNetwork Transfer (NET): When the transfer is between two different customers.
\nThe system ensures:
\nSufficient balance checks on the sender’s account.
\nAccount and customer status validation to ensure both sender and receiver are active (status = 'ACT').
Instant processing, meaning transactions are immediately reflected in the system.
\ntransfer_type)If sender and receiver accounts belong to the same customer, the transfer type is Internal Transfer (INT).
\nIf sender and receiver accounts belong to different customers, the transfer type is Network Transfer (NET).
\nThe system automatically derives sender_customer_id and receiver_customer_id from the Accounts model.
amount must be a valid number greater than zero.
sender_account_id and receiver_account_id must be different unless it’s an Internal Transfer (INT).
The sender account must have sufficient funds to cover the transfer.
\nThe sender and receiver accounts must be active (status = 'ACT').
The sender and receiver customers must also be active (status = 'ACT').
The currency must match both accounts' currency.
\nRetrieves a list of transfer transactions with optional filtering parameters.
\nGET /funding/transfers
This API fetches a list of transfers based on optional filters such as status, account, or date range. Only active transfers are returned, and soft-deleted (isDeleted: true) transfers are excluded.
statusdate_from and date_to must be in YYYY-MM-DD format.
If both date_from and date_to are provided, date_from must be before or equal to date_to.
Retrieves detailed information about a specific transfer transaction.
\nGET /funding/transfers/:transfer_id
This API fetches detailed transfer transaction data, including populated account, customer, and transaction details.
\nThe List Transactions API allows clients to retrieve a list of transactions based on optional filters such as account, customer, transaction code, or date range.
\nGET /transactions
This API returns a paginated list of transactions. Clients can filter results based on the provided query parameters.
\nstatusdate_from and date_to must be in YYYY-MM-DD format.
If both date_from and date_to are provided, date_from must be before or equal to date_to.
The Get Transaction Details API allows clients to retrieve detailed information about a specific transaction.
\nGET /transactions/:id
This API returns detailed information about a specific transaction, including transaction type, customer, and account details.
\nThe Get Account Transactions API retrieves all transactions for a specific account belonging to the authenticated client.
\nGET /transactions/account/:account_id
This API allows clients to retrieve all transactions associated with a specific account. Transactions are returned in ascending order based on their creation date.
\naccount_id must be provided in the path.
The account_id must belong to the authenticated client (client_id).
The account must not be deleted (isDeleted: false).
If no transactions exist for the given account_id, a 404 Not Found response is returned.
The Get Customer Transactions API retrieves all transactions for a specific customer, grouping them by the customer’s accounts.
\nGET /transactions/customer/:customer_id
This API allows clients to retrieve all transactions associated with a specific customer. Transactions are grouped by account and sorted in ascending order by account number. Each account entry includes its account number, description, balance, and available balance, followed by its corresponding transactions.
\ncustomer_id must be provided in the path.
The customer_id must belong to the authenticated client (client_id).
The customer must not be deleted (isDeleted: false).
If no transactions exist for the given customer_id, a 404 Not Found response is returned.
The Get Statements API provides a list of statements for an account, grouped by month. Each statement includes the transaction count for that month and a link to access detailed statement information.
\nGET /statements/:account_id
This API returns a list of monthly statements for a specified account. Each statement contains summary information, including the month, year, transaction count, and a link to access detailed statement data for that period.
\naccount_id must exist, be valid, and belong to the client making the API call.The Get Statement Details API provides detailed transaction information and summary statistics for a specific statement month.
\nGET /statements/:account_id/:statement_id
This API returns detailed statement information for a specific account and month. The response includes account holder information, account details, transaction data, and summary statistics.
\n