Creating bank accounts

When making API requests to our system, it is important to include the authorization token in the Authorization header to authenticate your requests. The correct format for including the token is:

Authorization: Bearer ${ACCESS_TOKEN}

For detailed information on obtaining and using access tokens, please refer to the Authentication section of our documentation.

Create Bank Account

Create a new bank account

Creates a new bank account for the authenticated user.

POST/bank-accounts

Authorization

Access Token

Body

application/json

accountNumber*string

bicSwift*string

currency*string

receiver*string

Response

201

Request

JavaScriptCurl

const response = await fetch('/bank-accounts', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer Bearer",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "accountNumber": "text",
      "bicSwift": "text",
      "currency": "text",
      "receiver": "text"
    }),
});
const data = await response.json();

Creates a new bank account for a receiver.

Request Body

Field	Type	Description
accountNumber	string	The account number of the bank account
bicSwift	string	The BIC/SWIFT code of the bank account
currency	string	The ID of the currency the account uses
receiver	string	The ID of the receiver the account belongs to

Example:

{
  "accountNumber": "PT50002700000001234567833",
  "bicSwift": "BESCPTPLXXX",
  "currency": "61482ebf6a2bb0c0d6b82f81",
  "receiver": "61482ebf6a2bb0c0d6b82f80"
}

Iban validations

• Check if accountNumber is not undefined, null, or an empty string.

• Verify if there is a specification (spec) available for the country indicated by the first two characters of the accountNumber. If not, the validation fails.

• Ensure that the length of the accountNumber matches the expected length specified for the country. If not, the validation fails.

• Validate the format of the Basic Bank Account Number (BBAN) portion of the accountNumber. If it doesn't match, the validation fails.

• Check if the two digits following the country code in the accountNumber represent a valid checksum (i.e., they are numeric).

• Validate the IBAN checksum. If the checksum is invalid, the validation fails.

• If no accountNumber is provided, the validation fails.

BIC/SWIFT validations

• Check if the bic (Bank Identifier Code) is falsy (null, undefined, empty string). If so, the validation fails.

• The first 6 characters must be alphabetic (uppercase or lowercase).

• The next 2 characters can be alphanumeric (uppercase, lowercase, or digits).

• Optionally, the next 3 characters can be alphanumeric.

• Retrieve the country specification based on the two characters at positions 4 and 5 in the uppercase bicSwift.

Status Code	Description
200	Returns the newly created bank account
400	check IBAN and BIC validations
401	If the user is not authenticated
403	If the user account is not confirmed or the onboarding status is not approved
500	If there is a server error while creating the bank account

Example response (Success):

{
  "accountNumber": "1234567890",
  "bicSwift": "ICBCUSBJ",
  "currency": {
    "_id": "63ebc49a227fcc69535bb96d",
    "name": "USD",
    "symbol": "$",
    "isoCode": "USD",
    "createdAt": "2023-02-14T17:27:54.400Z",
    "updatedAt": "2023-02-14T17:27:54.400Z",
    "__v": 0
  },
  "receiver": {
    "_id": "63fca2ba63be838030b2d4bd",
    "firstName": null,
    "lastName": null,
    "legalName": "teste",
    "type": "COMPANY",
    "email": "[e-mail]",
    "owner": "63ebc79156940ab1c9c32210",
    "country": {
      "_id": "63ebc49a227fcc69535bb77d",
      "name": "Afghanistan",
      "isoCode3166": "AF",
      "continent": "AS",
      "createdAt": "2023-02-14T17:27:54.095Z",
      "updatedAt": "2023-02-14T17:27:54.095Z",
      "__v": 0
    },
    "currency": {},
    "createdAt": "2023-02-27T12:31:54.370Z",
    "updatedAt": "2023-02-27T12:31:54.370Z",
    "__v": 0
  },
  "_id": "6423239e6eb191e45530eb87",
  "createdAt": "2023-03-28T17:27:58.227Z",
  "updatedAt": "2023-03-28T17:27:58.227Z"
}

Note: To assist with creating Bank Accounts you can retrieve information from our Countries and Currencies APIs.

Retrieve Bank Account by ID

Retrieves a bank account by id

Find Bank Account by ID

Finds a bank account by ID.

GET/bank-accounts/{id}

Authorization

Access Token

Path parameters

id*string

Response

200

Request

JavaScriptCurl

const response = await fetch('/bank-accounts/{id}', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer Bearer"
    },
});
const data = await response.json();

If the bank account belongs to you, you will receive a 200 status code along with the bank account details. If the bank account was not found or does not belong to you, you will receive a 400 status code with an error message.

Example Response (Success):

{
  "_id": "640018b6136f0eaf5f4444c5",
  "accountNumber": "210938109283",
  "bicSwift": "BIC/SWIFT",
  "currency": {
    "_id": "63ebc49a227fcc69535bb96f",
    "name": "EUR",
    "symbol": "€",
    "isoCode": "EUR",
    "createdAt": "2023-02-14T17:27:54.401Z",
    "updatedAt": "2023-02-14T17:27:54.401Z",
    "__v": 0
  },
  "receiver": {
    "_id": "640018b6136f0eaf5f4444be",
    "firstName": null,
    "lastName": null,
    "legalName": "example",
    "type": "COMPANY",
    "email": "[e-mail]",
    "owner": "63ebc79156940ab1c9c32210",
    "country": {
      "_id": "63ebc49a227fcc69535bb77f",
      "name": "Antigua and Barbuda",
      "isoCode3166": "AG",
      "continent": "NA",
      "createdAt": "2023-02-14T17:27:54.103Z",
      "updatedAt": "2023-02-14T17:27:54.103Z",
      "__v": 0
    },
    "currency": {},
    "createdAt": "2023-03-02T03:32:06.136Z",
    "updatedAt": "2023-03-02T03:32:06.136Z",
    "__v": 0
  },
  "createdAt": "2023-03-02T03:32:06.357Z",
  "updatedAt": "2023-03-02T03:32:06.357Z"
}

Get all bank accounts for the current user

Finds all bank accounts belonging to the current user, using pagination and optional search query parameters.

GET/bank-accounts/me

Authorization

Access Token

Query parameters

Response

200

Request

JavaScriptCurl

const response = await fetch('/bank-accounts/me', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer Bearer"
    },
});
const data = await response.json();