Learn how to manage returns in Mambu Payments (formerly Numeral)
A return is the return of an incoming payment or payment order.
| Attribute | Description |
|---|---|
| id string | The return ID. |
| object string | Always return. |
| connected_account_id string | The ID of the connected account used to send or receive the return. |
| type string | The payment scheme or network. Supported types are: - sepa- sepa_instant- swift- target2- target2_fi_to_fi- fps |
| return_type string | The type of return, when available. For instance return, refund, or reversal. |
| direction string | The direction of the return: - credit for returns related to credit or instant credit transfers- debit for returns related to direct debits. |
| related_payment_type string | The type of the payment returned, either payment_order or incoming_payment |
| related_payment_id string | The ID of the payment returned. |
| return_reason string | The return reason. Authorised reasons depend on the payment scheme. For SEPA, refer to SEPA reason codes. |
| value_date date | The value date of the return. |
| returned_amount integer | The payment amount, in the currency's smallest unit. For instance, euro smallest unit is cents and €20 is thus represented as |
| currency string | The return currency. Only EUR is supported. |
| receiving_account_number string | The account number of the account receiving the return. |
| status string | The return status. It will be updated as the return is processed. |
| status_details string | The return status details. |
| reconciliation_status string | The return 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. |
| payment_validation object | Information about the payment validation, like the validation rules and validation statuses. |
| metadata object | Additional data in JSON key:value format. See Metadata. |
| bank_data object | Bank data in JSON key:value format. |
| cbs_data _object | This object contains all relevant information about the payment in the context of the integration with Mambu Core. Learn more in our dedicated guides Mambu Deposits integration and Mambu Lending integration. |
| created_at datetime | The return creation UTC timestamp. |
Below is an example of a return:
{
"id": "a117fdf3-0f5d-46f1-abe8-57b8e78f6226",
"object": "return",
"connected_account_id": "050b18a2-fe5a-47c5-8692-50cf6663c259",
"type": "sepa",
"return_type": "return",
"related_payment_id": "9c95044f-73bb-425e-bf66-74cb3a03647d",
"related_payment_type": "incoming_payment",
"return_reason": "AC04",
"value_date": "2025-10-17",
"returned_amount": 2000,
"currency": "EUR",
"receiving_account_number": "FR6010096000306973462461G47",
"status": "executed",
"status_details": "",
"reconciliation_status": "reconciled",
"reconciled_amount": 2000,
"payment_validation": {
"status": "successful",
"validation_results": [{
"payment_validation_rule_id": "f1613230-50d6-49cd-89d1-0f019f71f7c7",
"status": "successful",
"validations": [
[{
"type": "liquidity_screening",
"status": "successful",
"status_details": "balance correct",
"resource_id": "123-ABC",
"resource_url": "my-liquidity.com/123-ABC"
}],
[{
"type": "sanctions_screening",
"status": "successful",
"status_details": "no match",
"resource_id": "DEF-456",
"resource_url": "my-sanction.com/DEF-456"
}]
]
}]
},
"metadata": {},
"bank_data": {
"file_id": "9ac03610-02b6-421c-958a-de17088b1901",
"message_id": "7d0665620d",
"transaction_id": "dfe7eb0b9c",
"end_to_end_id": "1061b6c83f"
},
"cbs_data": {
"transactions": [{
"id": "1534",
"type": "withdrawal",
"channel": "cash",
"context": "deposit",
"booked_at": "2026-03-03T13:04:12.886736405Z",
"account_id": "JELM775",
"external_id": "019cb3cc-3b38-7d0a-b2be-58e8aeea2486",
"authorization_id": "bcee9199-3194-449c-bd73-750e4d3454e6"
}],
"loan_ids": null,
"credit_arrangement_id": null
},
"created_at": "2025-10-17T15:12:20.644356Z"
}