Incoming payment object

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 accounts debits the receiving account Combined 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 debit The `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. 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"
}