swagger: '2.0' info: title: Mastercard Bill Payment Validator Account Opening Refunds 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: Refunds description: API endpoints used by CSP to facilitate refund request and confirmation. paths: /payment-requests/{payment_request_lifecycle_id}/refunds: post: tags: - Refunds summary: Mastercard Refund Account Request. description: A CSP can request refund account details from a Debtor Service Provider(DSP) on behalf of a Creditor. They can use these details to refund the Debtor. operationId: retrieveRefundAccount parameters: - $ref: '#/components/parameters/X-Request-ID' - $ref: '#/components/parameters/X-Product-ID' - $ref: '#/components/parameters/X-Participant-ID' - $ref: '#/components/parameters/X-JWS-Signature' - $ref: '#/components/parameters/Idempotency-Key' - $ref: '#/components/parameters/payment_request_lifecycle_id' requestBody: $ref: '#/components/requestBodies/RefundAccountRequest' responses: '200': $ref: '#/components/responses/RefundAccountResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorisedErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /payment-requests/{payment_request_lifecycle_id}/refunds/{refund_request_lifecycle_id}/payment-confirmations: post: tags: - Refunds summary: Mastercard Refund Payment Confirmation. description: Enables CSP to notify DSP of a refund payment confirmation. operationId: confirmRefundPayment parameters: - $ref: '#/components/parameters/X-Request-ID' - $ref: '#/components/parameters/X-Product-ID' - $ref: '#/components/parameters/X-Participant-ID' - $ref: '#/components/parameters/X-JWS-Signature' - $ref: '#/components/parameters/Idempotency-Key' - $ref: '#/components/parameters/payment_request_lifecycle_id' - $ref: '#/components/parameters/refund_request_lifecycle_id' requestBody: $ref: '#/components/requestBodies/RefundPaymentConfirmationRequest' responses: '200': $ref: '#/components/responses/RefundPaymentConfirmationResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorisedErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /payment-requests/{payment_request_lifecycle_id}/refunds/{refund_request_lifecycle_id}/status-retrievals: post: tags: - Refunds summary: Mastercard Refund Request Status Retrieval Request description: Enables DSP to enquire about the status of Refund Request. operationId: retrieveRefundStatus parameters: - $ref: '#/components/parameters/X-Request-ID' - $ref: '#/components/parameters/X-Product-ID_2' - $ref: '#/components/parameters/X-Participant-ID' - $ref: '#/components/parameters/X-JWS-Signature' - $ref: '#/components/parameters/Idempotency-Key' - $ref: '#/components/parameters/refund_request_lifecycle_id' - $ref: '#/components/parameters/payment_request_lifecycle_id' requestBody: $ref: '#/components/requestBodies/RefundRequestStatusRetrievalRequest' responses: '200': $ref: '#/components/responses/RefundRequestStatusRetrievalResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorisedErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: NewRefundRequestStatusRetrieval: allOf: - $ref: '#/components/schemas/MessageRequestBlock' - type: object required: - refundRequestLifecycleId - paymentRequestLifecycleId - debtor properties: paymentRequestLifecycleId: type: string minLength: 1 maxLength: 35 example: '923123123123123100' description: Unique identifier assigned by Mastercard, to identify the payment request in subsequent transactions or services. refundRequestLifecycleId: type: string example: 0123901239100 minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify the refund request in subsequent transactions or services. debtor: $ref: '#/components/schemas/DebtorForSRR' RefundAcknowledgement: type: object required: - refundRequestLifecycleId - refundRequestStatus properties: refundRequestLifecycleId: type: string example: 0123901239100 minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify the refund request in subsequent transactions or services. refundRequestStatus: type: string example: INPR minLength: 4 maxLength: 4 description: Refund Status returned to Mastercard. * Refer to Codes and Formats section for more details. status: type: object required: - refundStatus properties: refundStatus: type: string example: APPR maxLength: 4 minLength: 4 description: Status of the transaction. * Refer to Codes and Formats section for more details. refundStatusReason: type: string example: SYSM maxLength: 4 minLength: 4 description: Reason for declined transaction. * Refer to Codes and Formats section for more details. RefundRequestStatusRetrievalAck: allOf: - $ref: '#/components/schemas/MessageResponseBlock_2' - type: object required: - refundRequestStatusRetrievalLifecycleId - retrievalRequestStatus properties: refundRequestStatusRetrievalLifecycleId: type: string example: '111123123123123111' minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify the Refund Request Status Retrieval request in subsequent transactions or services. retrievalRequestStatus: type: string example: WFPC minLength: 1 maxLength: 35 description: Informs the status of the Retrieval Request. * Refer to Codes and Formats section for more details. NewRefundAccount: allOf: - $ref: '#/components/schemas/MessageRequestBlock' - type: object required: - refund - creditor properties: creditor: $ref: '#/components/schemas/CreditorForRefund' refund: $ref: '#/components/schemas/Refund' refundPayment: type: object required: - refundpaymentReference - clearingSystem - refundAmount properties: refundpaymentReference: type: string minLength: 1 maxLength: 42 example: y18dvGsj3GJ57Tt description: Unique refund payment Reference of the real time settlement method provided by CSP. clearingSystem: type: string minLength: 1 maxLength: 35 example: FPS description: Creditor or CSP requested real-time settlement method. * Refer to Codes and Formats section for more details. refundAmount: allOf: - $ref: '#/components/schemas/Amount' example: example_value RefundAccount: allOf: - $ref: '#/components/schemas/MessageResponseBlock' - type: object required: - refund properties: refund: $ref: '#/components/schemas/RefundAcknowledgement' MessageResponseBlock: type: object required: - messageId - creationDateTime - initiatingPartyId - originalMessageId properties: initiatingPartyId: type: string example: ZAPP minLength: 1 maxLength: 35 description: Unique identifier of the message sender. messageId: type: string example: 3bef00e542ec4be583b1b5d449799084 minLength: 1 maxLength: 35 description: A point-to-point unique identifier is assigned to every message by the message initiator. creationDateTime: type: string example: '2020-11-20T06:57:24.465Z' format: date-time description: ISO 8601 format date and time in Coordinated Universal Time (UTC) when this message was created. originalMessageId: type: string example: 7eab4eab35a542e085add0363a49c035 minLength: 1 maxLength: 35 description: "Original message identifier generated and sent by the initiator of\n the request message." RefundPaymentAdviseConfirmation: allOf: - $ref: '#/components/schemas/MessageResponseBlock' ErrorWrapper: description: A top level object for errors type: object required: - Errors properties: Errors: $ref: '#/components/schemas/Errors' Refund: type: object required: - paymentRequestLifecycleId - refundAmount - refundReason - refundMethod properties: paymentRequestLifecycleId: type: string example: '923123123123123100' minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify the payment request in subsequent transactions or services. creditorRefundReference: type: string example: '454647894521236' minLength: 1 maxLength: 35 description: Identifier assigned for the refund transaction by the Creditor or CSP. caseReferenceId: type: string example: '2324252627' minLength: 1 maxLength: 35 description: CaseReferenceId generated by Dispute Management System to be Populated when the refund is a result of a dispute. This should be populated only when the value for refundReason is DISPUTES. refundAmount: $ref: '#/components/schemas/Amount' refundReason: type: string example: DUPLICATEORDER minLength: 1 maxLength: 25 description: Identifies the reason for the refund, such as whether a refund is the result of a query or a dispute case. * Refer to Codes and Formats section for more details. refundMethod: type: string example: FPS minLength: 1 maxLength: 20 description: The method of refund that Creditor or CSP will use when they receive account details from DSP. * Refer to Codes and Formats section for more details. Amount: required: - currency - value type: object properties: currency: type: string example: GBP maxLength: 3 minLength: 3 description: ISO 4217 code for Currency. value: type: number example: 100.25 description: Amount value. NewRefundPaymentConfirmation: allOf: - $ref: '#/components/schemas/MessageRequestBlock' - type: object required: - paymentRequestLifecycleId - refundRequestLifecycleId - creditor - status properties: paymentRequestLifecycleId: type: string example: '923123123123123100' minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify the payment request in subsequent transactions or services. refundRequestLifecycleId: type: string example: 0123901239100 minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify the refund request in subsequent transactions or services. creditor: $ref: '#/components/schemas/CreditorForRefund' status: $ref: '#/components/schemas/status' refundPaymentConfirmation: $ref: '#/components/schemas/refundPayment' refundRequestStatusRetrievalLifecycleId: type: string example: '111123123123123111' minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify the Refund Request Status Retrieval request in subsequent transactions or services. Errors: description: Object that contains the list of errors type: object required: - Error properties: Error: $ref: '#/components/schemas/ErrorList' DebtorForSRR: type: object required: - debtorId - debtorServiceProviderId properties: debtorId: type: string example: Fxrsi5345 minLength: 1 maxLength: 35 description: Unique identifier of the Debtor provided to Mastercard by the DSP. debtorServiceProviderId: type: string example: 000369 minLength: 1 maxLength: 35 description: Unique identifier assigned to the DSP during Mastercard onboarding. ErrorList: description: The list of errors type: array minItems: 1 items: $ref: '#/components/schemas/Error' MessageResponseBlock_2: type: object required: - messageId - creationDateTime - initiatingPartyId - originalMessageId properties: initiatingPartyId: type: string example: ZAPP minLength: 1 maxLength: 35 description: Unique identifier of the message sender. messageId: type: string example: 3bef00e542ec4be583b1b5d449799084 minLength: 1 maxLength: 35 description: A point-to-point unique identifier is assigned to every message by the message initiator. creationDateTime: type: string example: '2020-11-20T06:57:24.465Z' format: date-time description: ISO 8601 format date and time in Coordinated Universal Time (UTC) when this message was created. originalMessageId: type: string example: 7eab4eab35a542e085add0363a49c035 minLength: 1 maxLength: 35 description: Original message identifier generated and sent by the initiator of the request message. CreditorForRefund: type: object required: - creditorId - creditorServiceProviderId properties: creditorId: type: string example: VerizonoMobile000588 minLength: 1 maxLength: 35 description: Unique identifier assigned to the Creditor by the CSP. creditorServiceProviderId: type: string example: '000645' minLength: 1 maxLength: 35 description: Unique identifier assigned to the CSP during Mastercard onboarding. MessageRequestBlock: type: object required: - messageId - creationDateTime - initiatingPartyId - businessType properties: initiatingPartyId: type: string example: '000545' minLength: 1 maxLength: 35 description: Unique identifier of the message sender. messageId: type: string example: 7eab4eab35a542e085add0363a49c035 minLength: 1 maxLength: 35 description: A point-to-point unique identifier is assigned to every message by the message initiator. creationDateTime: type: string format: date-time example: '2020-11-20T06:57:24.465Z' description: ISO 8601 format date and time in Coordinated Universal Time (UTC) when this message was created. businessType: type: number example: 3 minimum: 1 maximum: 999 description: Unique identifier assigned by Mastercard to define the commercial product construct. * Refer to Codes and Formats section for more details. Error: description: A single error type: object properties: Source: type: string example: ZAPP description: Source of the error ReasonCode: type: string example: STVL-9999 description: Error Code Description: type: string example: Invalid structure description: Error Description Recoverable: type: boolean example: false description: Boolean value to specify if error is recoverable or not Details: type: string example: Invalid structure description: Optional details of the error responses: RefundAccountResponse: description: Refund account request creation successful. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Product-ID: $ref: '#/components/headers/X-Product-ID' X-Participant-ID: $ref: '#/components/headers/X-Participant-ID' X-JWS-Signature: $ref: '#/components/headers/X-JWS-Signature' content: application/json: schema: $ref: '#/components/schemas/RefundAccount' BadRequestErrorResponse: description: 'Invalid structure: The header or payload fails syntax or structural validation.' headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Product-ID: $ref: '#/components/headers/X-Product-ID' X-Participant-ID: $ref: '#/components/headers/X-Participant-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorWrapper' examples: BadRequestErrorExample: $ref: '#/components/examples/BadRequestErrorExample' RefundRequestStatusRetrievalResponse: description: Refund Request Status Retrieval Request was successfully received by Mastercard. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID_2' X-Product-ID: $ref: '#/components/headers/X-Product-ID_2' X-Participant-ID: $ref: '#/components/headers/X-Participant-ID' content: application/json: schema: $ref: '#/components/schemas/RefundRequestStatusRetrievalAck' RefundPaymentConfirmationResponse: description: Refund payment confirmation successful. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Product-ID: $ref: '#/components/headers/X-Product-ID' X-Participant-ID: $ref: '#/components/headers/X-Participant-ID' X-JWS-Signature: $ref: '#/components/headers/X-JWS-Signature' content: application/json: schema: $ref: '#/components/schemas/RefundPaymentAdviseConfirmation' UnauthorisedErrorResponse: description: Invalid signature. The service fails signature validation. headers: X-Request-ID: $ref: '#/components/headers/X-Request-ID' X-Product-ID: $ref: '#/components/headers/X-Product-ID' X-Participant-ID: $ref: '#/components/headers/X-Participant-ID' content: application/json: schema: $ref: '#/components/schemas/ErrorWrapper' examples: BadRequestExample: $ref: '#/components/examples/UnauthorisedExample' requestBodies: RefundAccountRequest: required: true description: Refund account request order. content: application/json: schema: $ref: '#/components/schemas/NewRefundAccount' RefundPaymentConfirmationRequest: required: true description: Refund payment confirmation request. content: application/json: schema: $ref: '#/components/schemas/NewRefundPaymentConfirmation' RefundRequestStatusRetrievalRequest: required: true description: Refund Request Status Retrieval Request. content: application/json: schema: $ref: '#/components/schemas/NewRefundRequestStatusRetrieval' parameters: X-Product-ID_2: name: X-Product-ID in: header required: true schema: type: string minLength: 1 maxLength: 50 example: PBARFP description: Unique identifier assigned to the product by Mastercard and given to the participant. X-JWS-Signature: name: X-JWS-Signature in: header required: true description: JWS detached signature is applied to ensure data integrity. schema: type: string example: eyJhbGciOiJSUzI1NiIsImtpZCI6Ik1LMGlrb1k3NFpNdUhnbncwSG1MNnpSbi9rRT0iLCJpYXQiOiIxNjc1OTYyMjA3IiwiY3JpdCI6WyJpYXQiXX0..XRHc_Q7mp49sr0CDL6Ps97uz4Lhl3XG_--JfeZrkj-4LK-3gzc7HsN0Jq4UjO_NX5ZlVp_tfL_GE1g9-vUT0NCfXmfbBXYEaC9CgFZIoU9F2PBegdZwHHmkDbu-5-t6kd2xo4UhaQ5VP1quWOD5yAs2a6MlQstT1iT-gPIW1teaiz4lgCmqbcTo6umjLKL-QsYvJ53Ngtb5rrF5WWQ1WKpGeq_PP1hGYbxDzcYBNZqGed-dXuGqpkWJ85JENJyOKDoskWM6cgs6OAjrmjTIFQ0qdfal91SUQtzJ49nbAiqMpROh79uYJ024jgtcQ_StqYJyJWYdLeUv1ge-kDJN0fw minLength: 1 maxLength: 512 X-Participant-ID: name: X-Participant-ID in: header required: true schema: type: string example: '000545' minLength: 1 maxLength: 50 description: Unique identifier assigned to the participant by Mastercard during onboarding. X-Product-ID: name: X-Product-ID in: header required: true schema: type: string example: PBARFP minLength: 1 maxLength: 50 description: Unique identifier assigned to the product construct by Mastercard and given to the participant. Idempotency-Key: name: Idempotency-Key in: header required: true description: Unique identifier generated by the participant. Mastercard uses this identifier to recognize subsequent retries of the same request and ensure idempotent behaviour by sending the same response without repeating the operation again. schema: type: string format: uuid example: 7da7a728-f910-11e6-942a-68f728c1ba70 minLength: 1 maxLength: 36 refund_request_lifecycle_id: name: refund_request_lifecycle_id in: path required: true description: Unique identifier assigned by Mastercard, to identify the refund request in subsequent transactions or services. schema: type: string example: '245566173931134008' minLength: 1 maxLength: 35 payment_request_lifecycle_id: name: payment_request_lifecycle_id in: path required: true description: Unique identifier assigned by Mastercard, to identify the payment request in subsequent transactions or services. schema: type: string example: '128361739311340082' minLength: 1 maxLength: 35 X-Request-ID: name: X-Request-ID in: header required: true schema: type: string example: 7eab4eab35a542e085add0363a49c035 minLength: 1 maxLength: 50 description: Each API request has an associated request identifier. It can be used to match the response to the request and used for tracing, troubleshooting and analysis purposes. headers: X-Product-ID_2: required: true schema: type: string minLength: 1 maxLength: 50 example: PBARFP description: Unique identifier assigned to the product by Mastercard and given to the participant. X-Participant-ID: required: true schema: type: string minLength: 1 maxLength: 50 example: '000545' description: Unique identifier assigned to the participant by Mastercard during onboarding. X-Request-ID_2: required: true schema: type: string minLength: 1 maxLength: 50 example: 7eab4eab35a542e085add0363a49c035 description: Each API request has an associated request identifier. It can be used to match the response to the request and for tracing, troubleshooting and analysis purposes. X-JWS-Signature: required: true description: JWS detached signature is applied to ensure data integrity. schema: type: string example: eyJhbGciOiJSUzI1NiIsImtpZCI6Ik1LMGlrb1k3NFpNdUhnbncwSG1MNnpSbi9rRT0iLCJpYXQiOiIxNjc1OTYyMjA3IiwiY3JpdCI6WyJpYXQiXX0..XRHc_Q7mp49sr0CDL6Ps97uz4Lhl3XG_--JfeZrkj-4LK-3gzc7HsN0Jq4UjO_NX5ZlVp_tfL_GE1g9-vUT0NCfXmfbBXYEaC9CgFZIoU9F2PBegdZwHHmkDbu-5-t6kd2xo4UhaQ5VP1quWOD5yAs2a6MlQstT1iT-gPIW1teaiz4lgCmqbcTo6umjLKL-QsYvJ53Ngtb5rrF5WWQ1WKpGeq_PP1hGYbxDzcYBNZqGed-dXuGqpkWJ85JENJyOKDoskWM6cgs6OAjrmjTIFQ0qdfal91SUQtzJ49nbAiqMpROh79uYJ024jgtcQ_StqYJyJWYdLeUv1ge-kDJN0fw minLength: 1 maxLength: 512 X-Request-ID: required: true schema: type: string minLength: 1 maxLength: 50 example: 7eab4eab35a542e085add0363a49c035 description: Each API request has an associated request identifier. It can be used to match the response to the request and used for tracing, troubleshooting and analysis purposes. X-Product-ID: required: true schema: type: string minLength: 1 maxLength: 50 example: PBARFP description: Unique identifier assigned to the product construct by Mastercard and given to the participant. examples: BadRequestErrorExample: value: Errors: Error: - Source: ZAPP ReasonCode: STVL-9999 Description: Invalid structure Recoverable: false Details: Invalid structure UnauthorisedExample: value: Errors: Error: - Source: ZAPP ReasonCode: SECU-9999 Description: Invalid signature Recoverable: false Details: Invalid signature