SWIFT · Schema

PaymentInstruction

Payment instruction with the data elements forming a partial or complete payment instruction. Validation is carried out on the data elements that are present.

BankingCross-Border PaymentsFinancial MessagingFinancial ServicesGPIISO 20022PaymentsSWIFT

Properties

Name	Type	Description
uetr	string	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".
instructed_amount	object
clearing_system_identification	string	The market infrastructure over which the payment instruction will be/is intended to be cleared.
debtor_agent_country	string	Country of the Financial institution servicing an account for the debtor expressed in 2 character ISO code.
creditor_agent	object
creditor_agent_country	string	Country of the Financial institution servicing an account for the creditor expressed in 2 character ISO code.
creditor_agent_branch_identification	string	Branch Identification of the Financial institution servicing an account for the creditor.
creditor	object
creditor_account	string	Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.
purpose_code	string	Underlying reason for the payment transaction. Usage: Purpose is used by the end-customers, that is initiating party, (ultimate) debtor, (ultimate) creditor to provide information concerning the natur
purpose_description	string	Description of the Underlying reason for the payment transaction, including any further regulatory reporting information that should accompany the payment.
category_purpose_code	string	Specifies the high level purpose of the instruction based on a set of pre-defined categories. Usage: This is used by the initiating party to provide information concerning the processing of the paymen

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/swift/json-schema/swift-payment-instruction-schema.json",
  "title": "PaymentInstruction",
  "description": "Payment instruction with the data elements forming a partial or complete payment instruction. Validation is carried out on the data elements that are present.\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/PaymentInstruction",
  "required": [
    "creditor_account",
    "creditor_agent_country",
    "debtor_agent_country",
    "instructed_amount"
  ],
  "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"
    },
    "instructed_amount": {
      "$ref": "#/$defs/CurrencyAmount"
    },
    "clearing_system_identification": {
      "maxLength": 35,
      "minLength": 1,
      "type": "string",
      "description": "The market infrastructure over which the payment instruction will be/is intended to be cleared.\n"
    },
    "debtor_agent_country": {
      "maxLength": 2,
      "minLength": 2,
      "pattern": "^[A-Z]{2,2}$",
      "type": "string",
      "description": "Country of the Financial institution servicing an account for the debtor expressed in 2 character ISO code.\n",
      "x-Validation": true,
      "x-ValidationType": "Algorithmic, ReferenceData",
      "x-Error": "ErrorCode:Sw.Stds.D00004, ErrorText:Invalid Country Code., SWIFTNetValidation:true,  Severity:Fatal"
    },
    "creditor_agent": {
      "$ref": "#/$defs/FinancialInstitutionIdentification"
    },
    "creditor_agent_country": {
      "maxLength": 2,
      "minLength": 2,
      "pattern": "^[A-Z]{2,2}$",
      "type": "string",
      "description": "Country of the Financial institution servicing an account for the creditor expressed in 2 character ISO code.\n",
      "x-Validation": true,
      "x-ValidationType": "Algorithmic, ReferenceData",
      "x-Error": "ErrorCode:Sw.Stds.D00004, ErrorText:Invalid Country Code., SWIFTNetValidation:true,  Severity:Fatal"
    },
    "creditor_agent_branch_identification": {
      "maxLength": 35,
      "minLength": 1,
      "type": "string",
      "description": "Branch Identification of the Financial institution servicing an account for the creditor.\n"
    },
    "creditor": {
      "$ref": "#/$defs/PartyIdentification"
    },
    "creditor_account": {
      "maxLength": 34,
      "minLength": 1,
      "type": "string",
      "description": "Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.\n"
    },
    "purpose_code": {
      "maxLength": 35,
      "minLength": 1,
      "type": "string",
      "description": "Underlying reason for the payment transaction. Usage: Purpose is used by the end-customers, that is initiating party, (ultimate) debtor, (ultimate) creditor to provide information concerning the nature of the payment.\n"
    },
    "purpose_description": {
      "maxLength": 140,
      "minLength": 1,
      "type": "string",
      "description": "Description of the Underlying reason for the payment transaction, including any further regulatory reporting information that should accompany the payment.\n"
    },
    "category_purpose_code": {
      "maxLength": 35,
      "minLength": 1,
      "type": "string",
      "description": "Specifies the high level purpose of the instruction based on a set of pre-defined categories.  Usage: This is used by the initiating party to provide information concerning the processing of the payment. It is likely to trigger special processing by any of the agents involved in the payment chain.\n"
    }
  },
  "additionalProperties": false,
  "$defs": {
    "ClearingSystemIdentificationChoice": {
      "type": "object",
      "additionalProperties": true,
      "description": "Choice of a clearing system identifier.\n",
      "oneOf": [
        {
          "required": [
            "code"
          ],
          "type": "object",
          "properties": {
            "code": {
              "maxLength": 5,
              "minLength": 1,
              "type": "string",
              "description": "Specifies the clearing system identification code, as published in an external clearing system identification code list. External code sets can be downloaded from www.iso20022.org..\n",
              "x-MXComponent": "ExternalClearingSystemIdentification1Code"
            }
          },
          "additionalProperties": false
        },
        {
          "required": [
            "proprietary"
          ],
          "type": "object",
          "properties": {
            "proprietary": {
              "maxLength": 35,
              "minLength": 1,
              "type": "string",
              "description": "Identification code for a clearing system, that has not yet been identified in the list of clearing systems.\n"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "ClearingSystemMemberIdentification": {
      "required": [
        "member_identification"
      ],
      "type": "object",
      "properties": {
        "clearing_system_identification": {
          "$ref": "#/$defs/ClearingSystemIdentificationChoice"
        },
        "member_identification": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Identification of a member of a clearing system.\n"
        }
      },
      "additionalProperties": false,
      "description": "Unique identification, as assigned by a clearing system, to unambiguously identify a member of the clearing system.\n"
    },
    "CurrencyAmount": {
      "required": [
        "amount",
        "currency_code"
      ],
      "type": "object",
      "properties": {
        "currency_code": {
          "pattern": "^[A-Z]{3,3}$",
          "type": "string",
          "description": "ISO three character currency code.  The Currency Code must be registered, or have already been registered. Valid active or historic currency codes are registered with the ISO 4217 Maintenance Agency, consist of three (3) contiguous letters, and may be or not be withdrawn on the day the message containing the Currency is exchanged.\n",
          "x-MXComponent": "ActiveOrHistoricCurrencyCode",
          "x-Validation": true,
          "x-ValidationType": "Algorithmic, ReferenceData",
          "x-Error": "ErrorCode:Sw.Stds.D00006, ErrorText:Invalid currency code., SWIFTNetValidation:true, Severity:Fatal"
        },
        "amount": {
          "maxLength": 19,
          "pattern": "^0*(([0-9]{0,13}\\.[0-9]{1,5})|([0-9]{0,14}\\.[0-9]{1,4})|([0-9]{0,15}\\.[0-9]{1,3})|([0-9]{0,16}\\.[0-9]{1,2})|([0-9]{0,17}\\.[0-9]{1,1})|([0-9]{0,18}\\.)|0*|([0-9]{0,18}))$",
          "type": "string",
          "description": "The amount with fractional digit.  The number of fractional digits (or minor unit of currency) must comply with ISO 4217. Note: The decimal separator is a dot.\nUsage:\n  minInclusive: 0\n  totalDigits: 18\n  fractionDigits: 5\n",
          "x-MXComponent": "ActiveOrHistoricCurrencyAndAmount",
          "x-Validation": true,
          "x-ValidationType": "Algorithmic",
          "x-Error": "ErrorCode:Sw.Stds.D00007, ErrorText:Too many decimal digits., SWIFTNetValidation:true  Severity:Fatal"
        }
      },
      "additionalProperties": false,
      "description": "Amount of money to be moved between the debtor and the creditor, before deduction of charges, expressed in the currency as ordered by the initiating party.    Usage: Specify the amount in this field when the amount to be received by the beneficiary is known in the creditor currency.\n"
    },
    "FinancialInstitutionIdentification": {
      "type": "object",
      "properties": {
        "bicfi": {
          "pattern": "^[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}$",
          "type": "string",
          "description": "Code allocated to a financial institution by the ISO 9362 Registration Authority as described in ISO 9362 \"Banking - Banking telecommunication messages - Business identifier code (BIC)\".\n",
          "x-MXComponent": "BICFIDec2014Identifier",
          "x-Validation": true,
          "x-ValidationType": "Algorithmic",
          "x-Error": "ErrorCode:Sw.Stds.D00008, ErrorText:Invalid BIC., SWIFTNetValidation:true  Severity:Fatal"
        },
        "clearing_system_member_identification": {
          "$ref": "#/$defs/ClearingSystemMemberIdentification"
        }
      },
      "additionalProperties": false,
      "description": "Specifies the details to identify a financial institution.\n"
    },
    "GenericOrganisationIdentification": {
      "required": [
        "identification"
      ],
      "type": "object",
      "properties": {
        "identification": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Identification assigned by an institution.\n"
        },
        "scheme_name": {
          "$ref": "#/$defs/OrganisationIdentificationSchemeNameChoice"
        },
        "issuer": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Entity that assigns the identification.\n"
        }
      },
      "additionalProperties": false,
      "description": "Information related to an identification of an organisation.\n"
    },
    "OrganisationIdentification": {
      "type": "object",
      "properties": {
        "bic": {
          "pattern": "^[A-Z0-9]{4,4}[A-Z]{2,2}[A-Z0-9]{2,2}([A-Z0-9]{3,3}){0,1}$",
          "type": "string",
          "description": "Business identification code of the organisation. Code allocated to a financial or non-financial institution by the ISO 9362 Registration Authority, as described in ISO 9362: 2014 - \"Banking - Banking telecommunication messages - Business identifier code (BIC)\".\n",
          "x-MXComponent": "AnyBICDec2014Identifier",
          "x-Validation": true,
          "x-ValidationType": "Algorithmic",
          "x-Error": "ErrorCode:Sw.Stds.D00008, ErrorText:Invalid BIC., SWIFTNetValidation:true  Severity:Fatal"
        },
        "other": {
          "maxItems": 2,
          "type": "array",
          "items": {
            "$ref": "#/$defs/GenericOrganisationIdentification"
          }
        }
      },
      "additionalProperties": false,
      "description": "Unique and unambiguous way to identify an organisation.\n"
    },
    "OrganisationIdentificationSchemeNameChoice": {
      "type": "object",
      "additionalProperties": true,
      "description": "Sets of elements to identify a name of the organisation identification scheme.\n",
      "oneOf": [
        {
          "required": [
            "code"
          ],
          "type": "object",
          "properties": {
            "code": {
              "maxLength": 4,
              "minLength": 1,
              "type": "string",
              "description": "Specifies the external organisation identification scheme name code in the format of character string with a maximum length of 4 characters. The list of valid codes is an external code list published separately. External code sets can be downloaded from www.iso20022.org.\n",
              "x-MXComponent": "ExternalOrganisationIdentification1Code"
            }
          },
          "additionalProperties": false
        },
        {
          "required": [
            "proprietary"
          ],
          "type": "object",
          "properties": {
            "proprietary": {
              "maxLength": 35,
              "minLength": 1,
              "type": "string",
              "description": "Name of the identification scheme, in a free text form.\n"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "PartyIdentification": {
      "type": "object",
      "properties": {
        "name": {
          "maxLength": 140,
          "minLength": 1,
          "type": "string",
          "description": "Name by which a party is known and which is usually used to identify that party.\n"
        },
        "postal_address": {
          "$ref": "#/$defs/PostalAddressChoice"
        },
        "identification": {
          "$ref": "#/$defs/PartyIdentification_identification"
        }
      },
      "additionalProperties": false,
      "description": "Specifies the identification of a person or an organisation.\n"
    },
    "PartyIdentification_identification": {
      "type": "object",
      "properties": {
        "organisation_identification": {
          "$ref": "#/$defs/OrganisationIdentification"
        }
      },
      "additionalProperties": false,
      "description": "Unique and unambiguous identification of a party.\n"
    },
    "PostalAddress": {
      "required": [
        "country",
        "town_name"
      ],
      "type": "object",
      "properties": {
        "department": {
          "maxLength": 70,
          "minLength": 1,
          "type": "string",
          "description": "Identification of a division of a large organisation or building."
        },
        "sub_department": {
          "maxLength": 70,
          "minLength": 1,
          "type": "string",
          "description": "Identification of a sub-division of a large organisation or building."
        },
        "street_name": {
          "maxLength": 70,
          "minLength": 1,
          "type": "string",
          "description": "Name of a street or thoroughfare."
        },
        "building_number": {
          "maxLength": 16,
          "minLength": 1,
          "type": "string",
          "description": "Number that identifies the position of a building on a street."
        },
        "building_name": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Name of the building or house."
        },
        "floor": {
          "maxLength": 70,
          "minLength": 1,
          "type": "string",
          "description": "Floor or storey within a building."
        },
        "post_box": {
          "maxLength": 16,
          "minLength": 1,
          "type": "string",
          "description": "Numbered box in a post office, assigned to a person or organisation, where letters are kept until called for."
        },
        "room": {
          "maxLength": 70,
          "minLength": 1,
          "type": "string",
          "description": "Building room number."
        },
        "post_code": {
          "maxLength": 16,
          "minLength": 1,
          "type": "string",
          "description": "Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail."
        },
        "town_name": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Name of a built-up area, with defined boundaries, and a local government."
        },
        "town_location_name": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Specific location name within the town."
        },
        "district_name": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Identifies a subdivision within a country sub-division."
        },
        "country_sub_division": {
          "maxLength": 35,
          "minLength": 1,
          "type": "string",
          "description": "Identifies a subdivision of a country such as state, region, county."
        },
        "country": {
          "maxLength": 2,
          "minLength": 2,
          "pattern": "^[A-Z]{2,2}$",
          "type": "string",
          "description": "Nation with its own government.",
          "x-Validation": true,
          "x-ValidationType": "Algorithmic, ReferenceData",
          "x-Error": "ErrorCode:Sw.Stds.D00004, ErrorText:Invalid Country Code., SWIFTNetValidation:true,  Severity:Fatal"
        }
      },
      "additionalProperties": false,
      "description": "Information that locates and identifies a specific address."
    },
    "PostalAddressChoice": {
      "type": "object",
      "additionalProperties": true,
      "description": "Postal Address Structured or Unstructured\n",
      "oneOf": [
        {
          "required": [
            "structured"
          ],
          "type": "object",
          "properties": {
            "structured": {
              "$ref": "#/$defs/PostalAddress"
            }
          },
          "additionalProperties": false
        },
        {
          "required": [
            "unstructured"
          ],
          "type": "object",
          "properties": {
            "unstructured": {
              "$ref": "#/$defs/PostalAddressUnstructured"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "PostalAddressUnstructured": {
      "required": [
        "address_line",
        "country"
      ],
      "type": "object",
      "properties": {
        "address_line": {
          "maxItems": 7,
          "type": "array",
          "description": "Information that locates and identifies a specific address, as defined by postal services, presented in free format text.\n",
          "items": {
            "maxLength": 70,
            "minLength": 1,
            "type": "string"
          }
        },
        "country": {
          "maxLength": 2,
          "minLength": 2,
          "pattern": "^[A-Z]{2,2}$",
          "type": "string",
          "description": "Nation with its own government.",
          "x-Validation": true,
          "x-ValidationType": "Algorithmic, ReferenceData",
          "x-Error": "ErrorCode:Sw.Stds.D00004, ErrorText:Invalid Country Code., SWIFTNetValidation:true,  Severity:Fatal"
        }
      },
      "additionalProperties": false,
      "description": "Information that locates and identifies a specific address in an unstructured format.\n"
    }
  }
}

Work with this as data

Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for schemas

4 MCP tools reach this

find_json_schemasBrowse and filter every JSON Schema in the catalog.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This JSON Schema

curl "https://apis.io/api/v1/json-schemas/swift-payment-instruction"

All schemas

curl "https://apis.io/api/v1/json-schemas?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.