PaymentInstructionValidation

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/swift/json-schema/swift-payment-instruction-validation-schema.json",
  "title": "PaymentInstructionValidation",
  "description": "Payment instruction validation providing a comprehensive view of the overall payment, including the results of the individual validations performed.\n",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/swift-payment-pre-validation-api-openapi.yml#/components/schemas/PaymentInstructionValidation",
  "required": [
    "payment_instruction_validation_result",
    "validation_summary"
  ],
  "type": "object",
  "properties": {
    "uetr": {
      "type": "string",
      "description": "Unique end to end transaction reference of a payment. The type is Universally Unique Identifier (UUID) version 4, as described in IETC RFC 4122 \"Universally Unique Identifier (UUID) URN Namespace\".\n",
      "format": "uuid"
    },
    "payment_instruction_validation_result": {
      "type": "string",
      "description": "This is the overall payment level result of the validations performed. It can have one of the below values \n\n`ERROR` - validations performed, resulting in at least one error response from the underlying data element validations.\n\n`WARNING` - validations performed, resulting in at least one warning from the underlying data element validations but no errors returned.\n\n`ALL_VALID` - all validations in the scope of this service, that were performed on the data elements, were successful.\n\n`PARTIALLY_VALIDATED` - some validations performed were successful. However, some validations could not be performed as source data was not available. But there were no errors returned for any of the underlying data element validations.\n\n`N/A` - Could not validate the payment instruction data elements, in the scope of this service, as source data was not available to perform any of the validations.\n",
      "enum": [
        "ERROR",
        "WARNING",
        "ALL_VALID",
        "PARTIALLY_VALIDATED",
        "N/A"
      ]
    },
    "validation_summary": {
      "$ref": "#/$defs/PaymentInstructionValidation_validation_summary"
    },
    "validations": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ValidationCheck"
      }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "PaymentInstructionValidation_validation_summary": {
      "required": [
        "ERROR_count",
        "N/A_count",
        "VALID_count",
        "WARNING_count",
        "service_error_count"
      ],
      "type": "object",
      "properties": {
        "ERROR_count": {
          "type": "string",
          "description": "Number of unsuccessful validations returned as a result of validating the payment instruction data elements.\n\nW3C XML Schema Built-in datatype \"nonNegativeInteger\".\n"
        },
        "WARNING_count": {
          "type": "string",
          "description": "Number of warnings returned as a result of validating the payment instruction data elements.\n\nW3C XML Schema Built-in datatype \"nonNegativeInteger\".\n"
        },
        "VALID_count": {
          "type": "string",
          "description": "Number of successful validations returned as a result of validating the payment instruction data elements.\n\nW3C XML Schema Built-in datatype \"nonNegativeInteger\".\n"
        },
        "N/A_count": {
          "type": "string",
          "description": "Number of validations that could not be performed as source data was not available.\n\nW3C XML Schema Built-in datatype \"nonNegativeInteger\".\n"
        },
        "service_error_count": {
          "type": "string",
          "description": "Number of technical errors resulting in a HTTP 400/500 response. These are the back-end service errors encountered when performing a validation and eventually the validation hasn't been performed. These service errors will not be considered for deriving the overall 'payment_instruction_validation_result'.\n\nW3C XML Schema Built-in datatype \"nonNegativeInteger\".\n"
        }
      },
      "additionalProperties": false,
      "description": "Summary of results of the validations performed.\n"
    },
    "ValidationCheck": {
      "required": [
        "check_type",
        "reason",
        "result",
        "status",
        "validated_by"
      ],
      "type": "object",
      "properties": {
        "check_type": {
          "type": "string",
          "description": "Identifies uniquely the Validation check being performed. \n\n`Account_Format_Validation` - validates the format of the instructed account identifier against all the formats that apply to the instructed context (country or/and the financial institution that holds the account)\n\n`Beneficiary_Account_Verification` - verifies that an account exists and is capable of receiving incoming funds. The service uses the beneficiary bank subscribed as data provider to perform the account verification (BAV) that usually implies that the account is open, properly identified by the given number and, depending on the jurisdiction and market practices in use where the account is held, that the creditor name matches the name of the account holder. When the beneficiary bank is not subscribed as data provider, SWIFT will use the pseudonymized account statistics (CBAV) to perform the account number verification that implies that the account exists and is likely to receive funds. SWIFT and the beneficiary banks subscribed as data provider do not take liability for the response and do not provide any guarantee on the outcome of an actual transaction being sent to this account. The information provided is meant to be as accurate as possible at the time that the request was processed.\n\n`Category_Purpose_Validation` - validates the instructed category purpose code against the list of category purpose codes available in the SWIFT reference data for the instructed payment context (creditor country).\n\n`Financial_Institution_Identity_Validation` - validates if the instructed institution is registered in the SWIFT reference data as financial institution.\n\n`Instructed_Amount_Validation` - validates the instructed amount against the requirements available in the SWIFT reference data for the instructed creditor agent country and payment market infrastructure.\n\n`Payment_Purpose_Validation` - validates the instructed information regarding the purpose of the payment based on the specific requirements available in the SWIFT repository, for the instructed payment context (creditor agent country, currency and local payment instrument).\n",
          "enum": [
            "Account_Format_Validation",
            "Beneficiary_Account_Verification",
            "Category_Purpose_Validation",
            "Financial_Institution_Identity_Validation",
            "Instructed_Amount_Validation",
            "Payment_Purpose_Validation"
          ]
        },
        "validated_by": {
          "type": "string",
          "description": "Indicates who is performing the check - if the check is performed by SWIFT centrally, or in collaboration with other institution, which in the payment validation case are the creditor agents.\n",
          "enum": [
            "SWIFT_CENTRALLY",
            "CREDITOR_AGENT"
          ]
        },
        "status": {
          "type": "string",
          "description": "Indicates the status of the individual payment validation check.\n\n`FVAL_valid` - The payment information instructed for validation is valid in the instructed payment context. \n\n`CVAL_valid_with_comments` - The payment information instructed for validation is valid but the instructed payment context can be further improved.\n\n`IVAL_invalid` - The payment information instructed for validation is not valid in the instructed payment context.\n\n`NAVL_not_available` - The validation of the instructed payment information is not available in the instructed payment context, typically due to payment data collection process being in progress and insufficient data coverage.\n\n`CNPR_could_not_perform` - The validation of the instructed payment information could not be performed in the instructed payment context typically due to missing payment context information.\n\n`NOAP_not_applicable` - The validation of the instructed payment information has not been applied because it is not applicable for the given context.\n\n`NOMN_not_mandated` - There is no mandate regarding the instructed payment information registered in the SWIFT repository for the given context.  \n\n`UNRE_unrecognised` - The payment information instructed for validation has not been found in the SWIFT repository for the instructed payment context.\n\n`ISMN_is_mandated` - There is a mandate regarding the instructed payment information registered in the SWIFT repository for the given context.\n\n\nBelow status are specific to *Beneficiary Account Verification* check, wherein the beneficiary bank is the data provider and has provided the response. Hence, the below status should be interpreted in the context of 'validated_by' indicator having the value as 'CREDITOR_AGENT'.\n\n`FAIL` - The account identification provided was not successfully validated to an account that can receive funds.\n\n`INCO` - The account identification provided was successfully validated to an account that can receive funds, however, some additional account checks will be performed at transaction time.\n\n`PASS` - The account identification was successfully validated to an account that can receive funds.\n\n`WARN` - The account identification was not successfully validated to an account that can receive funds, however, the responder lacks some information to provide a definite answer.\n\n\nBelow status are specific to *Central Beneficiary Account Verification* or CBAV, wherein the beneficiary bank is not a data provider and SWIFT has used the pseudonymized account statistics to perform the account number verification, that implies that the account exists and is likely to receive funds. Hence, the below status should be interpreted in the context of 'validated_by' indicator having the value as 'SWIFT_CENTRALLY'.\n\n`INCO` - Transactions with this beneficiary account were found in the transaction history and all these transaction were successful or did not fail due to invalid beneficiary account details.\n\n`WARN` - In the history there are transactions with this beneficiary account that were rejected due to a problem related to the account.\n\n`NAVL` - No transactions with this account found in the transaction history.\n",
          "enum": [
            "FVAL_valid",
            "CVAL_valid_with_comments",
            "IVAL_invalid",
            "NAVL_not_available",
            "CNPR_could_not_perform",
            "NOAP_not_applicable",
            "NOMN_not_mandated",
            "UNRE_unrecognised",
            "ISMN_is_mandated",
            "FAIL",
            "INCO",
            "PASS",
            "WARN",
            "NAVL"
          ]
        },
        "reason": {
          "type": "array",
          "description": "The reason(s) behind the status of the individual payment purpose validation check.\n\nBelow reasons are for *Account_Format_Validation* check:\n\n*AINP_account_data_collection_in_progress* - SWIFT account format data coverage index indicates that the account data collection process is in progress (below 90% level of completion).\n\n*CCTY_consistent_country* - The instructed country code matches the country of the payment information that is subject to validation.\n\n*CFIN_consistent_financial_institution_identification* - The instructed financial institution matches the financial institution that uses the account format of the instructed account.\n\n*INCT_inconsistent_country* - The instructed country code does not match the country of the payment information that is subject to validation.\n\n*IFIN_inconsistent_financial_institution_identification* - The instructed financial institution identifier does not match the  financial institution that owns the account that is the subject to the account format validation.\n\n*IBBN_invalid_bban* - The instructed account identifier subject to account format validation does not have a valid Basic Bank Account Number (BBAN) format for the instructed payment context.\n\n*IBIC_invalid_bic* - The instructed financial institution identifier subject to financial institution identity validation is not a  valid BIC for the instructed payment context.\n\n*ICTY_invalid_country* - Instructed country code is not a valid country code on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).\n\n*IDOM_invalid_domestic_bank_specific* - The instructed account identifier subject to account format validation does not have a valid domestic, bank specific format (nor national domestic standard nor bank specific standard) for the instructed payment context.\n\n*IIBN_invalid_iban* - The instructed account identifier subject to account format validation does not have a valid IBAN format for the instructed payment context.\n\n*ICCH_check_not_applied* - The individual payment validation check has not been applied for the instructed context. Other individual payment validation checks are more relevant and will be applied instead.\n\n*MCTY_missing_country_code* - Country code is missing from the payment context in order for the validation of the instructed payment information to be performed.\n\n*MFIN_missing_financial_institution_identifier* - Financial Institution Identifier is missing from the payment context in order for the validation of the instructed payment information to be performed.\n\n*UCSM_unrecognized_clearing_system_member_identification* - The instructed financial institution identifier subject to financial institution identity validation has not been found in the SWIFT directory for the instructed payment context.\n\n*VBBN_valid_bban* - The instructed account identifier subject to account format validation has a valid Basic Bank Account Number (BBAN) format for the instructed payment context.\n\n*VDOM_valid_domestic_bank_specific* - The instructed account identifier subject to account format validation has a valid domestic, bank specific format (national domestic standard or bank specific standard) for the instructed payment context.\n\n*VIBN_valid_iban* - The instructed account identifier subject to account format validation has a valid IBAN format for the instructed payment context.\n\n\nBelow reasons are for *Beneficiary_Account_Verification* check, wherein the beneficiary bank is the data provider (BAV) and has provided the response:\n\nBAV:\n\n*creditor_account_match = MTCH/NMTC* - the creditor account match response code.\n\n*creditor_name_match = MTCH/MBAM/NMTC/NOAP/NOTC* - the creditor name match response code.\n\n*creditor_address_match =  NOAP/NOTC* - the creditor address match response code.\n\n*creditor_organisation_identification_match =  MTCH/NMTC/NOAP/NOTC* - the creditor organisation identification match response code.\n(MTCH-Match, NMTC-No match, MBAM-Maybe a match, NOAP-Not applicable, NOTC-Not checked)\n\n\nBelow reasons are for *Beneficiary_Account_Verification* check, wherein the beneficiary bank is NOT a data provider and SWIFT has used the pseudonymized account statistics (CBAV) to perform the account number verification:\n\nCBAV:\n\n*INCO, Transactions with this beneficiary account were found in the transaction history and all these transaction were successful or did not fail due to invalid beneficiary account details*\n\n*WARN, In the history there are transactions with this beneficiary account that were rejected due to a problem related to the account*\n\n*NAVL, No transactions with this account found in the transaction history*\n\n\nBelow reasons are for *Category_Purpose_Validation* check:\n\n*CINP_no_category_purpose_data_available* - No category purpose data available in the SWIFT repository for the instructed context. This may relate to the country specific requirements not mandating category purpose codes for the instructed context.\n\n*ICTY_invalid_country* - Instructed country code is not a valid country code on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).\n\n*UPCP_unrecognized_category_purpose* - The instructed payment category purpose subject to validation could not be found in the payment category purpose data available in the SWIFT repository for the instructed payment context.\n\n*VPCP_valid_category_purpose* - The instructed payment category purpose subject has been successfully validated for the instructed payment context.\n\n\nBelow reasons are for *Financial_Institution_Identity_Validation* check:\n\n*CCTY_consistent_country* - The instructed country code matches the country of the payment information that is subject to validation.\n\n*INCT_inconsistent_country* - The instructed country code does not match the country of the payment information that is subject to validation.\n\n*IBIC_invalid_bic* - The instructed financial institution identifier subject to financial institution identity validation is not a  valid BIC for the instructed payment context.\n\n*ICTY_invalid_country* - Instructed country code is not a valid country code on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).\n\n*MCTY_missing_country_code* - Country code is missing from the payment context in order for the validation of the instructed payment information to be performed.\n\n*UCSM_unrecognized_clearing_system_member_identification* - The instructed financial institution identifier subject to financial institution identity validation has not been found in the SWIFT directory for the instructed payment context.\n\n*VBIC_valid_bic* - The instructed financial institution identifier subject to financial institution identity validation is a valid BIC for the instructed payment context.\n\n*VCSM_valid_clearing_system_member_identification* - The instructed financial institution identifier subject to financial institution identity validation is a valid clearing system member identifier for the instructed payment context.\n\n\nBelow reasons are for *Instructed_Amount_Validation* check:\n\n*AALP_amount_above_pmi_limit_per_payment* - The instructed amount subject to validation has exceeded the per-transaction limit imposed by the Payment Market Infrastructure (PMI).\n\n*ABLP_amount_below_pmi_limit_per_payment* - The instructed amount subject to validation is below the per-transaction limit imposed by the Payment Market Infrastructure (PMI).\n\n*DACD_amount_decimals_do_not_match_currency_decimals* - Instructed amount has a number of decimals that is different from the number of decimals advised for the instructed currency.\n\n*DBCD_amount_decimals_match_currency_decimals* - Instructed amount has a number of decimals that matches exactly the number of decimals advised for the instructed currency.\n\n*AWPL_amount_within_pmi_limits* - The instructed amount subject to validation is within the per-transaction limits imposed by the instruct context.\n\n*ICCY_invalid_currency_code* - Instructed currency code is not a valid ISO currency code.\n\n*PMIP_pmi_data_collection_in_progress* - SWIFT is in the process of collecting additional data with regards to the instructed Payment Market Infrastructure.\n\n*UCSI_unrecognized_clearing_system_identification* - Instructed clearing system identifier has not been found in the SWIFT directory for the instructed payment context.\n\n\nBelow reasons are for *Payment_Purpose_Validation* check:\n\n*ICCH_check_not_applied* - The individual payment validation check has not been applied for the instructed context. Other individual payment validation checks are more relevant and will be applied instead.\n\n*ICCY_invalid_currency_code* - Instructed currency code is not a valid ISO currency code.\n\n*ICTY_invalid_country* - Instructed country code is not a valid country code on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code).\n\n*MCCC_missing_currency_code* - Currency code  is missing from the payment context in order for the validation of the instructed payment information to be performed.\n\n*MCSI_missing_clearing_system_identifier* - Clearing system identifier  is missing from the payment context in order for the validation of the instructed payment information to be performed.\n\n*MPPC_missing_payment_purpose_code* - Payment Purpose code has not been instructed for the payment validation to be performed.\n\n*MPPD_missing_purpose_description* - There are specific rules for the provided context that require the presence of the payment purpose description which is missing from the payment purpose validation request.\n\n*PCME_purpose_code_description_max_length_exceeded* - Instructed payment purpose code description has exceeded the mandated maximum length registered in the SWIFT repository for the given context.\n\n*PINP_no_purpose_code_data_available* - No purpose code data available in the SWIFT repository for the instructed context. This may relate to the country specific requirements not mandating purpose codes for the instructed context.\n\n*PPNM_payment_purpose_not_mandatory* - Payment purpose code or description is not mandatory.\n\n*PPNR_payment_purpose_not_mandatory_but_recommended* - Payment purpose code or description is not mandatory but one or both are recommended.\n\n*PPMT_payment_purpose_mandatory_above_pmi_amount_threshold* - Payment purpose code or description is mandatory if the instructed amount is above the amount threshold set by the PMI (Payment Market Infrastructure).\n\n*UCSI_unrecognized_clearing_system_identification* - Instructed clearing system identifier has not been found in the SWIFT directory for the instructed payment context.\n\n*UPPC_unrecognized_purpose_code* - The instructed payment purpose code subject to validation could not be found in the purpose code data available in the SWIFT repository for the instructed payment context.\n\n*VPPC_valid_purpose_code* - The instructed payment purpose code has been successfully validated against the purpose  code list(s) available in the SWIFT repository for the instructed payment context.\n\n*VPPD_valid_purpose_description* - The instructed payment purpose description has been successfully validated according to the specific requirements available in the SWIFT repository for the instructed context.\n",
          "items": {
            "maxLength": 280,
            "minLength": 1,
            "type": "string"
          }
        },
        "result": {
          "type": "string",
          "description": "Result of the validation check.\n\n`ERROR` - The validation performed resulted in invalid result.\n\n`WARNING` - Not completely valid, something is missing or inconsistent.\n\n`N/A` - SWIFT has no data available to validate against.\n\n`VALID` - It has been validated, there is no error nor any missing information.\n\n`service_error` - There was a technical error resulting in a HTTP 400/500 response. These are the back-end service errors encountered when performing a validation and eventually the validation hasn't been performed.\n",
          "enum": [
            "ERROR",
            "WARNING",
            "N/A",
            "VALID",
            "service_error"
          ]
        },
        "validated_payment_elements": {
          "type": "array",
          "description": "Details about the specific data elements of the payment instruction that has been validated. This can have the below values:\n\"instructed_amount\"\n\"clearing_system_identification\"\n\"debtor_agent_country\"\n\"creditor_agent.bicfi\"\n\"creditor_agent.clearing_system_member_identification\"\n\"creditor_agent_country\"\n\"creditor_agent_branch_identification\"\n\"creditor.name\"\n\"creditor.postal_address\"\n\"creditor.identification\"\n\"creditor_account\"\n\"purpose_code\"\n\"purpose_description\"\n\"category_purpose_code\"\n",
          "items": {
            "maxLength": 140,
            "minLength": 1,
            "type": "string"
          }
        },
        "additional_information": {
          "maxLength": 2048,
          "minLength": 1,
          "type": "string",
          "description": "This is a generic field to return any other relevant detail for the validation performed. One of the use cases identified is for the Beneficiary Account Verification in the Payment Instruction validation service, wherein this field would include the actual Creditor Name from the Creditor Agent if the Creditor Agent verified the name provided in the request.\n"
        }
      },
      "additionalProperties": false,
      "description": "Details of the outcome of each individual checks performed.\n"
    }
  }
}