Mastercard Summaries API

swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Summaries API
  description: This service is provided on behalf of the Mastercard Remote Payment and Presentment (RPPS) Bill Payment Processing Network, which supports consumer to business "push" bill payments (i.e. those which are not funded by debit/credit card transactions) in the U.S.
  version: '1.0'
  x-artifactId: billpay-api
  contact:
    name: Bill Pay Development Support
    email: Bill_Pay_Development_Support@mastercard.com
host: sandbox.api.mastercard.com
basePath: /billpayAPI/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Summaries
paths:
  /summary-rates:
    get:
      tags:
      - Summaries
      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'
components:
  schemas:
    Errors:
      type: object
      required:
      - Error
      properties:
        Error:
          type: array
          description: if an errorhas occurred
          items:
            $ref: '#/components/schemas/EcbError'
    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
    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
    ErrorResponse:
      type: object
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    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
    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'
    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
  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.
    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.
    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)
    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.