Use the Create payment order API endpoint to send payments with Mambu Payments. Mambu Payments receives payment orders, formats them, batches them if applicable, and sends them to your partner banks, CSMs, or Swift. Mambu Payments retrieves and updates payment statuses. Payment status updates are sent to your webhooks as events.

End-to-end payment order flow

sequenceDiagram
participant Customer
participant Numeral as Mambu Payments
participant Partner bank as Partner bank (if applicable)
participant CSM
Customer->>Customer:Receive payment request from end customer
Customer->>Customer:Control and authorise payment request
Customer->>Numeral:Send POST /payment_orders/ API request
Numeral->>Numeral:Queue payment order
Numeral->>Customer:Send event payment_order.auto_approved to webhook
Numeral->>Numeral:Batch payment order into payment pain / pacs file
Numeral->>Customer:Send file.created event to webhook
Numeral->>Customer:Send payment_order.processing event to webhook
Numeral->>Customer:Send file.auto_approved event to webhook
Numeral->>Numeral:Encrypt and sign payment pain / pacs file
Numeral->>Partner bank:Send payment pain / pacs file
Numeral->>Customer:Send file.sent event to webhook
Numeral->>Customer:Send payment_order.sent event to webhook
Partner bank->>Partner bank:Control payment pain / pacs file
Partner bank->>CSM:Send payment pacs file
Partner bank->>Numeral:Send payment status report pain / pacs file
Numeral->>Numeral:Parse payment status report pain / pacs file
Numeral->>Numeral:Reconcile payment status report pain / pacs file with corresponding payment order
Numeral->>Numeral:Update payment status to executed
Numeral->>Customer:Send payment_order.executed event to webhook
Customer->>Customer:Update payment request status and notify end customer

ℹ️
This sequence diagram applies to indirect participants to payment schemes. For direct participants, there would be no partner bank and payments would go directly from the customer to the CSM through Mambu Payments.

Create payment order

To create a payment order, use the Create payment order API endpoint:

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders \
     --header 'x-api-key: Your-API-Key' \
     --header 'Idempotency-Key: b9a53cf1-f4e1-4941-a4ef-ad42526d8fa0' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "sepa",
  "direction": "credit",
  "amount": 1234, <-- payment amount in cents
  "currency": "EUR",
  "reference": "Invoice 1234",
  "connected_account_id": "24e3157c-4942-11ed-b878-0242ac120002", <-- bank account or CSM connectivity
  "originating_account_id": "8d97ed83-a6f7-4929-8e90-01b2912fb6a7", <-- bank account originating the payment
  "receiving_account_id": "b38f5318-a389-4278-9cbe-d16116750982", <-- beneficiary bank account
  "auto_approval": true,
}

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders \
     --header 'x-api-key: Your-API-Key' \
     --header 'Idempotency-Key: 295d5c66-f606-42ff-a7af-0d7457e61aa7' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "sepa_instant",
  "direction": "credit",
  "amount": 1234, <-- payment amount in cents
  "currency": "EUR",
  "reference": "Invoice 1234",
  "connected_account_id": "24e3157c-4942-11ed-b878-0242ac120002", <-- bank account or CSM connectivity
  "originating_account_id": "8d97ed83-a6f7-4929-8e90-01b2912fb6a7", <-- bank account originating the payment
  "receiving_account_id": "b38f5318-a389-4278-9cbe-d16116750982", <-- beneficiary bank account
	"auto_approval": true,
}
'

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders \
     --header 'x-api-key: Your-API-Key' \
     --header 'Idempotency-Key: 5323be83-6718-4467-a618-114876520346' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "sepa",
  "direction": "debit",
  "amount": 1234, <-- payment amount in cents
  "currency": "EUR",
  "reference": "Invoice 1234",
  "connected_account_id": "24e3157c-4942-11ed-b878-0242ac120002", <-- bank account or CSM connectivity
  "originating_account_id": "8d97ed83-a6f7-4929-8e90-01b2912fb6a7", <-- bank account originating the payment
  "receiving_account_id": "b38f5318-a389-4278-9cbe-d16116750982", <-- beneficiary bank account
  "direct_debit_mandate_id": "15ee5994-9019-478c-b27a-a4edfec17c58",
  "direct_debit_sequence_type": "recurring",
  "auto_approval": true
}
'

In addition to the API, payment orders can also be created manually or in bulk in the dashboard.

Receive payment order status updates

Mambu Payments retrieves and updates payment order statuses. Payment order status updates are sent to your webhooks as events. The main payment order statuses include:

Status	Description
sent	Payment has been sent to the bank or CSM.
executed	Payment has been executed by the bank or CSM.
pending	Payment has been put on hold by the bank or CSM.
rejected	Payment order has been rejected by the bank or CSM.
returned	Payment order has been returned after having been executed by the bank or CSM.

Related resources

Payment order object
Create payment order API endpoint
Create bulk action API endpoint to bulk create payment orders
Approve payment order API endpoint
Cancel payment order API endpoint
Payment order lifecycle