The account holder, external account, and internal account Mambu Payments objects enable you to manage your customers, suppliers, vendors, and partners and their accounts.

Object	Description
Account holder	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 account holder can have multiple external accounts (for distinct use cases, different currencies, or multiple banks). An account holder can also have multiple internal accounts.
External account	An external account is a bank account in the name of the account holder. External accounts: Can be used as receiving accounts in payment orders Will appear as originating accounts in incoming payments
Internal account	An internal account is a bank, payment, or electronic money account your organization holds for a customer. Internal accounts: Can be used as originating accounts in payment orders Will appear as receiving accounts in incoming payments

Object

Description

Account holder

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 account holder can have multiple external accounts (for distinct use cases, different currencies, or multiple banks).

An account holder can also have multiple internal accounts.

External account

An external account is a bank account in the name of the account holder.

External accounts:

Can be used as receiving accounts in payment orders
Will appear as originating accounts in incoming payments

Internal account

An internal account is a bank, payment, or electronic money account your organization holds for a customer.

Internal accounts:

Can be used as originating accounts in payment orders
Will appear as receiving accounts in incoming payments

Account holder

Create an account holder

To create an account holder, use the Create account holder API endpoint:

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"
  }
}
'

{
    "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 external accounts

After an 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. You can create an external account with or without an account holder.

To create an external account, use the Create external account API endpoint:

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"
    },
}

{
  "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",
}

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 payment order API request. The receiving account data will be populated with the related external account details. Creating an external account and using its ID simplifies your API requests as well as enables you to filter payment orders by external account.

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 an external 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 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 as well as enables you to filter expected payments by external account.

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, payment, or electronic money account your organization holds. It is only applicable to financial institutions. An internal can be one of two types:

Type	Description
`own`	This is an account you hold on behalf of a customer. This account has a bank code and account number you manage.
`virtual`	This is an account held and virtual account number managed by your partner bank.

Create an internal account

To create an internal account, use the Create internal account API endpoint with or without an account holder:

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"
    },
}

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 payment order API request. The originating account data will be populated with the related internal account details. Creating a internal account and using its ID simplifies your API requests as well as enables you to filter payment orders by internal account.

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_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",
}