Numeral enables you to manage account holders, external accounts and internal accounts.

An account holder is an individual or organization you need to send money to, receive money from or hold account on behalf of. It can be a customer, a supplier, a merchant, a partner, a group company, etc.

An external account is a bank account in the name of the account holder. An account holder can have different external accounts, for distinct use cases, in different currencies, or at multiple banks.

An internal account is a bank account your organization holds on behalf of one of your customers. It is only applicable to financial institutions. An account holder can have different internal accounts.

Account holder

Create an account holder

To create an account holder, simply use the Create an account holder API endpoint to pass its name and any relevant metadata (such as an internal ID):

curl --request POST \
     --url https://sandbox.numeral.io/v1/account_holders \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
  "name": "PartnerCo",
  "metadata": {
    "internal_id": "123"
  }
}
'

The API will return the account holder object:

#{
    "id": "de785fd3-da86-45c7-a185-719ebfb2122d",
    "object": "account_holder",
    "name": "PartnerCo",
    "metadata": {
      "internal_id": "123"
    },
    "created_at": "2022-09-05T14:54:11.76182Z",
    "disabled_at": null,
}

Disable an account holder

You can disable an account holder. Disabling an account holder also disables the associated external and internal accounts. A disabled account holder has a disabled_at timestamp.

A disabled account holder can no longer be used to create an external or internal accounts and will trigger an error.

External accounts

Create the related external accounts

After the account holder has been created, you can add external accounts related to this account holder. An external account is the bank account of an account holder. It must have all the account details required to send a payment to this counterparty.

To create an external account, use the Create an external account with the ID of the account holder created:

curl --request POST \
     --url https://sandbox.numeral.io/v1/external_accounts \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
    "account_holder_id": "de785fd3-da86-45c7-a185-719ebfb2122d",
    "holder_name": "PartnerCo SAS",
    "account_number": "FR7601234567891127967100082",
    "bank_code": "BNPAFRPPXXX",
    "holder_address": {
        "line_1": "1, rue de la Bourse",
        "line_2": "",
        "postal_code": "59000",
        "region_state": "",
        "city": "Lille",
        "country": "FR"
    },
}

The API will return the external account object:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object": "external_account",
  "account_holder_id": "de785fd3-da86-45c7-a185-719ebfb2122d",
  "holder_name": "PartnerCo SAS",
  "account_number": "FR7601234567891127967100082",
  "bank_code": "BNPAFRPPXXX",
  "holder_address": {
    "line_1": "1, rue de la Bourse",
    "line_2": "",
    "postal_code": "59000",
    "region_state": "",
    "city": "Lille",
    "country": "FR"
  },
  "metadata": {},
  "created_at": "2022-09-06T19:38:26.442Z",
  "disabled_at": "2022-09-06T19:38:26.442Z",
}

Please note that you can create an external account without an account holder.

Create a payment order using an external account

To create a payment order using an external account, use its ID in the receiving_account_id body parameter of your Create a payment order API request. The receiving account data will be populated with the related external account details. Creating a external account and using its ID simplifies your API requests. It also enables you to filter payment orders by external account or account holder.

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
  "connected_account": "711b414e-2d31-11ed-a261-0242ac120002",
  "type": "sepa",
  "direction": "credit",
  "amount": 1000,
  "currency": "EUR",
  "receiving_account_id": "0d3b9d33-21d4-47c5-9421-be899ed8a4ba",
  "reference": "Payment 85a7407c",
}

Create an expected payment using a counterparty account

Similarly, you can create an expected payment using the ID of an external account in the external_account_id body parameter of your Create an expected payment API request. The external account data will be populated with the related external account details. Creating a external account and using its ID simplifies your API requests. It also enables you to filter expected payments by external account or account holder.

curl --request POST \
     --url https://sandbox.numeral.io/v1/expected_payments \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
  "connected_account_id": "711b414e-2d31-11ed-a261-0242ac120002",
  "direction": "credit",
  "amount_from": 1000,
  "amount_to": 1000,
  "currency": "EUR",
  "start_date": "2022-09-05",
  "end_date": "2022-09-10",
  "external_account_id": "0d3b9d33-21d4-47c5-9421-be899ed8a4ba",
  "description": "Subscription 11eda261",
}

Internal accounts

An internal account is a bank account your organization holds. It is only applicable to financial institutions.

An internal can be one of 2 types:

own: your organization holds this account one behalf of one of its customers, it uses your BIC and an account number you generated
virtual: your organizations uses a virtual account number, provided by your partner bank

Create an internal account

curl --request POST \
     --url https://sandbox.numeral.io/v1/internal_accounts \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
    "account_holder_id": "de785fd3-da86-45c7-a185-719ebfb2122d",
    "connected_account_ids":["a5d1f662-28ff-4215-9bdd-d735cdb5f8d7"],
    "type": "own",
    "name": "Account PartnerCo FR"
    "holder_name": "PartnerCo SAS",
    "account_number": "FR7601234567891127967100082",
    "bank_code": "YOURBICXXX",
    "holder_address": {
        "line_1": "1, rue de la Bourse",
        "line_2": "",
        "postal_code": "59000",
        "region_state": "",
        "city": "Lille",
        "country": "FR"
    },
}

Please note that you can create an internal account without an account holder.

Create a payment order using an internal account

To create a payment order using an internal account, use its ID in the originating_account_id body parameter of your Create a payment order API request. The originating account data will be populated with the related external account details. Creating a internal account and using its ID simplifies your API requests. It also enables you to filter payment orders by internal account or account holder.

curl --request POST \
     --url https://sandbox.numeral.io/v1/expected_payments \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
  "connected_account_id": "711b414e-2d31-11ed-a261-0242ac120002",
  "direction": "credit",
  "amount_from": 1000,
  "amount_to": 1000,
  "currency": "EUR",
  "start_date": "2022-09-05",
  "end_date": "2022-09-10",
  "internal_account_id": "0d3b9d33-21d4-47c5-9421-be899ed8a4ba",
	"external_account_id": "ff3f23d6-0585-455d-aa80-05ebe95ff542",
  "description": "Subscription 11eda261",
}