swagger: '2.0' info: title: Mastercard Bill Payment Validator Account Opening Rates 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: Rates paths: /summary-rates: get: tags: - 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 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' /conversion-rate: get: tags: - Rates summary: Mastercard Get the Currency Conversion Rate Details. description: Provides transaction details including date, transaction currency and amount, cardholder billing currency and issuer specific mark up to determine the applicable currency conversion rate and cardholder billing amount. operationId: getConversionDetailUsingGET parameters: - name: fxDate in: query description: Date of the requested FX rates. required: true schema: type: string example: '2023-02-27' - name: transCurr in: query description: Currency of the transaction. required: true schema: type: string example: ALL - name: crdhldBillCurr in: query description: Cardholder billing currency. required: true schema: type: string example: DZD - name: bankFee in: query description: Additional fees imposed by the bank. required: false schema: type: number format: number example: 5 - name: transAmt in: query description: Amount in the transaction currency. required: true schema: type: number format: number example: 23 responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ConversionRateWrapper' examples: Getconversiondetailusingget200Example: summary: Default getConversionDetailUsingGET 200 response x-microcks-default: true value: name: Example Title description: A sample description. date: example_value type: example_value data: conversionRate: 42.5 crdhldBillAmt: 42.5 fxDate: example_value transCurr: example_value crdhldBillCurr: example_value transAmt: 42.5 bankFee: 42.5 errorCode: example_value errorMessage: example_value '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found x-microcks-operation: delay: 0 dispatcher: FALLBACK /conversion-rate-issued: get: tags: - Rates summary: Mastercard Determine if the Settlement Rate Has Been Issued. description: Provides status update if the present day Mastercard currency conversion rates are issued. Mastercard rates are published daily and effective for 24 hours. operationId: isRateIssuedUsingGET parameters: - name: date in: query description: The date by which the rate would have been issued. required: false schema: type: string example: '2023-02-27' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SettlementRateIssuedWrapper' examples: Israteissuedusingget200Example: summary: Default isRateIssuedUsingGET 200 response x-microcks-default: true value: name: Example Title description: A sample description. date: example_value data: rateIssued: example_value '401': description: Unauthorized '403': description: Forbidden '404': description: Not Found x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: Errors: type: object required: - Error properties: Error: type: array description: if an errorhas occurred items: $ref: '#/components/schemas/EcbError' 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' 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 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' 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' 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 Conversion: type: object properties: conversionRate: type: number format: number example: 0.943078 description: Rate applied to the transaction to convert from Transaction Currency to Cardholder Billing Currency. crdhldBillAmt: type: number format: number example: 21.690798 description: Amount in the cardholder billing currency. fxDate: type: string example: '2016-09-30' description: Date of the requested FX rates. transCurr: type: string example: ALL description: Currency of the transaction. crdhldBillCurr: type: string example: DZD description: Cardholder billing currency. transAmt: type: number format: number example: 23 description: Amount in the transaction currency. bankFee: type: number format: number example: 5 description: Additional fees imposed by the bank. errorCode: type: string example: 104 description: The error code associated with the error being returned. errorMessage: type: string example: Not Found , The calculated cross rates for the selected date is not available. description: The reason for the error. SettlementRateIssued: type: object properties: rateIssued: type: string example: 'NO' description: The requested foreign exchange rate. ConversionRateWrapper: type: object properties: name: type: string example: settlement-conversion-rate description: The name of the service being requested. description: type: string example: Settlement conversion rate and billing amount description: The description of the API being called. date: type: string example: '2019-08-08 16:43:27' description: The date and time the API is being called in GMT. type: type: string example: error description: The type of response being returned by the API. data: $ref: '#/components/schemas/Conversion' SettlementRateIssuedWrapper: type: object properties: name: type: string example: settlement-conversion-rate-issued description: The name of the service being requested. description: type: string example: Is settlement conversion rate issued description: The description of the API being called. date: type: string example: '2019-08-08 16:22:31' description: The date and time the API is being called in GMT. data: $ref: '#/components/schemas/SettlementRateIssued' 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. 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. 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.