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