Mastercard Enhanced Currency Conversion Calculator

openapi: 3.0.0
info:
  description: >-
    The Enhanced Currency Conversion Calculator is a subscription-based service
    that provides access to Mastercard's daily currency conversion rates and
    historical currency conversion rates. Additionally, the API provides
    electronic access to European Central Bank (ECB) reference rates that
    European Economic Area (EEA) issuing customers may require for the purposes
    of compliance with EU Regulation 2019 / 518.
  version: 1.0.0
  title: Mastercard Enhanced Currency Conversion Calculator
  contact:
    name: API Support
    url: https://developer.mastercard.com/support
    email: [email protected]
tags:
  - name: Conversion-rate-summary
    description: >-
      Provides Mastercard currency conversion rate, calculated cardholder
      billing amount, the ECB reference rates and the calculated percentage
      difference between Mastercard and ECB rates for a provided currency pair
  - name: Conversion-rate-issued
    description: >-
      Determine if mastercard and ecb conversion rates are issued for the given
      date
  - name: Mastercard-currencies
    description: List of Mastercard currencies
  - name: Ecb-currencies
    description: >-
      List of EEA currencies for which the ECB publishes an euro foreign
      exchange reference rate
paths:
  /summary-rates:
    get:
      tags:
        - Summaries
        - Rates
      summary: getEnhancedConversionDetails
      operationId: getEnhancedConversionDetailsUsingGET
      description: >-
        Provides Mastercard currency conversion rate, calculated cardholder
        billing amount, the ECB reference rate and the calculated percentage
        difference between Mastercard and ECB rate for the provided currency
        pair.
      parameters:
        - name: rate_date
          in: query
          description: Date of the requested FX rates
          required: true
          schema:
            type: string
          example: '2023-02-27'
        - name: trans_curr
          in: query
          description: Currency of the transaction
          required: true
          schema:
            type: string
          example: GBP
        - name: trans_amt
          in: query
          description: Amount in the transaction currency
          required: true
          schema:
            type: number
          example: '100'
        - name: crdhld_bill_curr
          in: query
          description: Cardholder billing currency
          required: true
          schema:
            type: string
          example: EUR
        - name: bank_fee_pct
          in: query
          description: >-
            Percentage mark-up/fee (if applicable) an issuer would assess a
            cardholder on the cross-border/cross-currency transaction
          required: false
          schema:
            type: number
          example: '1.6754'
        - name: bank_fee_fixed
          in: query
          description: >-
            Fixed mark-up/fee (if applicable) an issuer would assess a
            cardholder on the cross-border/cross-currency transaction (amount in
            cardholder billing currency)
          required: false
          schema:
            type: number
          example: '0.5'
      responses:
        '200':
          description: Rates Summary is successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedCurrencyConversionWrapper'
        '400':
          description: Invalid input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestResponse:
                  $ref: '#/components/examples/BadRequestResponse'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedResponse:
                  $ref: '#/components/examples/UnauthorizedResponse'
        '403':
          description: Mastercard and ECB rates are not accessible for selected date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                ForbiddenResponse:
                  $ref: '#/components/examples/ForbiddenResponse'
        '404':
          description: Rates are not available for selected date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                NotFoundResponse:
                  $ref: '#/components/examples/NotFoundResponse'
  /rate-statuses:
    get:
      tags:
        - Rates
        - Statuses
      summary: isEcbMcRateIssued
      operationId: isEcbMcRateIssuedUsingGET
      description: >-
        Helps determine if the present days Mastercard and ECB conversion rates
        are available. Refer the Support section for more information on the
        Mastercard and ECB rate publication schedule.
      parameters:
        - name: request_date
          in: query
          description: Rate issued date (YYYY-mm-dd)
          required: false
          schema:
            type: string
          example: '2023-02-27'
      responses:
        '200':
          description: Rates status is successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedSettlementRateIssuedWrapper'
        '400':
          description: Date format is invalid (Expected date format yyyy-MM-DD).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                BadRequestResponse:
                  $ref: '#/components/examples/BadRequestResponse'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedResponse:
                  $ref: '#/components/examples/UnauthorizedResponse'
        '403':
          description: 'Mastercard and ECB rates are not accessible for selected date '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                RateIssuedForbiddenResponse:
                  $ref: '#/components/examples/RateIssuedForbiddenResponse'
        '404':
          description: Rates are not available for selected date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                RateIssuedNotFoundResponse:
                  $ref: '#/components/examples/RateIssuedNotFoundResponse'
  /mc-currencies:
    get:
      tags:
        - Currencies
      summary: getEnhancedMCCurrencyData
      operationId: getEnhancedMCCurrencyDataUsingGET
      description: >-
        Provides a list of Mastercard currencies for which Mastercard publishes
        a rate.
      responses:
        '200':
          description: List of Mastercard currencies successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedMastercardCurrencyWrapper'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedResponse:
                  $ref: '#/components/examples/UnauthorizedResponse'
        '404':
          description: Data not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                CurrenciesNotFoundResponse:
                  $ref: '#/components/examples/CurrenciesNotFoundResponse'
  /ecb-currencies:
    get:
      tags:
        - Currencies
      summary: getEcbCurrenciesList
      operationId: getEcbCurrenciesListUsingGET
      description: >-
        Provides the list of currencies for which the ECB publishes an euro
        foreign exchange reference rate.
      responses:
        '200':
          description: List of ECB currencies successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnhancedEcbCurrencyWrapper'
        '401':
          description: Unauthorized request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                UnauthorizedResponse:
                  $ref: '#/components/examples/UnauthorizedResponse'
        '404':
          description: Data not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                CurrenciesNotFoundResponse:
                  $ref: '#/components/examples/CurrenciesNotFoundResponse'
servers:
  - url: >-
      https://sandbox.api.mastercard.com/enhanced/settlement/currencyrate/subscribed
    description: Sandbox server
  - url: https://api.mastercard.com/enhanced/settlement/currencyrate/subscribed
    description: Production server
components:
  schemas:
    ECBConversionObject:
      type: object
      properties:
        ecbReferenceRateDate:
          type: string
          description: Date of reference rates issued by the European Central Bank (ECB).
          example: '2021-02-16T00:00:00.000Z'
        ecbReferenceRate:
          type: number
          description: >-
            Euro foreign exchange reference rates issued by the European Central
            Bank (ECB). When neither the transaction currency nor the cardholder
            billing currency is equal to Euro, a calculated reference rate is
            derived from the two ECB rates
          example: 1.2018075
        message:
          type: string
          description: User friendly message (if applicable)
          example: >-
            Rate issuance for requested date not supported.  Resubmit for a
            non-weekend or non-holiday date.
        reasonCode:
          type: string
          description: User friendly reason code (if applicable)
          example: NOT_AVAILABLE
    MastercardConversionObject:
      type: object
      properties:
        mastercardFxRateDate:
          type: string
          description: >-
            Date of Mastercard issued conversion rates. The date can differ to
            the requested rate date if no new rates are published for the
            requested date or if the user requests for a historical date
          example: '2021-02-16T00:00:00.000Z'
        mastercardConvRateInclPctFee:
          type: number
          description: >-
            Mastercard exchange rate for the requested currency pair including
            issuer-to-cardholder percentage rate fee as provided by the issuer
            in the API call
          example: 1.2250048
        mastercardConvRateExclAllFees:
          type: number
          description: >-
            Mastercard exchange rate for the requested currency pair excluding
            any issuer-to-cardholder fees
          example: 1.2048193
        crdhldBillAmtInclAllFees:
          type: number
          description: >-
            Cardholder Billing Amount as calculated by applying the Mastercard
            Conversion Rate, including any applicable issuer-to-cardholder fees
            (percentage and fixed)
          example: 123.00048
        crdhldBillAmtExclAllFees:
          type: number
          description: >-
            Cardholder billing amount calculated by using the Mastercard
            conversion rate, excluding any applicable issuer-to-cardholder fees
          example: 120.48193
        message:
          type: string
          description: User friendly message (if applicable)
          example: >-
            Conversion rate is not available for this currency pair, Please
            refer to the Support section for a complete list of MCI reference
            rates available via the Enhanced Currency Conversion Calculator -
            https://developer.mastercard.com/documentation/enhanced-currency-conversion-calculator
        reasonCode:
          type: string
          description: User friendly reason code (if applicable)
          example: NOT_APPLICABLE
    EnhancedEcbCurrencies:
      type: object
      properties:
        currencyCount:
          type: integer
          format: int32
          description: Number of ECB Currencies
          example: 33
        currencies:
          type: array
          description: List of ECB Currencies
          items:
            $ref: '#/components/schemas/EnhancedCurrency'
    EnhancedSettlementRateIssued:
      type: object
      properties:
        rateDate:
          type: string
          description: The date of the requested rates
          example: '2021-02-16T00:00:00.000Z'
        mastercardRateIssued:
          $ref: '#/components/schemas/EcbMcRateIssued'
        ecbRateIssued:
          $ref: '#/components/schemas/EcbMcRateIssued'
    EnhancedMastercardCurrencies:
      type: object
      properties:
        currencyCount:
          type: integer
          format: int32
          description: Number of Mastercard Currencies
          example: 153
        currencies:
          type: array
          description: List of Mastercard Currencies
          items:
            $ref: '#/components/schemas/EnhancedCurrency'
    EnhancedCurrencyConversionData:
      type: object
      properties:
        transCurr:
          type: string
          description: Currency of the transaction as provided in the API request
          example: GBP
        crdhldBillCurr:
          type: string
          description: Cardholder billing currency as provided in the API request
          example: EUR
        rateDate:
          type: string
          description: The date of the requested rates
          example: '2021-02-16T00:00:00.000Z'
        transAmt:
          type: number
          description: Amount in transaction currency as provided in the API request
          example: '100'
        bankFeePct:
          type: number
          description: Percentage bank fee as provided in the API request
          example: '1.6754'
        bankFeeFixed:
          type: number
          description: Fixed bank fee as provided in the API request
          example: '0.5'
        mastercard:
          $ref: '#/components/schemas/MastercardConversionObject'
        ecb:
          $ref: '#/components/schemas/ECBConversionObject'
        effectiveConversionRate:
          type: number
          description: >-
            Calculated effective exchange rate for the requested currency pair
            including all issuer-to-cardholder fees. This is calculated by
            dividing cardholder billing amount including all fees divided by the
            transaction amount (crdhldBillAmtInclAllFees / transAmount)
          example: 1.2300048
        pctDifferenceMastercardExclAllFeesAndEcb:
          type: number
          description: >-
            Calculated percentage difference between Mastercard Conversion Rate
            excluding all issuer-to-cardholder fees for the selected currency
            pair and the ECB Reference Rate
          example: 0.2506058
        pctDifferenceMastercardInclAllFeesAndEcb:
          type: number
          description: >-
            Calculated percentage difference between Mastercard Conversion Rate
            Including all issuer-to-cardholder fees (fixed and percentage) for
            the selected currency pair and the ECB Reference Rate
            ([effectiveConversionRate/ecbReferenceRateDate]-1*100)
          example: 2.3462409
    ErrorResponse:
      type: object
      required:
        - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    EnhancedMastercardCurrencyWrapper:
      type: object
      properties:
        name:
          type: string
          description: The name of the service being requested
          example: mastercard-currencies
        description:
          type: string
          description: The description of the API being called
          example: List of Mastercard currencies
        requestDate:
          type: string
          description: The date and time the API is being called in GMT
          example: '2020-01-21T17:39:41.000Z'
        data:
          $ref: '#/components/schemas/EnhancedMastercardCurrencies'
    Errors:
      type: object
      required:
        - Error
      properties:
        Error:
          type: array
          description: if an errorhas occurred
          items:
            $ref: '#/components/schemas/EcbError'
    EcbError:
      type: object
      properties:
        Description:
          type: string
          description: Short description of the ReasonCode field.
          example: Not Found
        Details:
          type: string
          description: >-
            Where appropriate, indicates detailed information about data
            received and calculated during request processing, to help the user
            with diagnosing errors.
          example: >-
            Mastercard and ECB rates are not available for this date. Resubmit
            for a date within the last 365 days inclusive of current day.
        ReasonCode:
          type: string
          description: >-
            A unique constant identifying the error case encountered during
            transaction processing. For example, INVALID_SIGNATURE is used when
            the request signature does not match the expected one.
          example: NOT_FOUND
        Recoverable:
          type: boolean
          description: >-
            Indicates whether this error will always be returned for this
            request, or retrying could change the outcome. For example, if the
            request contains an invalid   signature, retrying will never result
            in a success. However, if the error is related to some unexpected
            timeout with the service, retrying the call could result in a
            successful response.
          example: false
        Source:
          type: string
          description: The name of the application that generated this error
          example: Gateway
    EnhancedCurrencyConversionWrapper:
      type: object
      properties:
        name:
          type: string
          description: The name of the service being requested
          example: mastercard-and-ecb-currency-conversion-rates
        description:
          type: string
          description: The description of the API being called
          example: >-
            Provides Mastercard currency conversion rate, calculated cardholder
            billing amount, the ECB reference rates and the calculated
            percentage difference between Mastercard and ECB rates for a
            provided currency pair
        requestDate:
          type: string
          description: The date and time the API is being called in GMT
          example: '2020-01-17T18:04:18.000Z'
        data:
          $ref: '#/components/schemas/EnhancedCurrencyConversionData'
    EnhancedEcbCurrencyWrapper:
      type: object
      properties:
        name:
          type: string
          description: The name of the service being requested
          example: ecb-currencies
        description:
          type: string
          description: The description of the API being called
          example: >-
            List of EEA currencies for which the ECB publishes an euro foreign
            exchange reference rate
        requestDate:
          type: string
          description: The date and time the API is being called in GMT
          example: '2020-01-21T17:43:37.000Z'
        data:
          $ref: '#/components/schemas/EnhancedEcbCurrencies'
    EnhancedSettlementRateIssuedWrapper:
      type: object
      properties:
        name:
          type: string
          description: The name of the service being requested
          example: mastercard-and-ecb-rate-status-service
        description:
          type: string
          description: The description of the API being called
          example: >-
            Determine if mastercard and ecb conversion rates are issued for the
            given date
        requestDate:
          type: string
          description: The date and time the API is being called in GMT
          example: '2019-11-17T00:00:00.000Z'
        data:
          $ref: '#/components/schemas/EnhancedSettlementRateIssued'
    EcbMcRateIssued:
      type: object
      properties:
        message:
          type: string
          description: User friendly message (if applicable)
          example: >-
            Rate issuance for requested date not supported.  Resubmit for a
            non-weekend or non-holiday date.
        reasonCode:
          type: string
          description: User friendly reason code (if applicable)
          example: NOT_AVAILABLE
        status:
          type: string
          description: Provides rate status as yes/No
          example: 'yes'
    EnhancedCurrency:
      type: object
      properties:
        alphaCd:
          type: string
          description: The currency code for the currency
          example: EUR
        currName:
          type: string
          description: The full name of the currency
          example: Euro
  examples:
    NotFoundResponse:
      value:
        Errors:
          Error:
            - Source: Enhanced Currency Conversion Calculator
              ReasonCode: NOT_FOUND
              Description: Data not available
              Recoverable: false
              Details: >-
                Mastercard and ECB rates are not available for this date.
                Resubmit for a date within the last 365 days inclusive of
                current day.
    BadRequestResponse:
      value:
        Errors:
          Error:
            - Source: Enhanced Currency Conversion Calculator
              ReasonCode: BAD_REQUEST
              Description: Invalid input
              Recoverable: false
              Details: Date format is invalid (Expected date format yyyy-MM-dd)
    ForbiddenResponse:
      value:
        Errors:
          Error:
            - Source: Enhanced Currency Conversion Calculator
              ReasonCode: FORBIDDEN
              Description: Data is not accesssible
              Recoverable: false
              Details: >-
                Rate is not accessible for this date - Please use a date within
                the last 365 days inclusive of current day.
    UnauthorizedResponse:
      value:
        Errors:
          Error:
            - Source: Enhanced Currency Conversion Calculator
              ReasonCode: UNAUTHORIZED
              Description: Invalid Client ID
              Recoverable: false
              Details: >-
                You do not have access to this service. Please visit the
                Enhanced Currency Conversion Calculator page for details.
    CurrenciesNotFoundResponse:
      value:
        Errors:
          Error:
            - Source: Enhanced Currency Conversion Calculator
              ReasonCode: NOT_FOUND
              Description: Data not available
              Recoverable: true
              Details: No active currency available
    RateIssuedForbiddenResponse:
      value:
        Errors:
          Error:
            - Source: Enhanced Currency Conversion Calculator
              ReasonCode: FORBIDDEN
              Description: Data is not accesssible
              Recoverable: false
              Details: >-
                Rate issuance for requested date not supported - Please use a
                date within the last 365 days inclusive of current day.
    RateIssuedNotFoundResponse:
      value:
        Errors:
          Error:
            - Source: Enhanced Currency Conversion Calculator
              ReasonCode: NOT_FOUND
              Description: Data not available
              Recoverable: false
              Details: Rate issuance for future date not supported.