Numeral enables you to manage counterparties and counterparty accounts.

A counterparty is an individual or organization you need to send money to or receive money from. It can be a customer, a supplier, a merchant, a partner, a group company, etc.

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

Create a counterparty

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

curl --request POST \
     --url https://sandbox.numeral.io/v1/counterparties \
     --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 counterparty object:

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

Create the related counterparty accounts

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

To create a counterparty account, use the Create a counterparty account with the ID of the counterparty created:

curl --request POST \
     --url https://sandbox.numeral.io/v1/counterparty_accounts \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
    "counterparty_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 counterparty account object:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "object": "counterparty_account",
  "counterparty_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",
}

In addition, the counteparty object will be updated with the related counterparty account:

{
  "id": "de785fd3-da86-45c7-a185-719ebfb2122d",
  "object": "counterparty",
  "name": "PartnerCo",
  "counterparty_accounts": [
      {
        "id": "0d3b9d33-21d4-47c5-9421-be899ed8a4ba",
        "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"
        },          
        "created_at": "2022-09-05T14:57:38.770012Z",
        "disabled_at": null,
      },
    ],
  "metadata": {
    "internal_id": "123"
  },
  "created_at": "2022-09-05T14:54:11.76182Z",
  "disabled_at": null,
}

Create a payment order using a counterparty account

To create a payment order using a counterparty 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 counterparty account details. Creating a counterparty account and using its ID simplifies your API requests. It also enables you to filter payment orders by counterparty account or counterparty.

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 a counterparty account in the counterparty_account_id body parameter of your Create an expected payment API request. The counterparty account data will be populated with the related counterparty account details. Creating a counterparty account and using its ID simplifies your API requests. It also enables you to filter expected payments by counterparty account or counterparty.

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",
  "counterparty_account_id": "0d3b9d33-21d4-47c5-9421-be899ed8a4ba",
  "description": "Subscription 11eda261",
}

Disable a counterparty or counterparty account

You can disable a counterparty or a counterparty account. Disabling a counterparty also disables the associated counterparty accounts. A disabled counterparty or counterparty account has a disabled_at timestamp.

A disabled counterparty can no longer be used to create a counterparty account and will trigger an error. Similarly, a disabled counterparty account can no longer be used to create a payment order or expected payment and will trigger an error.