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.