1. Introduction to payment orders

Payment orders represent payment instructions sent to your partner banks or CSMs through Mambu Payments. Mambu Payments receives payment orders, formats them, batches them if applicable, and sends them to your partner banks or CSMs. Mambu Payments retrieves and updates payment statuses. Payment status updates are sent to your webhooks as events. Learn more about the lifecycle of payment orders.

2. Create payment order

A payment order is an order to send a payment from of one of your connected accounts. Among other attributes, a payment order has:

Learn more about payment order attributes.

Below is the request to send a €10.00 SEPA credit transfer payment using the Create a payment order API endpoint:

curl --request POST \
     --url https://sandbox.numeral.io/v1/payment_orders \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-API-Key: Your_API_Key'
     --data '
{
  "type": "sepa",
  "direction": "credit",
  "amount": 1000,
  "currency": "EUR",
  "connected_account_id": "634f662d-44f3-4b56-b823-a1442d5beb69",
  "external_account_id": "4e6f03f7-5777-41ed-b58b-ae1e32b4ba2c",
  "reference": "Invoice 1234",
  "auto_approval": false
}
'

{
  "id": "b69837bf-e784-4bd1-b0d0-2ad0e61a89b6",
  "object": "payment_order",
  "connected_account_id": "634f662d-44f3-4b56-b823-a1442d5beb69",
  "type": "sepa",
  "direction": "credit",
  "amount": 1000,
  "currency": "EUR",
  "reference": "Invoice 1234",
  "originating_account": {
    "account_number": "FR7601234567890627967100010",
    "bank_code": "SOGEFRPP",
    "holder_name": "SoftwareCo",
    "holder_address": {
      "line_1": "1, rue Rivoli",
      "line_2": "",
      "postal_code": "75001",
      "region_state": "",
      "city": "Paris",
      "country": "FR"
    }
  },
  "receiving_account_id": "4e6f03f7-5777-41ed-b58b-ae1e32b4ba2c",
  "receiving_account": {
    "account_number": "FR9617569000505936314373V66",
    "bank_code": "NUMBFRPPXXX",
    "holder_name": "Acme Corporation",
    "holder_address": {
      "line_1": "1, rue de la Bourse",
      "line_2": "",
      "postal_code": "59000",
      "region_state": "",
      "city": "Lille",
      "country": "FR"
    }
  },
  "value_date": "2022-01-06",
  "status": "pending_approval",
  "status_details": "",
  "reconciled_amount": 1000,
  "reconciliation_status": "reconciled",
  "reconciliation_override": false,
  "metadata": {
    "invoice_id": "b122-423f"
  },
  "bank_data": {
    "file_id": null,
    "message_id": null,
    "transaction_id": null,
    "end_to_end_id": null
  },
  "created_at": "2022-01-06T11:53:19.734182Z",
  "updated_at": "2022-01-06T15:12:20.644356Z"
}

3. Approve payment order

Payment orders are created in status pending_approval. They can be approved:

• Automatically by setting the auto_approval attribute to false
• Programatically using Approve payment order and Cancel payment order API endpoints
• Manually in the dashboard using payment approval rules

In addition to programmatic or manual approval, payment validation rules can be attached to payment orders. Common payment validations include checking the balance of an account in your core banking system, the account authorised currencies, or the absence of sanctions on the originator or recipient of the payment. Learn more about payment validation.

After it has been approved, a payment order will be batched (if applicable) and sent to your partner bank or CSM.

4. Validate payment file to send payment payment order

Every payment order approved is batched into a file with other payments to be sent to the bank. Payment files must be approved before being sent to the bank or clearing house. Payment files can be approved:

• Using the Approve file and Cancel file API endpoints
• Manually in the dashboard
• Automatically by activating the file auto approval setting

After a payment file has been approved, its status will first be updated to approved and then to sent shortly after. Similarly, the status of the related payment orders will be updated from approved to sent.

5. Track payment order

Usually less than an hour after the payment has been sent to your bank, the bank sends back a payment status report to inform Mambu Payments about the execution status of the payment. From this point, the payment could have been accepted or rejected.

To retrieve the latest status of a payment order, you can either retrieve the payment order or retrieve events.

5.1. Retrieve payment order status

Retrieve payment order

You can use the Retrieve payment order API endpoint time to retrieve the status of a payment order.

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/payment_orders/b69837bf-e784-4bd1-b0d0-2ad0e61a89b6' \
     --header 'Accept: application/json'
     --header 'x-api-key: YOUR_API_Key'

If the status changes from sent to executed, it means that the payment has been executed by the bank. You can refer to the payment order lifecycle to learn more about existing statuses and possible status transitions.

5.2. Retrieve events

Similarly, you can use the List events API endpoint to retrieve events related to your payment order and its file. You can use the related_object_id filter to filter events related to your payment ID or file ID:

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/events?related_object_id=b69837bf-e784-4bd1-b0d0-2ad0e61a89b6' \
     --header 'Accept: application/json' \
     --header 'x-api-key: YOUR_API_Key'

The API will return all events related to the payment order.

5.3. Receive events through webhooks

In addition to be retrieved using the API, events can be sent to one or multiple webhooks exposed by your application. For each event, Mambu Payments (formerly Numeral) will send a POST request to your API endpoint in JSON format. This API request contains an event object. Learn more about webhooks.

6. Reconcile payment order

As payments are processed and transactions are posted on your bank account, Mambu Payments automatically reconciles them with unreconciled payments. Transactions can also be reconciled manually using the Mambu Payments API or dashboard.

A reconciliation takes the form of a reconciliation object and always reconciles a single payment with a single transaction. Multiple reconciliations can be created to reconcile a single payment with multiple transactions or multiple payments with a single transaction.

As payment and transactions are reconciled, their reconciliation_status is updated:

Learn more about reconciliations.