v1

latestOpenAPI 3.1.02026-07-24180245513.9 KB

Internal Accounts

Create internal account

Create an internal account, which can refer to an existing active account holder. This internal account will only be created in Numeral system and should be created by your bank beforehand. It will refer to either: (1) a type own account, namely a record of a financial institution connected account or (2) a type virtual account managed by your bank.

post/internal_accounts

Request body

type'own' | 'virtual' required

The type of the internal account.

namestring required

The name of the internal account.

holder_namestring required

The name of the internal account holder.

alternative_holder_namesstring[]

Alternative account holder names, for instance if the account is a joint account.

account_numberstring required

The account number of the internal account. Own internal accounts accept IBANs and UK domestic account numbers, and virtual internal accounts accept any alphanumerical account numbers up to 35 characters.

account_number_format'iban' | 'uk_account_number' | 'us_account_number' | 'tokenized' | 'other'

The format of the account number. When set, it must match account_number unless the format is other or tokenized.

bank_codestring

The bank code. Mandatory for internal accounts of type = own.

bank_code_format'bic' | 'uk_sorting_code' | 'us_aba_routing_number' | 'tokenized' | 'other'

The format of the bank code. When set, it must match bank_code unless the format is other or tokenized.

account_holder_idstring uuid

The ID of the account holder to which the internal account belongs to. It must not be disabled.

bank_namestring

The name of the bank holding the account.

creditor_identifierstring

The unique reference for organisations collecting payments by SEPA Direct Debit.

custom_fieldsCommonCustomFields

Custom fields in JSON key:value format. See Custom fields.

metadataobject

Additional client data in JSON format. See Metadata.

cbs_source'mambu'

The CBS this internal account refers to. Only mambu is supported.

cbs_account_idstring

The ID of the account in linked CBS. Must be provided if cbs_source is provided.

cbs_account_type'deposit'

The type of account in linked CBS. Only deposit supported. Must be provided if cbs_source is provided.

synchronized_with_bankboolean

Whether the internal account is synchronized with the bank.

generate_account_numberboolean

Whether the account number should be automatically generated by Mambu Payments. Contact your account manager to activate this feature.

currenciesstring[]

ISO 4217 currencies of the account.

customer_bicstring

BIC of the internal account. Used for Swift correspondent payments.

distinguished_namestring

Distinguished name (DN) of the internal account. Used for Swift correspondent payments.

Example request

{
  "name": "PartnerCo Main Account",
  "holder_name": "PartnerCo SAS",
  "account_number": "FR4217569000705838477329D20",
  "account_number_format": "iban",
  "bank_code": "SOMEBIC0XXX",
  "bank_code_format": "bic",
  "organization_identification": {
    "legal_entity_identifier": "529900T8BM49AURSDO55",
    "business_identification_code": "SOMEBIC0XXX",
    "default_other_identifier_type": "siren",
    "others": [
      {
        "type": "siren",
        "value": "901250746"
      }
    ]
  },
  "holder_address": {
    "line_1": "1, place de la Concorde",
    "building_number": "1",
    "street_name": "place de la Concorde",
    "postal_code": "75008",
    "city": "Paris",
    "country": "FR",
    "department": "Marketing",
    "sub_department": "Content team",
    "building_name": "Bat. 4",
    "floor": "3",
    "postal_box": "67b",
    "room": "47",
    "city_location_name": "Confluences",
    "district_name": "District 9"
  },
  "bank_name": "BankCo",
  "bank_address": {
    "line_1": "1, place de la Concorde",
    "building_number": "1",
    "street_name": "place de la Concorde",
    "postal_code": "75008",
    "city": "Paris",
    "country": "FR",
    "department": "Marketing",
    "sub_department": "Content team",
    "building_name": "Bat. 4",
    "floor": "3",
    "postal_box": "67b",
    "room": "47",
    "city_location_name": "Confluences",
    "district_name": "District 9"
  },
  "creditor_identifier": "FR12ZZZ123456",
  "metadata": {
    "property_a": true,
    "property_b": "some text"
  },
  "cbs_account_id": "ACC-ID-CBS-0000-0000",
  "synchronized_with_bank": true,
  "generate_account_number": true,
  "currencies": [
    "EUR",
    "USD"
  ],
  "customer_bic": "BNPAFRPPXXX",
  "distinguished_name": "CN=foo,OU=bar,O=baz"
}

Response

200

idstring uuid required

The UUID of the internal account.

object'internal_account' required

The object, here internal_account.

status'pending_creation' | 'creation_rejected' | 'active' | 'blocked' | 'disabled' required

The status of the internal account.