SWIFT Currency Codes API

openapi: 3.2.0
info:
  title: Swift Currency Codes API
  version: '1.0'
  description: 'Operations tagged Currency Codes across 3 of this provider''s published API definitions: swift-swiftref-api-openapi.yml, swift-swiftref-api-v4-openapi.yml, swift-swiftref-api-v4-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.swift.com/swiftrefdata
  description: SWIFT SwiftRef Production API
- url: https://sandbox.swift.com/swiftrefdata
  description: SWIFT SwiftRef Sandbox
- url: https://api.swift.com/swiftrefdata/v4
  description: Live environment
- url: https://sandbox.swift.com/swiftrefdata/v4
  description: Sandbox environment
- url: https://api-test.swift.com/swiftrefdata/v4
  description: Test environment
tags:
- name: Currency Codes
  description: Currency code lookup and validation
paths:
  /v2/currency_codes/{currency_code}:
    get:
      operationId: getCurrencyCode
      summary: Get Currency Code Details
      description: Returns details for an ISO 4217 currency code including currency name and minor units.
      tags:
      - Currency Codes
      parameters:
      - $ref: '#/components/parameters/currencyCode'
      responses:
        '200':
          description: Currency code details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyCodeDetails'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
      - OAuth2: []
    servers:
    - url: https://api.swift.com/swiftrefdata
      description: SWIFT SwiftRef Production API
    - url: https://sandbox.swift.com/swiftrefdata
      description: SWIFT SwiftRef Sandbox
  /v2/currency_codes/{currency_code}/validity:
    get:
      operationId: validateCurrencyCode
      summary: Validate Currency Code
      description: Checks whether a currency code is a valid ISO 4217 code.
      tags:
      - Currency Codes
      parameters:
      - $ref: '#/components/parameters/currencyCode'
      responses:
        '200':
          description: Currency code validity result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidityResult'
      security:
      - OAuth2: []
    servers:
    - url: https://api.swift.com/swiftrefdata
      description: SWIFT SwiftRef Production API
    - url: https://sandbox.swift.com/swiftrefdata
      description: SWIFT SwiftRef Sandbox
  /currency_codes/{currency_code}/validity:
    get:
      tags:
      - Currency Codes
      summary: Check validity of a currency code
      description: You can check whether a currency code is correct and valid.
      operationId: getCurrencyCodeValidity
      parameters:
      - in: path
        name: currency_code
        schema:
          oneOf:
          - $ref: '#/components/schemas/ThreeLetterCode'
          - $ref: '#/components/schemas/ThreeDigitCode'
        required: true
        description: Currency code (3-letters or 3-digits) to validate
        example: EUR
      responses:
        '200':
          description: Valid currency code
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyCodeValidity'
            application/xml:
              schema:
                $ref: '#/components/schemas/CurrencyCodeValidity'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.MCRI
                  severity: Fatal
                  text: 'The currency code is not in one of the two supported formats: 3a or 3n'
                  user_message: 'The currency code is not in one of the two supported formats: 3a or 3n'
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: '<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.MCRI</code> <severity>Fatal</severity> <text>The currency code is not in one of the two supported formats: 3a or 3n</text> <user_message>The currency code is not in one of the two supported formats: 3a or 3n</user_message> </error> </errors>'
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: Invalid currency code or currency code not found or wrong URL format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.ICUC
                  severity: Fatal
                  text: 'The currency code is not in one of the two supported formats: 3a or 3n'
                  user_message: Invalid currency code
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.ICUC</code> <severity>Fatal</severity> <text>The currency code matches one of the two supported formats (3a or 3n), but it does not exist</text> <user_message>Invalid currency code</user_message> </error> </errors>
        '405':
          $ref: '#/components/responses/InvalidHttpMethod'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
      - oauthBearerToken: []
    servers:
    - url: https://api.swift.com/swiftrefdata/v4
      description: Live environment
    - url: https://sandbox.swift.com/swiftrefdata/v4
      description: Sandbox environment
    - url: https://api-test.swift.com/swiftrefdata/v4
      description: Test environment
  /currency_codes/{currency_code}:
    get:
      tags:
      - Currency Codes
      summary: Get details of a currency code
      description: For a given currency code, you can retrieve the details of that currency code, that is the name, other codes, the fractional digits and the list of countries where the currency is used.
      operationId: getCurrencyCodeDetails
      parameters:
      - in: path
        name: currency_code
        schema:
          oneOf:
          - $ref: '#/components/schemas/ThreeLetterCode'
          - $ref: '#/components/schemas/ThreeDigitCode'
        required: true
        description: Currency code (3-letters or 3-digits) for which details are requested
        example: EUR
      responses:
        '200':
          description: Corresponding currency code found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Currency'
            application/xml:
              schema:
                $ref: '#/components/schemas/Currency'
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: No corresponding currency code found or wrong URL format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.CUNF
                  severity: Fatal
                  text: The currency code does not exist
                  user_message: The currency code does not exist
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.CUNF</code> <severity>Fatal</severity> <text>The currency code does not exist</text> <user_message>The currency code does not exist</user_message> </error> </errors>
        '405':
          $ref: '#/components/responses/InvalidHttpMethod'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
      - oauthBearerToken: []
    servers:
    - url: https://api.swift.com/swiftrefdata/v4
      description: Live environment
    - url: https://sandbox.swift.com/swiftrefdata/v4
      description: Sandbox environment
    - url: https://api-test.swift.com/swiftrefdata/v4
      description: Test environment
  /currency_codes/{currency_code}/amount_validity:
    get:
      tags:
      - Currency Codes
      summary: Check validity of a currency amount
      description: You can check whether an amount is valid for a specific currency.
      operationId: getCurrencyAmountValidity
      parameters:
      - in: path
        name: currency_code
        schema:
          oneOf:
          - $ref: '#/components/schemas/ThreeLetterCode'
          - $ref: '#/components/schemas/ThreeDigitCode'
        required: true
        description: Currency code (3-letters or 3-digits) of the amount to validate
        example: EUR
      - in: query
        name: amount
        schema:
          type: string
          pattern: ^[0-9]*,[0-9]*$
        required: true
        description: Currency amount to validate
        example: 12,34
      responses:
        '200':
          description: Valid amount
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrencyAmountValidity'
              example:
                amount: 12,34
                currency_code: EUR
                validity: VAMT
            application/xml:
              schema:
                $ref: '#/components/schemas/CurrencyAmountValidity'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <amount_validity> <amount>12,34</amount> <currency_code>EUR</currency_code> <validity>VAMT</validity> </amount_validity>
        '401':
          $ref: '#/components/responses/Unallowed'
        '404':
          description: Invalid currency code, currency code not found, invalid amount decimals or wrong URL format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
              example:
                errors:
                - code: REDA.API.IAMT
                  severity: Fatal
                  text: Invalid amount
                  user_message: Invalid amount
            application/xml:
              schema:
                $ref: '#/components/schemas/Errors'
              example: <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <errors> <error> <code>REDA.API.IAMT</code> <severity>Fatal</severity> <text>Invalid amount</text> <user_message>Invalid amount</user_message> </error> </errors>
        '405':
          $ref: '#/components/responses/InvalidHttpMethod'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        default:
          $ref: '#/components/responses/UnexpectedError'
      security:
      - oauthBearerToken: []
    servers:
    - url: https://api.swift.com/swiftrefdata/v4
      description: Live environment
    - url: https://sandbox.swift.com/swiftrefdata/v4
      description: Sandbox environment
    - url: https://api-test.swift.com/swiftrefdata/v4
      description: Test environment
components:
  schemas:
    ValidityResult:
      type: object
      properties:
        valid:
          type: boolean
          description: Whether the identifier is valid
        errorCode:
          type: string
          description: Error code if invalid
        errorDescription:
          type: string
          description: Human-readable description of validation failure
    CurrencyCodeDetails:
      type: object
      properties:
        currencyCode:
          type: string
          description: ISO 4217 currency code
        currencyName:
          type: string
          description: Currency name
        minorUnits:
          type: integer
          description: Number of decimal places (minor currency units)
    TwoLetterCode:
      description: Generic 2-letter code
      type: string
      pattern: ^[A-Z]{2}$
    CurrencyName:
      $ref: '#/components/schemas/StringMax70'
    CurrencyCodeValidity:
      type: object
      required:
      - currency_code
      - validity
      properties:
        currency_code:
          oneOf:
          - $ref: '#/components/schemas/ThreeLetterCode'
          - $ref: '#/components/schemas/ThreeDigitCode'
          description: The currency code that was validated
        validity:
          type: string
          enum:
          - VCUC
          description: The code VCUC if the currency code is valid
      xml:
        name: validity
      additionalProperties: false
      example:
        currency_code: EUR
        validity: VCUC
    StringMax70:
      description: Generic string definition, from 1 to 70 characters long
      type: string
      minLength: 1
      maxLength: 70
    ThreeLetterCode:
      description: Generic 3-letter code
      type: string
      pattern: ^[A-Z]{3}$
    ThreeDigitCode:
      description: Generic 3-digit code
      type: string
      pattern: ^[0-9]{3}$
    Error:
      description: Custom error schema to support detailed error message.
      required:
      - code
      - severity
      - text
      type: object
      properties:
        severity:
          description: Specifies the severity of the error.
          type: string
          enum:
          - Fatal
          - Transient
          - Logic
        code:
          description: Specifies the custom error code as defined by the service provider.
          type: string
          minLength: 3
          maxLength: 70
        text:
          $ref: '#/components/schemas/StringMax255'
        user_message:
          $ref: '#/components/schemas/StringMax255'
        more_info:
          description: Specifies an URL to find more information about the error.
          type: string
          format: uri
      xml:
        name: error
      additionalProperties: false
      example:
        code: REDA.API.CODE
        severity: Fatal
        text: Error description
        user_message: User-friendly error description
    Errors:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
          minItems: 1
      xml:
        name: errors
      additionalProperties: false
    CurrencyAmountValidity:
      type: object
      required:
      - amount
      - currency_code
      - validity
      properties:
        amount:
          type: string
          pattern: ^[0-9]*,[0-9]*$
          description: The amount that was validated
        currency_code:
          oneOf:
          - $ref: '#/components/schemas/ThreeLetterCode'
          - $ref: '#/components/schemas/ThreeDigitCode'
          description: The currency code of the amount that was validated
        validity:
          type: string
          enum:
          - VAMT
          description: The code VAMT if the amount is valid
      xml:
        name: amount_validity
      additionalProperties: false
      example:
        amount: 12,34
        currency_code: EUR
        validity: VAMT
    StringMax255:
      description: Generic string definition, from 1 to 255 characters long
      type: string
      minLength: 1
      maxLength: 255
    CountryName:
      $ref: '#/components/schemas/StringMax70'
    Currency:
      type: object
      required:
      - name
      - iso_3a_code
      properties:
        name:
          $ref: '#/components/schemas/CurrencyName'
        iso_3a_code:
          $ref: '#/components/schemas/ThreeLetterCode'
        iso_3n_code:
          $ref: '#/components/schemas/ThreeDigitCode'
        fractional_digits:
          type: integer
          minimum: 0
          maximum: 5
          description: The number of fractional digits to use
        countries:
          type: array
          items:
            type: object
            required:
            - name
            - iso_2a_code
            properties:
              name:
                $ref: '#/components/schemas/CountryName'
              iso_2a_code:
                $ref: '#/components/schemas/TwoLetterCode'
              iso_3a_code:
                $ref: '#/components/schemas/ThreeLetterCode'
              iso_3n_code:
                $ref: '#/components/schemas/ThreeDigitCode'
          description: A list of countries where the currency is used
      example:
        name: US DOLLAR
        iso_3a_code: USD
        iso_3n_code: '840'
        fractional_digits: 2
        countries:
        - iso_2a_code: AS
          iso_3a_code: ASM
          iso_3n_code: '016'
          name: AMERICAN SAMOA
        - iso_2a_code: BQ
          iso_3a_code: BES
          iso_3n_code: '535'
          name: BONAIRE, SINT EUSTATIUS AND SABA
  responses:
    NotFound:
      description: Identifier not found in reference data
      content:
        application/json:
          schema:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
    NotAcceptable:
      description: The server does not support the format asked by the consumer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - code: REDA.API.NOAC
              severity: Fatal
              text: Requested output format is not supported
    UnexpectedError:
      description: Unexpected error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        application/xml:
          schema:
            $ref: '#/components/schemas/Errors'
    InvalidHttpMethod:
      description: Request HTTP method is not accepted
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - code: REDA.API.IREQ
              severity: Fatal
              text: Request performed with HTTP method other than GET
              user_message: Invalid request
    Unallowed:
      description: You do not have sufficient privileges to execute this service
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example:
            errors:
            - code: REDA.API.ILIC
              severity: Fatal
              text: You do not have sufficient privileges to execute this service
              user_message: You do not have sufficient privileges to execute this service
  parameters:
    currencyCode:
      name: currency_code
      in: path
      required: true
      schema:
        type: string
        pattern: ^[A-Z]{3}$
      description: ISO 4217 currency code
      example: EUR
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        password:
          tokenUrl: https://api.swift.com/oauth2/v1/token
          scopes:
            urn:swiftref:external: External customer access to SwiftRef data
            urn:swiftref:internal: Internal payment validation access
    oauthBearerToken:
      type: http
      scheme: bearer
      bearerFormat: opaque OAuth 2.0
      description: "Use the access token obtained as a result of OAuth 2.0 flows. \n\nSWIFT supports two OAuth grant types depending on the API service.\n* JWT-Bearer grant type [RFC 7523](https://tools.ietf.org/html/rfc7523)\n* Password grant type\n\nThis API uses password grant type.\n\nPlease visit [SWIFT OAuth Token API](https://developer.swift.com/swift-oauth-token-api) for more information and examples.\n\nIn this declaration only the basic security element to transport the bearer token of an OAuth2 process is declared.\n"
externalDocs:
  description: SWIFT SwiftRef API Documentation
  url: https://developer.swift.com/apis/swiftref-api
x-refined-from:
- swift-swiftref-api-openapi.yml
- swift-swiftref-api-v4-openapi.yml
- swift-swiftref-api-v4-openapi.yml