Create payment order

post

https://sandbox.numeral.io/v1/payment_orders

Create a payment order to be sent to the bank. Once created, a payment order can be approved or canceled.

Create payment orders in batches using the Bulk actions object.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

type

string

enum

required

The type of payment.

direction

string

enum

required

Defaults to credit

The direction of the payment. Describes the direction the money is flowing. A credit moves money from your account to someone else's account. A debit moves money from someone else's account to your account.

Allowed:

amount

int64

required

≥ 0

The absolute amount of a payment, in the specified currency's smallest units. For euro payments, the smallest unit is cents. €20 is represented as 2000.

currency

string

required

The ISO 4217 currency code of the payment order.

reference

string

required

length ≤ 140

The reference that will appear on the origin and destination account statements, with a maximum of 140 characters.

end_to_end_id

string

length ≤ 35

The end-to-end ID of the payment order. Only supported for specific banks and payment schemes. Contact us to get more details.

connected_account_id

uuid

required

The ID of the connected account. The connected account is the account used to trigger the payment order.

originating_account

object

The account from which the payment originates. This field is required for financial institution customers. For corporate customers, this field is optional. If absent, the originating account is automatically derived from the connected account information. If present, the original account either represents the virtual account attached to the connected account or the 3rd party account.

originating_account_id

uuid

The ID of the internal_account sending the payment instruction. It must be left empty if the originating_account parameter is filled.

ultimate_originator

object

The ultimate originating account of the payment (sometimes called ultimate debtor for a credit transfer or ultimate creditor for a direct debit).

receiving_account

object

The account receiving the payment instruction. It must be left empty if receiving_account_id or direct_debit_mandate_id parameter is filled.

receiving_account_id

uuid

The ID of the external_account receiving the payment instruction. It must be left empty if receiving_account or direct_debit_mandate_id parameter is filled.

direct_debit_mandate

object

The mandate authorizing the direct debit. This attribute must be filled only when the payment order's direction is debit. It must be left empty if direct_debit_mandate_id parameter is filled.

direct_debit_mandate_id

uuid

The mandate's ID authorizing the direct debit. This attribute must be filled only when the payment order's direction is debit. It must be left empty if receiving_account, receiving_account_id, or direct_debit_mandate parameter is filled.

direct_debit_sequence_type

string | null

enum

Identifies the direct debit sequence, such as first, recurrent, final or one-off. This field is optional and should only be used when direct_debit_mandate or direct_debit_mandate_id is provided.

Allowed:

initiated_at

date-time

The UTC timestamp this payment order was initiated. This value marks the start of the payment order lifecycle and has millisecond precision (up to 3 digits where trailing zeros are dropped).

This field is valid and optional when the payment type is sepa_instant and the connected account type is financial_institution. In all other cases, this field must be omitted from the request.

intermediary_agents

array of objects

Intermediary financial institution agents via which the payment should be processed. Only applicable to swift payments.

intermediary_agents

previous_instructing_agents

array of objects

Applicable to swift_fi_to_fi, target2 and target2_fi_to_fi payments.

previous_instructing_agents

uetr

uuid

Unique End-to-end Transaction Reference (UETR). Can be used to track payments with Swift GPI.

purpose

string

The purpose code of the payment, ensuring compliance with regulatory requirements of certain beneficiary countries. Only applicable to swift and chaps payment types.

category_purpose_code

string

The category purpose of the payment. Recommended for chaps payments.

fee_option

string

enum

Network payment fee preference. Only applicable to Swift payments. Supported values include originator (fee paid by the originating party), receiver (paid by the receiving party), or shared (fee split between the originating and the receiving party).

Allowed:

routing_instruction

string

Specific instructions intended for the next financial institution in the payment chain to ensure proper processing of the transaction. Only applicable to swift payments.

instructed_agent

string

Instructed agent of the payment order. Can only be set for financial institution payments of type sepa_instant, target2, and target_2_fi_to_fi. If not set, Mambu Payments will fill this value automatically based on the payment's target scheme or receiving account.

addressee_bank_code

string

Addressee BIC of the payment order. Can only be set for financial institution payments of type sepa_instant, target2, and target_2_fi_to_fi. If not set, Mambu Payments will fill this value automatically based on the payment's target scheme or receiving account.

requested_execution_date

date

The requested execution date of the payment order.

auto_approval

boolean

Defaults to false

The auto_approval flag determines whether a payment requires human intervention before execution.

When true: The system bypasses all manual approval steps.

If a validation rule applies, the payment starts as pending_approval.
If no rules apply, the payment is immediately approved.

When false: The payment always starts as pending_approval and requires a manual user action. If a validation rule is also attached, it must be successfully completed before the payment can reach the final approved status.

retry_details

object

Information about the payment order retries.

treasury_option

string

enum

The treasury_option attribute is used to specify the type of treasury payments (type = treasury). It can take the following values, local (for instance payments from a French account to another French internal account), international (French to German accounts), relocated (to send payments from another partner bank), and safeguarding (only applicable to financial institutions, to send funds from their settlement account to their safeguarding account and vice versa).

Allowed:

confidentiality_option

string

enum

Used in case of a confidential payment. Only payroll confidential payments are supported for now.

Allowed:

settlement_method

string

enum

The settlement_method attribute is mandatory when creating Swift payment orders (type = swift) with a connected account of type financial_institution. For all other payment orders, this attribute - if provided - is simply ignored when creating bank files.

Allowed:

fi_to_fi_option

string

enum

The fi_to_fi_option attribute is mandatory when creating payment orders with type = swift_fi_to_fi or target2_fi_to_fi.

Allowed:

related_payment_id

uuid

Mandatory when creating payment orders with type = swift_fi_to_fi or target2_fi_to_fi and fi_to_fi_option = cover.

cbs_transfer_allowed

boolean

Defaults to false

Indicates if the payment type could be promoted to a cbs_transfer.

metadata

object

Additional client data in JSON format. See Metadata.

custom_fields

object

Custom fields in JSON key:value format. See Custom fields.

Headers

Idempotency-Key

string

An idempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.

Responses

200200

400Validation error.

409Conflict.

415Unsupported Media Type.