Introduction

Payment validation is used to approve or reject payments before they are sent or when they are received. Common payment validations include checking:

The status of an internal account before confirming or rejecting a payment received
If a beneficiary is on a sanctions list before sending a payment
If a direct debit mandate is not blocked when receiving a direct debit payment
If a payment type and an amount are allowed for an internal account

Payment validation rules

Validations are managed via payment validation rules that group and orchestrate the execution of validations for a target payment flow (outgoing SCT Instant, incoming SDD, etc.)

A rule is defined by its:

Criteria, defining the payments (payment orders or incoming payments) this rule will apply to. Supported criteria are connected accounts, payment types, and directions
Validations which is the list of validations to be performed on these payments. Each check has a list of possible outcomes mapped to 3 different actions:
- Move to next validation
- Approve payment order (or confirm incoming payment)
- Cancel payment order (or reject incoming payment)

// Example of a payment validation rule for outgoing SCT Instant, checking whether the internal account is active and performing a PEP screening on the reciving account holder
{
  "id": "7c149cf6-0306-4a45-b48c-b3562c39ab2b",
  "object": "payment_validation_rule",
  "name": "Internal account & PEP screening",
  "scope": "payment_order",
  "criteria": [
    {
      "attribute": "connected_account_id",
      "extra": null,
      "operator": "in",
      "values": ["7c149cf6-0306-4a45-b48c-b3562c39ab2b"]
    },
    {
      "attribute": "payment_direction",
      "extra": null,
      "operator": "equals",
      "values": ["credit"]
    },
    {
      "attribute": "payment_type","extra": null,
      "operator": "equals",
      "values": ["sepa_instant"]
    }
  ],
  "validations":[
    [
      {
        "type": "is_internal_account_active",
        "outcomes": [
          {
            "status": "successful",
            "action": "next_validation"
          },
          {
            "status": "failed",
            "action": "cancel_payment"
          }
        ]
      }
    ],
    [
      {
        "type": "pep_screening",
        "outcomes": [
          {
            "status": "successful",
            "action": "approve_payment"
          },
          {
            "status": "failed",
            "action": "cancel_payment"
          }
        ]
      }
    ]
  ]
}

Validations

Mambu Payments currently supports two types of validations:

Custom validations performed by your systems based on your internal logic and data providers
Pre-built validations performed on Mambu Payments objects and data, like internal accounts, direct debit mandates, external account reachability etc. which can be configured for your business needs

Asynchronous custom validations

Mambu Payments sends an event to your webhook when a validation in your system is required. The result of the validation can be shared using the dedicated API endpoint.

sequenceDiagram
    participant ThirdParty as Third-party service (e.g., ComplyAdvantage)
    participant Customer as Customer
    participant Numeral as Numeral

    Customer->>Numeral: Create payment order
    activate Numeral
    Note over Numeral: Validate payload
    Numeral-->>Customer: payment_order.pending_approval event
    Note over Numeral: Initiate validation
    Numeral-->>Customer: payment_order.validation_updated event
    Note over Numeral: Wait for validation result

    Customer->>ThirdParty: Send validation request
    ThirdParty-->>Customer: Send validation result

    Customer->>Numeral: Update validation result<br/>POST /payment_order/{id}
    Note over Numeral: Finalise validation
    Numeral-->>Customer: payment_order.approved event
    deactivate Numeral

Synchronous payment validation

Mambu Payments calls an endpoint (in your system or in a third-party system). The result of the validation is shared as a response in the HTTP session.

sequenceDiagram
    participant Customer as Customer
    participant Numeral as Numeral

    Customer->>Numeral: Create payment order
    activate Numeral
    Note over Numeral: Validate payload
    Numeral-->>Customer: payment_order.pending_approval event

    Note over Numeral: Send validation request
    Numeral->>Customer: Request
    activate Customer
    Note over Numeral: Wait for response
    Customer-->>Numeral: Response
    deactivate Customer

    Note over Numeral: Finalise validation
    Numeral-->>Customer: payment_order.approved event
    deactivate Numeral

curl --request POST \
     --url https://your-system.com/sanction-screening \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "id": "e19aff61-53ce-4293-9a0a-6996d4995e18",
    "object": "payment_order",
    // The whole payment order is sent. Only a subset of the object is displayed here to enhance clarity.
    "status": "pending_approval",
    "payment_validation": {
        "status": "in_progress",
        "validation_results": [{
            "status": "in_progress",
            "validations": [
                [{
                    "type": "sanction_screening",
                    "status": "in_progress",
                    "resource_id": null,
                    "resource_url": null,
                    "status_details": null
                }],
            ],
            "payment_validation_rule_id": "f1613230-50d6-49cd-89d1-0f019f71f7c7"
        }]
    }
}
'

200

{
  "status": "successful",
  "status_details": "no sanction hit"
}

Pre-built validations

Mambu Payments manages the validations based on your configuration.

sequenceDiagram
    participant Customer as Customer
    participant Numeral as Numeral

    Customer->>Numeral: Create payment order
    activate Numeral
    Note over Numeral: Validate payload
    Numeral-->>Customer: payment_order.pending_approval event
    Note over Numeral: Perform validation on Numeral objects
    Numeral-->>Customer: payment_order.approved event
    deactivate Numeral

Payment validation flow

A payment order created or an incoming payment received include:

A payment validation status
The list of associated payment validation rules and, for each rule, a completion status and the list of associated validations with their status and result

Below is an example of a payment order with 2 payment validations:

// First validation of the internal account status is in progress

{
  "id": "b38f5318-a389-4278-9cbe-d16116750987",
  "object": "payment_order",
  "status": "pending_approval",
  
  // Only a subset of the object is displayed to enhance clarity.
  
  "payment_validation": {
    "status": "in_progress",
    "validation_results": [
      {
        "payment_validation_rule_id": "7c149cf6-0306-4a45-b48c-b3562c39ab2b",
        "status": "in_progress", 
        "validations": [
          [
            {
              "type": "internal_account_is_active",
              "status": "in_progress",
              "status_details": null,
              "resource_id": "some ID",
              "resource_url": "https://someurl.com/someid"
            }
          ],
          [
            {
              "type": "pep_screening",
              "status": "queued",
              "status_details": null,
              "resource_id": null,
              "resource_url": null
            }
          ]
        ]
      }
		]
	}
}

// First validation is successful. Second validation of PEP screening is in progress

{
  "id": "b38f5318-a389-4278-9cbe-d16116750987",
  "object": "payment_order",
  "status": "pending_apprvoal",
  
  // Only a subset of the object is displayed to enhance clarity.
  
  "payment_validation": {
    "status": "in_progress",
    "validation_results": [
      {
        "payment_validation_rule_id": "7c149cf6-0306-4a45-b48c-b3562c39ab2b",
        "status": "in_progress", 
        "validations": [
          [
            {
              "type": "internal_account_is_active",
              "status": "successful",
              "status_details": null,
              "resource_id": "some ID",
              "resource_url": "https://someurl.com/someid"
            }
          ],
          [
            {
              "type": "pep_screening",
              "status": "in_progress",
              "status_details": null,
              "resource_id": "some ID",
              "resource_url": "https://someurl.com/someid"
            }
          ]
        ]
      }
		]
	}
}

// All validations are successful and payment is approved

{
  "id": "b38f5318-a389-4278-9cbe-d16116750987",
  "object": "payment_order",
  "status": "approved",
  
  // Only a subset of the object is displayed to enhance clarity.
  
  "payment_validation": {
    "status": "successful",
    "validation_results": [
      {
        "payment_validation_rule_id": "7c149cf6-0306-4a45-b48c-b3562c39ab2b",
        "status": "successful", 
        "validations": [
          [
            {
              "type": "internal_account_is_active",
              "status": "successful",
              "status_details": null,
              "resource_id": "some ID",
              "resource_url": "https://someurl.com/someid"
            }
          ],
          [
            {
              "type": "pep_screening",
              "status": "successful",
              "status_details": null,
              "resource_id": "some ID",
              "resource_url": "https://someurl.com/someid"
            }
          ]
        ]
      }
		]
	}
}