APIs

Verification of Payee Requester API

OpenAPI Specification

Verification Of Payee Requester Service API

Exposing the OpenAPI Specification Endpoint

The below should only ever be configured in development/test environments

By default, the OpenAPI specification UI endpoint is not enabled in the application. This can be enabled by setting the following properties in the application configuration:

springdoc.api-docs.enabled = true

spring.web.resources.static-locations = "classpath:/static/"

With the above properties set, the OpenAPI specification will be accessible by hitting the /swagger-ui/index.html path of the running application.

Using the API

The API accepts a JSON request containing the payee’s information and returns a verification result.

What You Need to Provide

  • Payee Information:

    • Name (for individuals) OR Organization ID (for businesses)

    • Account number (IBAN)

    • Bank identifier (BIC) (optional)

      • CSM Reachability is able to retrieve the BIC from the IBAN if not provided

  • Processing Entity (optional) of the Payee’s financial institution

  • Payment Identifiers (optional):

    • Any identifiers you use to track the payment in your systems

What You’ll Receive

  • Verification Result:

    • Success: The payee details match, no reason code will be provided

    • Failure: The details don’t match, with a reason code explaining why

    • Close Match: The name is similar but not an exact match, with the correct name provided

Failure Reason Codes

  • PI01 - The organization ID doesn’t match the account

  • PN01 - The name doesn’t match the account

  • PN02 - The name is similar but not an exact match

  • NORR - A match could not be performed

  • NORQ - If country filtering is enabled, then either the Responder’s Country Code is not present on the configured Country Code list, or the Regulatory date for the Responder’s country has not been reached.

Error Handling

The API provides error responses for the following issues:

HTTP Status Error Description

400

Request validation error

When the provided details are incomplete or do not meet the required format

500

Unknown server error

When an unanticipated error occurs. Additional details can be found in the logs

503

External services cannot be reached

When an external service necessary for verification cannot be reached e.g. Responder, CSM Reachability