The payment order object

A payment order is an order to create a payment to or out of one of your connected accounts. Numeral connects to your bank to process this payment and sends status updates through webhooks.

AttributeDescription
id
string
The UUID of the payment order.
object
string
The object, here payment_order.
connected_account_id
string
The ID of the connected account used to trigger the payment order.
type
string
The payment scheme or network. The following types are supported:sepa, sepa_instant, bacs, fps, and treasury.
treasury_option
string
In case of treasury payment orders (type = "treasury"), the treasury option to apply. Only local, international, and relocated treasury payments are supported.
confidentiality_option
string
In case of confidential payments, the confidentiality option to apply. Only payroll confidential payments are supported.
direction
string
Either credit or debit.

The direction describes the direction of the money. A credit moves money from your account to another account. A debit moves money from another account to your account.

A payment order of type:sepa and direction:credit is a SEPA credit transfer (SCT). A payment order of type:sepa and direction:debit is a SEPA direct debit (SDD).
amount
integer
The absolute value of the payment in the specified currency's smallest unit.

For euro payments, the smallest unit is cents. €20 is represented as 2000.
currency
string
The currency of the payment. EUR and GBP are supported.
reference
string
The reference is the message that will appear on the origin and destination account statements, with a maximum of 140 characters.
originating_account
object
The account originating the payment.

This attribute must be filled by financial institution customers only. It must be left empty for corporate customers.

The object includes the following attributes:
  • account_number: the account number or IBAN. In case the account_number is 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 bank code, sort code, or BIC. Only upper case letters are allowed.
  • holder_name: the legal entity or individual name
  • creditor_identifier: the account creditor identifier
  • holder_address: the account holder address, as an address object
receiving_account
object
The account receiving the payment instruction. This attribute must be left empty if receiving_account_id is filled.

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

When direction = debit, the receiving account is the account to be debited.

The object includes the following attributes:
  • account_number: the account number or IBAN. In case the account_number is 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 bank code, sort code, or BIC. Only upper case letters are allowed.
  • holder_name: the legal entity or individual name
  • holder_address: the account holder address, as an address object
receiving_account_id
string
The ID of the counterparty_account receiving the payment instruction. This attribute must be left empty if receiving_account parameters are filled.

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

When direction = debit, the receiving account is the account to be debited.
direct_debit_mandate
object
The mandate authorizing the direct debit.

This attribute must be filled only when the payment order’s direction is debit.

The object includes the following attributes:
  • reference: the unique reference that is assigned to a mandate. The reference will appear on the account statement of the account debited
  • signature_date: the signature date of the mandate
  • type: the type of the mandate, either sepa_core or sepa_b2b
  • sequence: the sequence of the mandate, either one_off or recurring
direct_debit_mandate_id
string
The ID of the direct debit mandate used in this payment order. This attribute must be left empty if direct_debit_mandate parameters are filled.
retried_from_payment_id
string
The ID of the payment order from which this payment was retried.
retried_to_payment_id
string
The ID of the payment order to which this payment was retried.
value_date
date
The value date of the payment order. The value date might be updated as the payment is processed by the bank or the CSM.
requested_execution_date
date
The requested execution date of the payment order. Only relevant for direct debits.
status
string
The status of the payment order. It will be updated as the payment order is processed. See Payment order lifecycle events for a comprehensive list of statuses of a payment order.
status_details
string
The details of the status of this payment order.
reconciliation_status
string
The reconciliation status of the payment order, which is either unreconciled, reconciled, or partially_reconciled.
reconciled_amount
integer
The amount that is already reconciled.

It is the sum of the amount of the reconciliations related to this payment order.
auto_approval
boolean
Either true or false, default value is false.

When auto_approval is true, the payment is created in status approved.

When auto_approval is false, the payment is created in status pending_approval and must be approved in order to be sent.
metadata
object
Additional data in JSON key:value format. See Metadata.
bank_data
object
Bank data, such as message and transaction IDs, in JSON key:value format.
idempotency_key
string
An idempotency key is a unique value sent by the client, which the server uses to recognize subsequent retries of the same request. See Idempotency.
created_at
datetime
The UTC timestamp of the creation of this 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 cut-off time and calendar.

If you would like to schedule and execute a payment order on a specific date, you should create it on this date, prior to the bank's cut-off time.

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