Learn how to receive payments with Mambu Payments (formerly Numeral)
An incoming payment is a payment received in a pacs.008 / MT103 (credit transfer), pacs.003 (direct debit), or any other message. Mambu Payments (formerly Numeral) receives payments from your partner banks and CSMs and creates incoming payments. Incoming payments are sent to your webhooks as events.
Incoming payments are only available to indirect and direct participants to payment schemes.
| Attribute | Description |
|---|---|
| id string | The incoming payment ID. |
| object string | Always incoming_payment. |
| connected_account_id string | The ID of the connected account that receives the incoming payment. |
| type string | The payment scheme or network. Supported types include: sepa, sepa_instant, fps, chaps, bacs, swift |
| direction string | Either credit or debit, from the perspective of the receiving account:- A credit incoming payment debits a counterparty account and credits the receiving account- A debit incoming payment credits a counterparty account and debits the receiving accountCombined with the payment order type, the direction indicates the payment scheme or method used. For instance:- An incoming payment with type = sepa and direction = credit is a SEPA credit transfer- An incoming payment with type = sepa and direction = debit is a SEPA direct debit- An incoming payment with type = fps and direction = credit is a Faster Payments credit transfer- An incoming payment with type = bacs and direction = debit is a Bacs direct debit |
| amount integer | The payment amount, in the currency's smallest unit. For instance, euro smallest unit is cents and €20 is thus represented as 2000. |
| currency string | The payment currency. EUR and GBP are currently supported. |
| reference string | The payment reference as it appears on the originating account and receiving account statements, with a maximum of 140 characters. |
| purpose string | The purpose code of the payment, ensuring compliance with regulatory requirements of certain beneficiary countries. |
| category_purpose_code string | The category purpose of the payment. |
| uetr string | Unique End-to-end Transaction Reference (UETR). Can be used to track payments with Swift GPI. |
| originating_account object | The account originating the payment. The originating_account object includes the following attributes:- account_number: the account number of the originating account- bank_code: the BIC / Swift code or sort code, depending on the country and bank. Only upper case letters are allowed- holder_name: the name of the company or individual holding the account- creditor_identifier: the creditor identifier or service user number (SUN), in case of SEPA or Bacs direct debit payments- holder_address: the account holder address, as an address object- organization_identification: the account organization identification, as an organization identification object- private_identification: the account private identification, as a private identification object |
| receiving_account object | The account receiving the payment: - If direction = credit, the receiving account is the account to credit- If direction = debit, the receiving account is the account to debitThe receiving_account object includes the following attributes:- account_number: the account number of the receiving account- bank_code: the BIC / Swift code or sort code. Only upper case letters are allowed- holder_name: the name of the company or individual holding the account- holder_address: the address of the account holder, as an address object- organization_identification: the account organization identification, as an organization identification object- private_identification: the account private identification, as a private identification object |
| receiving_account_id string | The ID of the Internal account that receives the payment, when successfully detected. |
| direct_debit_mandate object | The mandate authorizing the direct debit, only for direct debit payments. The direct_debit_mandate object includes the following attributes:- reference: the mandate reference. It will appear on the account statement of the account debited- signature_date: the mandate signature date- type: the mandate type, either sepa_core, sepa_b2b, or bacs_debit- sequence: the mandate sequence, either first, recurring, one_off or final |
| direct_debit_mandate_id string | The direct debit mandate ID. |
| value_date date | The incoming payment value date. |
| requested_execution_date date | The incoming payment requested execution date. |
| initiated_at datetime | The payment order initiation UTC timestamp with ISO 8601 format to the milliseconds without trailing zeros. Only supported for sepa_instant payments. |
| status string | The incoming status payment. It is updated as the incoming payment is processed. See Incoming payment lifecycle for a comprehensive list of incoming payment statuses. |
| status_details string | The incoming payment status details. |
| reconciliation_status string | The incoming payment reconciliation status. Either unreconciled, reconciled, or partially_reconciled. |
| reconciled_amount integer | The amount reconciled, calculated as the sum of the reconciliations created for this incoming payment. |
| 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. This object contains banking information managed by Mambu Payments (formerly Numeral) and comes from the originating bank that sent the payment. This includes fields such as end_to_end_id which are set according to banking protocols. |
| created_at datetime | The UTC creation timestamp of the incoming payment. |
Below are examples of incoming payments:
{
"id": "6607e355-7d2c-588b-9deb-403b0a91f89b",
"object": "incoming_payment",
"connected_account_id": "eca92b9e-6725-4233-9943-5e9bbf033e9c",
"type": "sepa",
"direction": "credit",
"amount": 5000,
"currency": "EUR",
"reference": "Payment ID 1zVrqOXmCS",
"purpose": "SALA",
"category_purpose_code": "B2B",
"originating_account": {
"account_number": "FR7688511000011234567890107",
"bank_code": "BNPAFRPP",
"holder_name": "PartnerCo",
"creditor_identifier": "",
"holder_address": {
"line_1": "119, avenue du General Michel Bizot",
"line_2": "75012 Paris",
"postal_code": "",
"region_state": "",
"city": "Paris",
"country": "FR"
},
"organization_identification": {
"legal_entity_identifier": "L3I9ZG2KFGXZ61BMYR72"
}
},
"receiving_account": {
"account_number": "FR7688511000011234567890107",
"bank_code": "SOGEFRPP",
"holder_name": "TechCo",
"holder_address": {
"line_1": "1, rue de la Paix",
"line_2": "",
"postal_code": "75001",
"region_state": "",
"city": "Paris",
"country": "FR"
},
"organization_identification": {
"legal_entity_identifier": "L3I9ZG2KFGXZ61BMYR72"
}
},
"receiving_account_id": "5223b2a0-919f-4bb0-baf3-ea866c222fef",
"direct_debit_mandate": {},
"direct_debit_mandate_id": "",
"value_date": "2022-01-03",
"requested_execution_date": "",
"status": "received",
"status_details": "",
"reconciled_amount": 5000,
"reconciliation_status": "reconciled",
"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": {
"end_to_end_id": "1zVrqOXmCS",
"file_id": "6fc0018b-4c4a-5d50-9f61-a054a1960bd9",
"message_id": "RirbvB2eEi",
"transaction_id": "1zVrqOXmCS"
},
"created_at": "2024-10-03T14:18:03.841642Z"
}{
"id": "6607e355-7d2c-588b-9deb-403b0a91f89b",
"object": "incoming_payment",
"connected_account_id": "eca92b9e-6725-4233-9943-5e9bbf033e9c",
"type": "sepa_instant",
"direction": "credit",
"amount": 5000,
"currency": "EUR",
"reference": "Payment ID 1zVrqOXmCS",
"originating_account": {
"account_number": "FR7688511000011234567890107",
"bank_code": "BNPAFRPP",
"holder_name": "PartnerCo",
"holder_address": {
"line_1": "119, avenue du General Michel Bizot",
"line_2": "75012 Paris",
"postal_code": "",
"region_state": "",
"city": "Paris",
"country": "FR"
},
"organization_identification": {
"legal_entity_identifier": "L3I9ZG2KFGXZ61BMYR72"
}
},
"receiving_account": {
"account_number": "FR7688511000011234567890107",
"bank_code": "SOGEFRPP",
"holder_name": "TechCo",
"holder_address": {
"line_1": "1, rue de la Paix",
"line_2": "",
"postal_code": "75001",
"region_state": "",
"city": "Paris",
"country": "FR"
},
"organization_identification": {
"legal_entity_identifier": "L3I9ZG2KFGXZ61BMYR72"
}
},
"direct_debit_mandate": {},
"direct_debit_mandate_id": "",
"value_date": "2022-01-03",
"requested_execution_date": "",
"status": "confirmed",
"status_details": "",
"reconciled_amount": 5000,
"reconciliation_status": "reconciled",
"metadata": {},
"bank_data": {
"end_to_end_id": "1zVrqOXmCS",
"file_id": "6fc0018b-4c4a-5d50-9f61-a054a1960bd9",
"message_id": "RirbvB2eEi",
"transaction_id": "1zVrqOXmCS"
},
"created_at": "2022-01-03T14:18:03.841642Z"
}{
"id": "6607e355-7d2c-588b-9deb-403b0a91f89b",
"object": "incoming_payment",
"connected_account_id": "eca92b9e-6725-4233-9943-5e9bbf033e9c",
"type": "sepa",
"direction": "debit",
"amount": 5000,
"currency": "EUR",
"reference": "Payment ID 1zVrqOXmCS",
"originating_account": {
"account_number": "FR7688511000011234567890107",
"bank_code": "BNPAFRPP",
"holder_name": "PartnerCo",
"creditor_identifier": "FR12ZZZ123456",
"holder_address": {
"line_1": "119, avenue du General Michel Bizot",
"line_2": "75012 Paris",
"postal_code": "",
"region_state": "",
"city": "Paris",
"country": "FR"
},
"organization_identification": {
"legal_entity_identifier": "L3I9ZG2KFGXZ61BMYR72"
}
},
"receiving_account": {
"account_number": "FR7688511000011234567890107",
"bank_code": "SOGEFRPP",
"holder_name": "TechCo",
"holder_address": {
"line_1": "1, rue de la Paix",
"line_2": "",
"postal_code": "75001",
"region_state": "",
"city": "Paris",
"country": "FR"
},
"organization_identification": {
"legal_entity_identifier": "L3I9ZG2KFGXZ61BMYR72"
}
},
"direct_debit_mandate": {
"reference": "78jjeEr533re",
"signature_date": "2022-07-14",
"type": "sepa_core",
"sequence": "recurring"
},
"direct_debit_mandate_id": "fc57af6a-2545-11ee-be56-0242ac120002",
"value_date": "2022-01-03",
"requested_execution_date": "2022-01-06",
"status": "received",
"status_details": "",
"reconciled_amount": 5000,
"reconciliation_status": "reconciled",
"metadata": {},
"bank_data": {
"end_to_end_id": "1zVrqOXmCS",
"file_id": "6fc0018b-4c4a-5d50-9f61-a054a1960bd9",
"message_id": "RirbvB2eEi",
"transaction_id": "1zVrqOXmCS"
},
"created_at": "2022-01-03T14:18:03.841642Z"
}