ISO20022 External Code Sets

This package provides a collection of ISO20022 external code sets used in financial messaging, converted to both JSON format and TypeScript enums for easy integration into modern applications.

It is designed to make it easy to map the Transaction Authorization Protocol into usecases where swift is currently working.

Overview

ISO20022 financial messaging defines numerous external code sets that are maintained outside the schema itself. These code sets define standardized values for various elements within financial messages, such as purpose codes, party types, and other categorization schemes.

This package:

1. Extracts all the external code sets from the ISO20022 specifications
2. Structures them as individual, well-formatted JSON files
3. Generates corresponding TypeScript enum definitions
4. Includes descriptions for each code value where available

Data Source

The data is based on the official ISO20022 External Code Sets publication.

Installation

npm install @taprsvp/iso20022_external_codes

Usage

TypeScript

import { Purpose, ServiceLevel, CategoryPurpose } from '@taprsvp/iso20022_external_codes';

// Use the enums in your code
const purpose = Purpose.CASH;  // "CASH"
const serviceLevel = ServiceLevel.SDVA; // "SDVA"

// Access descriptions via JSDoc in your IDE
// Purpose.CASH will show: "Transaction is a general cash management instruction."

JSON Files

The package also includes JSON files for each code set, which you can use if you need the raw data:

{
  "description": "Specifies the external purpose code in the format of character string with a maximum length of 4 characters.",
  "name": "ExternalPurpose1Code",
  "codes": {
    "ACCT": "Transaction moves funds between 2 accounts of same account holder at the same bank.",
    "CASH": "Transaction is a general cash management instruction.",
    ...
  }
}

Available Code Sets

The package includes 128 code sets from ISO20022, including:

• Purpose (ExternalPurpose1Code) - Purpose codes for payments
• CategoryPurpose (ExternalCategoryPurpose1Code) - Category purpose codes
• ServiceLevel (ExternalServiceLevel1Code) - Service level codes
• DocumentType (ExternalDocumentType1Code) - Document type codes
• And many more...

Each code set is available both as a TypeScript enum and as a JSON file.

Full List of Supported Code Sets

Below is a complete list of all supported ISO20022 external code sets. For each code set, links to both the JSON file and TypeScript enum are provided.

| Code Set | JSON | TypeScript | Original ISO20022 Name | |----------|------|------------|------------------------| | AcceptedReason | JSON | TypeScript | ExternalAcceptedReason1Code | | AccountIdentification | JSON | TypeScript | ExternalAccountIdentification1Code | | AgentInstruction | JSON | TypeScript | ExternalAgentInstruction1Code | | AgreementType | JSON | TypeScript | ExternalAgreementType1Code | | AuthenticationChannel | JSON | TypeScript | ExternalAuthenticationChannel1Code | | AuthenticationMethod | JSON | TypeScript | ExternalAuthenticationMethod1Code | | AuthorityExchangeReason | JSON | TypeScript | ExternalAuthorityExchangeReason1Code | | AuthorityIdentification | JSON | TypeScript | ExternalAuthorityIdentification1Code | | BalanceSubType | JSON | TypeScript | ExternalBalanceSubType1Code | | BalanceType | JSON | TypeScript | ExternalBalanceType1Code | | BenchmarkCurveName | JSON | TypeScript | ExternalBenchmarkCurveName1Code | | BillingBalanceType | JSON | TypeScript | ExternalBillingBalanceType1Code | | BillingCompensationType | JSON | TypeScript | ExternalBillingCompensationType1Code | | BillingRateIdentification | JSON | TypeScript | ExternalBillingRateIdentification1Code | | CalculationAgent | JSON | TypeScript | ExternalCalculationAgent1Code | | CancellationReason | JSON | TypeScript | ExternalCancellationReason1Code | | CashAccountType | JSON | TypeScript | ExternalCashAccountType1Code | | CashClearingSystem | JSON | TypeScript | ExternalCashClearingSystem1Code | | CategoryPurpose | JSON | TypeScript | ExternalCategoryPurpose1Code | | Channel | JSON | TypeScript | ExternalChannel1Code | | ChargeType | JSON | TypeScript | ExternalChargeType1Code | | ChequeCancellationReason | JSON | TypeScript | ExternalChequeCancellationReason1Code | | ChequeCancellationStatus | JSON | TypeScript | ExternalChequeCancellationStatus1Code | | ClaimNonReceiptRejection | JSON | TypeScript | ExternalClaimNonReceiptRejection1Code | | ClearingSystemIdentification | JSON | TypeScript | ExternalClearingSystemIdentification1Code | | ContractBalanceType | JSON | TypeScript | ExternalContractBalanceType1Code | | ContractClosureReason | JSON | TypeScript | ExternalContractClosureReason1Code | | CorporateActionEventType | JSON | TypeScript | ExternalCorporateActionEventType1Code | | CreditorAgentInstruction | JSON | TypeScript | ExternalCreditorAgentInstruction1Code | | CreditorEnrolmentAmendmentReason | JSON | TypeScript | ExternalCreditorEnrolmentAmendmentReason1Code | | CreditorEnrolmentCancellationReason | JSON | TypeScript | ExternalCreditorEnrolmentCancellationReason1Code | | CreditorEnrolmentStatusReason | JSON | TypeScript | ExternalCreditorEnrolmentStatusReason1Code | | CreditorReferenceType | JSON | TypeScript | ExternalCreditorReferenceType1Code | | DateFrequency | JSON | TypeScript | ExternalDateFrequency1Code | | DateType | JSON | TypeScript | ExternalDateType1Code | | DebtorActivationAmendmentReason | JSON | TypeScript | ExternalDebtorActivationAmendmentReason1Code | | DebtorActivationCancellationReason | JSON | TypeScript | ExternalDebtorActivationCancellationReason1Code | | DebtorActivationStatusReason | JSON | TypeScript | ExternalDebtorActivationStatusReason1Code | | DebtorAgentInstruction | JSON | TypeScript | ExternalDebtorAgentInstruction1Code | | DeviceOperatingSystemType | JSON | TypeScript | ExternalDeviceOperatingSystemType1Code | | DiscountAmountType | JSON | TypeScript | ExternalDiscountAmountType1Code | | DocumentAmountType | JSON | TypeScript | ExternalDocumentAmountType1Code | | DocumentFormat | JSON | TypeScript | ExternalDocumentFormat1Code | | DocumentLineType | JSON | TypeScript | ExternalDocumentLineType1Code | | DocumentPurpose | JSON | TypeScript | ExternalDocumentPurpose1Code | | DocumentType | JSON | TypeScript | ExternalDocumentType1Code | | EffectiveDateParameter | JSON | TypeScript | ExternalEffectiveDateParameter1Code | | EmissionAllowanceSubProductType | JSON | TypeScript | ExternalEmissionAllowanceSubProductType1Code | | EncryptedElementIdentification | JSON | TypeScript | ExternalEncryptedElementIdentification1Code | | EnquiryRequestType | JSON | TypeScript | ExternalEnquiryRequestType1Code | | EntryStatus | JSON | TypeScript | ExternalEntryStatus1Code | | FinancialInstrumentIdentificationType | JSON | TypeScript | ExternalFinancialInstrumentIdentificationType1Code | | GarnishmentType | JSON | TypeScript | ExternalGarnishmentType1Code | | Incoterms | JSON | TypeScript | ExternalIncoterms1Code | | InformationType | JSON | TypeScript | ExternalInformationType1Code | | InstructedAgentInstruction | JSON | TypeScript | ExternalInstructedAgentInstruction1Code | | InvestigationAction | JSON | TypeScript | ExternalInvestigationAction1Code | | InvestigationActionReason | JSON | TypeScript | ExternalInvestigationActionReason1Code | | InvestigationExecutionConfirmation | JSON | TypeScript | ExternalInvestigationExecutionConfirmation1Code | | InvestigationInstrument | JSON | TypeScript | ExternalInvestigationInstrument1Code | | InvestigationReason | JSON | TypeScript | ExternalInvestigationReason1Code | | InvestigationReasonSubType | JSON | TypeScript | ExternalInvestigationReasonSubType1Code | | InvestigationServiceLevel | JSON | TypeScript | ExternalInvestigationServiceLevel1Code | | InvestigationStatus | JSON | TypeScript | ExternalInvestigationStatus1Code | | InvestigationStatusReason | JSON | TypeScript | ExternalInvestigationStatusReason1Code | | InvestigationSubType | JSON | TypeScript | ExternalInvestigationSubType1Code | | InvestigationType | JSON | TypeScript | ExternalInvestigationType1Code | | LetterType | JSON | TypeScript | ExternalLetterType1Code | | LocalInstrument | JSON | TypeScript | ExternalLocalInstrument1Code | | MandateReason | JSON | TypeScript | ExternalMandateReason1Code | | MandateStatus | JSON | TypeScript | ExternalMandateStatus1Code | | MandateSuspensionReason | JSON | TypeScript | ExternalMandateSuspensionReason1Code | | MarketArea | JSON | TypeScript | ExternalMarketArea1Code | | MarketInfrastructure | JSON | TypeScript | ExternalMarketInfrastructure1Code | | MessageFunction | JSON | TypeScript | ExternalMessageFunction1Code | | ModelFormIdentification | JSON | TypeScript | ExternalModelFormIdentification1Code | | NarrativeType | JSON | TypeScript | ExternalNarrativeType1Code | | NotificationSubType | JSON | TypeScript | ExternalNotificationSubType1Code | | NotificationType | JSON | TypeScript | ExternalNotificationType1Code | | OrganisationIdentification | JSON | TypeScript | ExternalOrganisationIdentification1Code | | PackagingType | JSON | TypeScript | ExternalPackagingType1Code | | PaymentCancellationRejection | JSON | TypeScript | ExternalPaymentCancellationRejection1Code | | PaymentCompensationReason | JSON | TypeScript | ExternalPaymentCompensationReason1Code | | PaymentControlRequestType | JSON | TypeScript | ExternalPaymentControlRequestType1Code | | PaymentGroupStatus | JSON | TypeScript | ExternalPaymentGroupStatus1Code | | PaymentModificationRejection | JSON | TypeScript | ExternalPaymentModificationRejection1Code | | PaymentRole | JSON | TypeScript | ExternalPaymentRole1Code | | PaymentTransactionStatus | JSON | TypeScript | ExternalPaymentTransactionStatus1Code | | PendingProcessingReason | JSON | TypeScript | ExternalPendingProcessingReason1Code | | PersonIdentification | JSON | TypeScript | ExternalPersonIdentification1Code | | PostTradeEventType | JSON | TypeScript | ExternalPostTradeEventType1Code | | ProductType | JSON | TypeScript | ExternalProductType1Code | | ProxyAccountType | JSON | TypeScript | ExternalProxyAccountType1Code | | Purpose | JSON | TypeScript | ExternalPurpose1Code | | RatesAndTenors | JSON | TypeScript | ExternalRatesAndTenors1Code | | RePresentmentReason | JSON | TypeScript | ExternalRePresentmentReason1Code | | ReceivedReason | JSON | TypeScript | ExternalReceivedReason1Code | | RejectedReason | JSON | TypeScript | ExternalRejectedReason1Code | | RelativeTo | JSON | TypeScript | ExternalRelativeTo1Code | | ReportingSource | JSON | TypeScript | ExternalReportingSource1Code | | RequestStatus | JSON | TypeScript | ExternalRequestStatus1Code | | ReservationType | JSON | TypeScript | ExternalReservationType1Code | | ReturnReason | JSON | TypeScript | ExternalReturnReason1Code | | ReversalReason | JSON | TypeScript | ExternalReversalReason1Code | | SecuritiesPurpose | JSON | TypeScript | ExternalSecuritiesPurpose1Code | | ServiceLevel | JSON | TypeScript | ExternalServiceLevel1Code | | ShipmentCondition | JSON | TypeScript | ExternalShipmentCondition1Code | | StatusReason | JSON | TypeScript | ExternalStatusReason1Code | | SystemBalanceType | JSON | TypeScript | ExternalSystemBalanceType1Code | | SystemErrorHandling | JSON | TypeScript | ExternalSystemErrorHandling1Code | | SystemEventType | JSON | TypeScript | ExternalSystemEventType1Code | | SystemMemberType | JSON | TypeScript | ExternalSystemMemberType1Code | | SystemPartyType | JSON | TypeScript | ExternalSystemPartyType1Code | | TaxAmountType | JSON | TypeScript | ExternalTaxAmountType1Code | | TechnicalInputChannel | JSON | TypeScript | ExternalTechnicalInputChannel1Code | | TradeMarket | JSON | TypeScript | ExternalTradeMarket1Code | | TradeTransactionCondition | JSON | TypeScript | ExternalTradeTransactionCondition1Code | | TypeOfParty | JSON | TypeScript | ExternalTypeOfParty1Code | | UnableToApplyIncorrectData | JSON | TypeScript | ExternalUnableToApplyIncorrectData1Code | | UnableToApplyMissingData | JSON | TypeScript | ExternalUnableToApplyMissingData1Code | | UnderlyingTradeTransactionType | JSON | TypeScript | ExternalUnderlyingTradeTransactionType1Code | | UndertakingAmountType | JSON | TypeScript | ExternalUndertakingAmountType1Code | | UndertakingDocumentType | JSON | TypeScript | ExternalUndertakingDocumentType1Code | | UndertakingStatusCategory | JSON | TypeScript | ExternalUndertakingStatusCategory1Code | | UndertakingType | JSON | TypeScript | ExternalUndertakingType1Code | | UnitOfMeasure | JSON | TypeScript | ExternalUnitOfMeasure1Code | | ValidationRuleIdentification | JSON | TypeScript | ExternalValidationRuleIdentification1Code | | VerificationReason | JSON | TypeScript | ExternalVerificationReason1Code |

Benefits

• Type Safety: Use TypeScript enums for compile-time validation
• Documentation: Each code includes its official description as JSDoc comments
• Consistency: Ensures your application uses ISO20022-compliant codes
• Easy Integration: Simple import and use in your TypeScript/JavaScript applications

Development

The code sets are generated from the ISO20022 external code sets using Python scripts:

• process_code_sets.py - Processes the ISO20022 external code sets and generates JSON files
• generate_ts_enums.py - Generates TypeScript enums from the JSON files

To regenerate the code sets (if you have updated source data):

python3 process_code_sets.py
python3 generate_ts_enums.py
npm run build

License

This package is MIT licensed. The ISO20022 data is published by ISO and is used in accordance with their terms.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Related

• ISO20022 Official Website
• ISO20022 Message Definitions