Payment order object

Use payment orders to send payment instructions to your banks through Numeral. Numeral receives payment orders, formats them, batches them if applicable, and sends them to your partner banks. Numeral retrieves and updates payment statuses. Payment status updates are sent to your webhooks as events.

AttributeDescription
id
string		The payment order ID.
object
string		Always payment_order.
connected_account_id
string		The ID of the connected account used to send the payment order.
type
string		The payment scheme or network. Types supported include:
  • sepa
  • sepa_instant
  • bacs
  • fps
  • swift
  • treasury
treasury_option
string		The treasury payment option, whentype = treasury. Supported treasury options include:
  • local, for same-country treasury payments
  • international, for cross-country treasury payments
  • safeguarding, for treasury payments between settlement and safeguarding accounts
  • relocated, to initiate payments from another bank than the connected account's bank, with whom an agreement has been signed
confidentiality_option
string		Only confidentiality option supported is payroll.
fee_option
string		Network payment fee preference. Only applicable to Swift payments (type=swift). Supported values include:
  • originator: fee paid by the originating party
  • receiver: paid by the receiving party
  • shared: fee split between the originating and the receiving party
direction
string		Either credit or debit, from the perspective of the receiving account:
  • A credit payment order credits a counterparty account and debits your account
  • A debitpayment order debits a counterparty accounts credits your account
Combined with the payment order type, the direction indicates the payment scheme or method used. For instance:
  • A payment order with type = sepa and direction = credit is a SEPA credit transfer
  • A payment order with type = bacs and direction = debit is a Bacs direct debit
amount
integer		The payment amount, in the currency's smallest unit.

For instance, euro smallest unit is cents and €20 is thus represented as 2000.
currency
string		The payment currency. EUR and GBP are currently supported.
reference
string		The payment reference as it will appear on the originating account and receiving account statements, with a maximum of 140 characters.
originating_account
object		The account originating the payment.

It must be filled for financial institution customers only and must be left empty for corporate customers.

The originating_account object includes the following attributes:
  • account_number: the account number or IBAN. If an IBAN, Numeral verifies the validity of the IBAN, but does not verify that the IBAN exists or belongs to the account holder
  • bank_code: the BIC / Swift code or sort code, depending on the country and bank. Only upper case letters allowed
  • holder_name: the name of the company or individual holding the account
  • creditor_identifier: the creditor identifier, in case of SEPA direct debit or Bacs payments
  • holder_address: the account holder address, as an address object
ultimate_originator
object		The ultimate originator of the payment. Only applicable to payment service providers. It is composed of the following attributes:
  • holder_name: the name of the ultimate originator, either an individual or a business
  • organization_identification: an object either containing the bank_code of the ultimate originator, or other that can hold additional information like its registration ID.
receiving_account
object		The account receiving the payment:
  • If direction = credit, the receiving account is the account to credit
  • If direction = debit, the receiving account is the account to debit
It must be left empty if receiving_account_id is filled.

The receiving_account object includes the following attributes:
  • account_number: the account number or IBAN. If an IBAN, Numeral verifies the validity of the IBAN, but does not verify that the IBAN exists or belongs to the account holder
  • bank_code: the BIC / Swift code or sort code. Only upper case letters allowed
  • holder_name: the name of the company or individual holding the account
  • holder_address: the account holder address, as an address object
receiving_account_id
string		The ID of the counterparty account receiving the payment. It must be left empty if receiving_account is filled.

When direction = credit, the receiving account is the account to credited.

When direction = debit, the receiving account is the account to debit.`
direct_debit_mandate
object		The mandate authorizing the direct debit, only for direct debit payments

The direct_debit_mandate object includes the following attributes:
  • reference: the mandate reference. It will appear on the account statement of the account debited
  • signature_date: the mandate signature date
  • type: the mandate type, either sepa_core or sepa_b2b
  • sequence: the mandate sequence, either one_off or recurring
direct_debit_mandate_id
string		The direct debit mandate ID. It must be left empty if direct_debit_mandate is filled.
retried_from_payment_id
string		The original payment order ID, in case the payment order is a retry.
retried_to_payment_id
string		The ID of the payment order retry, in case the payment order has been retried.
value_date
date		The payment order value date. It might be updated as the payment is processed by the bank or the CSM.
requested_execution_date
date		The payment order requested execution date. Only supported for direct debit payments.
status
string		The payment order status. It will be updated as the payment order is processed. See Payment order lifecycle for a comprehensive list of payment order statuses.
status_details
string		The payment order status details.
reconciliation_status
string		The payment order reconciliation status. Either unreconciled, reconciled, or partially_reconciled.
reconciled_amount
integer		The amount reconciled, calculated as the sum of the reconciliations created for this payment order.
auto_approval
boolean		When auto_approval = true, the payment order is created in status approved.

When auto_approval = false, the payment is created in status pending_approval and must be approved to be sent.

Set to false by default.
retry_details
object		All relevant information about the payment order retries.

The retry_details object includes the following attributes:
  • payment_retry_rule_id: the ID of the payment retry rule attached to the payment order. See Payment retry rule
  • original_payment_id: the ID of the original payment order that led to the current object through a chain of retries
  • retried_from_payment_id: the ID of the payment order the payment order has been retried from, in case the payment order is a retry
  • retried_to_payment_id: the ID of the payment order the payment order has been retried to, in case the payment order has been retried.
  • retry_scheduled_at: the UTC timestamp of the expected retry
metadata
object		Additional data in JSON key:value format. See Metadata.
custom_fields
object		Custom fields in JSON key:value format. See Custom fields.
bank_data
object		Bank data in JSON key:value format. This object contains banking information managed by Numeral and determined by the specific integration rules of each bank. This includes fields such as end_to_end_id which are set according to banking protocols and cannot be set by users. Client-specific information can be stored in metadata and custom fields and will persist through the payment order processing in Numeral.
idempotency_key
string		A unique key sent by the customer and used by Numeral to identify subsequent retries of the same request. See Idempotency.
created_at
datetime		The UTC timestamp of the creation of the payment order.

📘

Execution date

A payment order does not have an execution date. The execution date is the date when the payment order is added to a payment file and sent to the bank, taking into consideration applicable your bank's cut-off time and CSM's calendar.

If you would like to schedule and execute a payment order on a specific date, you should create it on this date, taking into consideration applicable your bank's cut-off time and CSM's calendar.

Below are examples of payment orders:

{
   "id": "b69837bf-e784-4bd1-b0d0-2ad0e61a89b6",
   "idempotency_key": "a23a61d8-9adf-4bd2-a453-fd3938c8871f",
   "object": "payment_order",
   "connected_account_id": "254e3100-afd6-44f2-8084-87e8ae67b554",
   "type": "sepa",
   "treasury_option": null,
   "confidentiality_option": null,
   "direction": "credit",
   "amount": 2000,
   "currency": "EUR",
   "reference": "Invoice 1234",
   "originating_account": {
      "account_number": "FR7601234567890627967100010",
      "bank_code": "SOGEFRPP",
      "holder_name": "SoftwareCo",
      "creditor_identifier": "",
      "holder_address": {
         "line_1": "1, rue de l'Abondance",
         "line_2": "",
         "postal_code": "69003",
         "region_state": "",
         "city": "Lyon",
         "country": "FR"
      }
   },
   "receiving_account_id": "b38f5318-a389-4278-9cbe-d16116750982",
   "receiving_account": {
      "account_number": "FR7601234567891127967100082",
      "bank_code": "BNPAFRPPXXX",
      "holder_name": "PartnerCo",
      "holder_address": {
         "line_1": "1, rue de la Bourse",
         "line_2": "",
         "postal_code": "59000",
         "region_state": "",
         "city": "Lille",
         "country": "FR"
      }
   },
   "direct_debit_mandate": {},
   "direct_debit_mandate_id": "",
   "retried_from_payment_id": "dec3336c-2ec6-47ee-a69f-33353c7fdfaf",
   "retried_to_payment_id": "",
   "value_date": "2022-01-03",
   "requested_execution_date": "",
   "status": "executed",
   "status_details": "",
   "auto_approval": false,
   "retry_details":{
     "payment_retry_rule_id":"dec3336c-2ec6-47ee-a69f-33353c7fdfaf",
     "original_payment_id":"bf400636-dd95-426e-8a13-e9b49aa0838b",
     "retried_to_payment_id":"9dcdaab7-861c-4e3b-8101-44fef53e289f",
     "retried_from_payment_id":"e0362ec5-0292-40d9-b6ad-985528da0443",
     "retry_scheduled_at":"2022-01-03T11:53:19.734182Z",
   },
   "reconciled_amount": 2000,
   "reconciliation_status": "reconciled",
   "metadata": {},
   "custom_fields": {},
   "bank_data": {
      "file_id": "a815e756-5576-4d40-9fbd-38ec304b856c",
      "message_id": "1gXrtKMxLJ",
      "transaction_id": "1zDrzOMxCJ",
      "end_to_end_id": "c3b2d737bc"
   },
   "created_at": "2022-01-03T11:53:19.734182Z"
}

{
   "id": "b69837bf-e784-4bd1-b0d0-2ad0e61a89b6",
   "idempotency_key": "a23a61d8-9adf-4bd2-a453-fd3938c8871f",
   "object": "payment_order",
   "connected_account_id": "254e3100-afd6-44f2-8084-87e8ae67b554",
   "type": "sepa_instant",
   "treasury_option": null,
   "confidentiality_option": null,
   "direction": "credit",
   "amount": 2000,
   "currency": "EUR",
   "reference": "Invoice 1234",
   "originating_account": {
      "account_number": "FR7601234567890627967100010",
      "bank_code": "SOGEFRPP",
      "holder_name": "SoftwareCo",
      "creditor_identifier": "",
      "holder_address": {
         "line_1": "1, rue de l'Abondance",
         "line_2": "",
         "postal_code": "69003",
         "region_state": "",
         "city": "Lyon",
         "country": "FR"
      }
   },
   "receiving_account": {
      "account_number": "FR7601234567891127967100082",
      "bank_code": "BNPAFRPPXXX",
      "holder_name": "PartnerCo",
      "holder_address": {
         "line_1": "1, rue de la Bourse",
         "line_2": "",
         "postal_code": "59000",
         "region_state": "",
         "city": "Lille",
         "country": "FR"
      }
   },
   "direct_debit_mandate": {},
   "direct_debit_mandate_id": "",
   "retried_from_payment_id": "dec3336c-2ec6-47ee-a69f-33353c7fdfaf",
   "retried_to_payment_id": "",
   "value_date": "2022-01-03",
   "requested_execution_date": "",
   "status": "executed",
   "status_details": "",
   "auto_approval": false,
   "reconciled_amount": 2000,
   "reconciliation_status": "reconciled",
   "metadata": {},
   "bank_data": {
      "file_id": "a815e756-5576-4d40-9fbd-38ec304b856c",
      "message_id": "1gXrtKMxLJ",
      "transaction_id": "1zDrzOMxCJ",
      "end_to_end_id": "c3b2d737bc"
   },
   "created_at": "2022-01-03T11:53:19.734182Z"
}

{
   "id": "b69837bf-e784-4bd1-b0d0-2ad0e61a89b6",
   "idempotency_key": "a23a61d8-9adf-4bd2-a453-fd3938c8871f",
   "object": "payment_order",
   "connected_account_id": "254e3100-afd6-44f2-8084-87e8ae67b554",
   "type": "sepa",
   "treasury_option": null,
   "confidentiality_option": null,
   "direction": "debit",
   "amount": 2000,
   "currency": "EUR",
   "reference": "Invoice 1234",
   "originating_account": {
      "account_number": "FR7601234567890627967100010",
      "bank_code": "SOGEFRPP",
      "holder_name": "SoftwareCo",
      "creditor_identifier": "FR12ZZZ123456",
      "holder_address": {
         "line_1": "1, rue de l'Abondance",
         "line_2": "",
         "postal_code": "69003",
         "region_state": "",
         "city": "Lyon",
         "country": "FR"
      }
   },
   "receiving_account": {
      "account_number": "FR7601234567891127967100082",
      "bank_code": "BNPAFRPPXXX",
      "holder_name": "PartnerCo",
      "holder_address": {
         "line_1": "1, rue de la Bourse",
         "line_2": "",
         "postal_code": "59000",
         "region_state": "",
         "city": "Lille",
         "country": "FR"
      }
   },
   "direct_debit_mandate": {
      "reference": "DDb05e47338e87",
      "signature_date": "2022-07-14",
      "type": "sepa_core",
      "sequence": "recurring"
   },
   "direct_debit_mandate_id": "fc57af6a-2545-11ee-be56-0242ac120002",
   "retried_from_payment_id": "dec3336c-2ec6-47ee-a69f-33353c7fdfaf",
   "retried_to_payment_id": "",
   "value_date": "2022-01-03",
   "requested_execution_date": "2022-01-03",
   "status": "executed",
   "status_details": "",
   "auto_approval": false,
   "reconciled_amount": 2000,
   "reconciliation_status": "reconciled",
   "metadata": {},
   "bank_data": {
      "file_id": "a815e756-5576-4d40-9fbd-38ec304b856c",
      "message_id": "1gXrtKMxLJ",
      "transaction_id": "1zDrzOMxCJ",
      "end_to_end_id": "c3b2d737bc"
   },
   "created_at": "2022-01-01T11:53:19.734182Z"
}