How to test pain.002 messages

pain.002 message testing verifies that a CustomerPaymentStatusReport is well-formed, conforms to the required ISO 20022 version and scheme rules, and reports the correct status for the original payment instruction. Tests should check message references, status levels, reason information and downstream handling, since a syntactically valid report can still be inconsistent with the payment or its actual processing state.

What a pain.002 message reports

A pain.002 message carries status information about a customer payment initiation, commonly a pain.001 credit transfer instruction. It can report status at group, payment-information or individual-transaction level, depending on the message version and implementation profile. A group-level status summarises the batch; transaction-level details can identify different outcomes within it.

Status values and their permitted use depend on the applicable ISO 20022 message version and scheme profile. For example, a report may indicate acceptance, pending processing or rejection. Treat the target bank or payment scheme's implementation guide as the authority for allowed codes, mandatory fields and status transitions. An acceptance status alone does not prove that funds have settled: verify the meaning defined by the profile and the processing outcome in the system under test.

Build a pain.002 message testing checklist

Start by recording the message version, namespace, scheme profile and transport format expected by the receiving application. Validate the XML (Extensible Markup Language) for well-formedness, then validate it against the relevant XSD (XML Schema Definition). Schema validation catches structural errors such as missing mandatory elements, invalid element order and values with the wrong data type. It does not establish that references or business outcomes are correct.

Add profile and business-rule checks. Confirm that the message identifier is present and unique where required, and that original-message references identify the payment instruction being reported. Check that the original message name and identifiers match the submitted payment, including payment-information and transaction references when those levels are present. Validate status codes, reason codes, dates and any required supplementary information against the agreed profile.

Test status consistency across levels. If a report contains both a group status and transaction details, assert that their combination is permitted by the profile. For a partial outcome, check that each transaction has an unambiguous status and that the system does not treat the whole batch as uniformly successful. Verify that rejection details reach the correct transaction or payment record and support the expected repair or customer-notification workflow.

Verify correlation and processing behaviour

Exercise the full path from payment submission to status handling. Submit a known pain.001 message, capture the resulting pain.002, and compare its original references with the submitted identifiers. Assert the status stored by the payment application, the displayed or returned outcome, and any downstream action such as holding a payment for review. Use controlled test data and an isolated environment so that a test status cannot trigger a real payment.

Include negative and lifecycle cases. Examples include an unknown original message identifier, a mismatched transaction reference, an unsupported status or reason code, a missing mandatory reference, and a report that arrives after the payment has changed state. Confirm that the application rejects, quarantines or flags each case according to its contract, and records enough diagnostic information for investigation. Also test duplicate delivery and out-of-order reports if the interface can receive them; define expected behaviour with the receiving system rather than assuming every report is safe to apply repeatedly.

Worked test example

For a batch containing two transactions, prepare a payment instruction with distinct end-to-end identifiers. Configure the test processor to return a partial outcome, if the target profile supports one. Check that the pain.002 identifies the original instruction and both transactions, assigns each transaction a permitted status, and includes the required rejection reason for the failed item. Then verify that the payment application marks the successful item according to the profile, routes the rejected item to the expected repair path, and leaves no transaction linked to another payment. Repeat with a fully rejected batch and a pending status to cover different processing paths.

Keep test cases traceable to the profile rules and retain the input message, returned report, validation results and application-level assertions as evidence. This separates XML validation defects from correlation failures and incorrect payment-state handling.