Learn how to manage internal accounts in Numeral
An internal account represent a customer account held by a payment service provider (PSP). It can be typed own
when the PSP uses its own bank code (BIC / Swift code or sort code) and generates its own account numbers / IBANs or virtual
when it uses virtual account numbers (also called virtual accounts, virtual IBANs, or vIBANs) provided by its partner bank.
Attribute | Description |
---|---|
id string | The internal account ID. |
object string | Always internal_account . |
type string | The type of the internal account. Can be own or virtual . |
status string | The status of the internal account. See Internal account lifecycle for a comprehensive list of internal account statuses. |
name string | The internal account usual name. |
connected_account_ids string | The list of connected account IDs this internal account is related to. At least one ID must be provided if internal account is used for payments. Internal accounts used for VOP do not require connected account IDs. |
account_holder_id string | The ID of the related account holder. |
holder_name string | The name of the company or individual holding the account. |
alternative_holder_names array[string] | Optional alternative company or individual names holding the account, for instance with joint or undivided accounts. |
holder_address string | The account holder address. See address object. |
account_number string | The account number of the internal account. It can be an IBAN or domestic account number. |
bank_code string | The BIC / Swift code, sort code, or domestic bank code, depending on the country and bank. |
creditor_identifier string | The unique reference for organisations collecting payments. Only applicable to internal accounts collecting direct debit payments. Can be a SEPA Creditor Identifier (SCI) or a UK Service User Number (SUN). |
organization_identification object | The organization identification of the internal account. See Organization identification. |
metadata object | Additional data in JSON key:value format. See Metadata. |
custom_fields object | Custom fields in JSON key:value format. See Custom fields. |
disabled_at datetime | The internal account disabling UTC timestamp. |
created_at datetime | The internal account creation UTC timestamp. |
Below is an example of an internal account:
{
"id": "b38f5318-a389-4278-9cbe-d16116750982",
"object": "internal_account",
"status": "created",
"connected_account_ids": ["4b97bbe0-e8cb-11ed-a05b-0242ac120003"],
"type": "own",
"name": "EndCustomerCo Main Account",
"account_number": "FR7601234567891127967100082",
"bank_code": "SOMEBIC0XXX",
"holder_name": "EndCustomerCo",
"alternative_holder_names": ["EndCustomer Enterprises"],
"account_holder_id": "a268354a-eec6-4ec3-abab-e6f78eda9454",
"holder_address": {
"building_number": "10",
"street_name": "rue de la Bourse",
"country": "FR",
"postal_code": "59000",
"region_state": "",
"city": "Lille",
"line_1": "",
"line_2": ""
},
"organization_identification": {
"legal_entity_identifier": "L3I9ZG2KFGXZ61BMYR72",
"business_identification_code": null,
"default_other_identification": "siren",
"others":[
{
"type": "siren",
"value": "123456789"
}
]
},
"creditor_identifier": "FR123ZZZ6617379",
"metadata": {},
"custom_fields": {},
"created_at": "2024-10-24T09:53:19.734182Z",
}