swagger: '2.0' info: title: Mastercard Bill Payment Validator Account Opening Payment Requests 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: Payment Requests paths: /payment-requests/{payment_request_lifecycle_id}/status-retrievals: post: tags: - Payment Requests summary: Mastercard Payment Request Status Retrieval Request. description: Enables Mastercard to retrieve payment request status from DSP. operationId: retrievePaymentRequestStatus 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/PaymentRequestStatusRetrievalRequest' responses: '200': $ref: '#/components/responses/PaymentRequestStatusRetrievalResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorisedErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /payment-request-retrievals: post: tags: - Payment Requests summary: Mastercard Retrieve Payment Request Details. description: Enables DSP to retrieve request for payment using either paymentRequestLifecycleId or paymentRequestReferenceNumber to present it to the debtor and obtain consent for funds transfer. operationId: retrievePaymentRequest 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' requestBody: $ref: '#/components/requestBodies/PaymentRequestDetailRetrievalRequest' responses: '200': $ref: '#/components/responses/PaymentRequestDetailRetrievalResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorisedErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /payment-requests/{payment_request_lifecycle_id}/payment-confirmation-advices: post: tags: - Payment Requests summary: Mastercard Confirm Payment description: Enables DSP to send payment status information for the request for payment message. operationId: confirmPaymentAdvice 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/payment_request_lifecycle_id' requestBody: $ref: '#/components/requestBodies/PaymentConfirmationAdviceRequest' responses: '200': $ref: '#/components/responses/PaymentConfirmationAdviceResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorisedErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK /payment-requests/{payment_request_lifecycle_id}/step-up-advices: post: tags: - Payment Requests summary: Mastercard Step-up Advice description: Enables DSP to send step-up advice to CSP through Mastercard. operationId: createStepUpAdvice 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/payment_request_lifecycle_id' requestBody: $ref: '#/components/requestBodies/StepUpNotificationRequest' responses: '200': $ref: '#/components/responses/StepUpNotificationResponse' '400': $ref: '#/components/responses/BadRequestErrorResponse' '401': $ref: '#/components/responses/UnauthorisedErrorResponse' x-microcks-operation: delay: 0 dispatcher: FALLBACK components: schemas: Payment: type: object required: - paymentReference - clearingSystem - paymentDateTime - paymentAmount properties: paymentReference: type: string minLength: 1 maxLength: 42 example: y18dvGsj3GJ57Tt description: Unique Payment Reference of the real time settlement method provided by DSP. 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. paymentDateTime: 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 real time settlement is initiated. paymentAmount: description: The actual amount that has been transferred from the Debtor to the Creditor. allOf: - $ref: '#/components/schemas/Amount' example: example_value PaymentConfirmationAdvice: allOf: - $ref: '#/components/schemas/MessageResponseBlock_2' - type: object required: - paymentRequestLifecycleId - requestStatus 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. requestStatus: $ref: '#/components/schemas/RequestStatus' agreementStatus: $ref: '#/components/schemas/AgreementStatus' CreditorAckForPaymentRetrieval: type: object required: - creditorId - creditorServiceProviderId - creditorTradeName - creditorCategoryCode 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. creditorCategoryCode: type: string example: '0742' minLength: 4 maxLength: 4 description: The category code of the Creditor, also known as Merchant Category Code (MCC). Enables the classification of Creditors into specific categories based on the type of business, trade or services supplied. creditorTradeName: type: string example: VerizonoMobileLtd minLength: 1 maxLength: 35 description: Name used by the Creditor in dealing with customers, which may not be the same as the one it uses for legal purposes. creditorReturnString: type: string example: https://www.creditor.com/creditorreturnstring minLength: 1 maxLength: 512 description: Return string (in URL encoded format) that is passed to the DSP to return the Debtor back to the Creditor's page. creditorLogoUrl: type: string example: https://www.cdn.com/creditorlogourl minLength: 1 maxLength: 512 description: Creditor's Logo (in URL encoded format). Can be used by the Debtor to display the Creditor's Logo. creditorAccount: type: object required: - accountNumber description: Creditor's Account Information. Either the IBAN or account number should be used. This is provided only for Me-to-Me payments. properties: accountNumber: type: string x-guarded-string: 'true' example: '45122351223323' minLength: 1 maxLength: 35 description: Unique identifier for each account assigned by a financial institution or wallet provider. For example, IBAN. If sort code or routing number is 451223 and account number is 51223323, then after concatenation, the account number will be 45122351223323. clearingSystem: type: string example: FPS minLength: 1 maxLength: 35 description: Creditor or CSP requested real-time settlement method. * Refer to Codes and Formats section for more details. example: example_value creditorAccounts: type: array deprecated: true description: Creditor's Account Information. Either of the IBAN or Other account should be used. (This "creditorAccounts" block is deprecated, use "creditorAccount" block) items: type: object properties: iban: type: string x-guarded-string: 'true' example: GB54HBUK60161331926819 minLength: 1 maxLength: 35 description: International Bank Account Number to uniquely identify the account. other: type: object description: Unique identification of an account. required: - accountNumber properties: accountNumber: type: string x-guarded-string: 'true' example: '45122351223323' minLength: 1 maxLength: 35 description: Unique Identifier for each account assigned by a financial institution. For example, if sort code or routing number is 451223 and account number is 51223323, then after concatenation the account number will be 45122351223323. clearingSystems: type: array items: type: string example: - FPS description: Creditor or CSP requested real-time settlement method. * Refer to Codes and Formats section for more details. example: [] AgreementStatus: type: object required: - agreementId - agreementStatus properties: agreementId: type: string example: a3e2a749088440eab8b40c926efe2931 minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard to the agreement. agreementStatus: type: string example: APPR minLength: 4 maxLength: 4 description: Status of the Agreement updated by DSP to either Approved or Rejected or Deleted. * Refer to Codes and Formats section for more details. NewPaymentRequestDetailRetrieval: allOf: - $ref: '#/components/schemas/MessageRequestBlock' - type: object required: - transaction properties: transaction: $ref: '#/components/schemas/TransactionForPaymentRetrieval' NewStepUpNotification: allOf: - $ref: '#/components/schemas/MessageRequestBlock' - type: object required: - transaction - debtorServiceProviderId properties: debtorServiceProviderId: type: string example: 000369 minLength: 1 maxLength: 35 description: Unique identifier assigned to the DSP during Mastercard onboarding. transaction: $ref: '#/components/schemas/TransactionForStepUpNotification' DebtorAckForPaymentRetrieval: 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. Status: type: object required: - transactionStatus properties: transactionStatus: type: string example: RJCT maxLength: 4 minLength: 4 description: Status of the transaction. * Refer to Codes and Formats section for more details. transactionStatusReason: type: string example: FRDS maxLength: 4 minLength: 4 description: Reason for declined transaction. * Refer to Codes and Formats section for more details. 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." NewPaymentConfirmationAdvice: allOf: - $ref: '#/components/schemas/MessageRequestBlock' - type: object required: - paymentRequestLifecycleId - status - debtor - acceptanceDateTime 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. acceptanceDateTime: type: string format: date-time example: '2020-11-20T06:57:24.465Z' description: ISO 8601 format date and time in Coordinated Universal Time (UTC) on when the Debtor has accepted or rejected the request. creditAccountUsed: type: boolean example: true description: Indicator to specify when a Credit account is used for the payment. authorisedByDebtor: type: boolean example: false description: Indicator whether the Consumer authorised the account on file transaction which was stepped up. paymentRequestStatusRetrievalLifecycleId: type: string example: '111123123123123111' minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify the Payment Request Status Retrieval request in subsequent transactions or services. debtor: $ref: '#/components/schemas/Debtor' status: $ref: '#/components/schemas/Status' payment: $ref: '#/components/schemas/Payment' agreementConfirmation: $ref: '#/components/schemas/AgreementConForPaymentAdvice' TransactionAcknowledgement: type: object required: - endToEndId - instructedAmount - paymentRequestLifecycleId - categoryPurpose - confirmationExpiryTimeInterval - paymentRequestType - instructionId - transactionCreationDateTime - purpose 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. endToEndId: type: string example: 7jhg5eab35a542e085add0363a4423o6 minLength: 1 maxLength: 35 description: Unique identifier assigned by Creditor to identify Payment Request in their system. instructionId: type: string example: 98dj4eab35a542e085add0363a40jk564 minLength: 1 maxLength: 60 description: Unique identifier for the transaction assigned by the transaction initiator (CSP). accountServicerReference: type: string example: '12254935976349875' minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify a particular payment (also referred to as settlement identifier) associated with a Payment Request. reconId: type: string example: RECON1201202201 minLength: 1 maxLength: 15 description: Reconciliation identifier assigned by Mastercard to the transaction. confirmationExpiryTimeInterval: type: number example: 150 description: Time window given in seconds within which the Payment Confirmation must be received by the Mastercard. paymentRequestType: type: string example: IMDT minLength: 4 maxLength: 4 description: Set by the Creditor/CSP to define the settlement type of the Payment Request. * Refer to Codes and Formats section for more details. transactionCreationDateTime: type: string format: date-time example: '2020-11-20T06:57:24.465Z' description: ISO 8601 format date and time in Coordinated Universal Time (UTC) the Payment Request was created. instructedAmount: description: The total amount of the payment request, as specified by the Creditor. allOf: - $ref: '#/components/schemas/Amount' example: example_value purpose: type: string example: ONLN minLength: 1 maxLength: 35 description: Set by Creditor/CSP to indicate the Payment Request type. * Refer to Codes and Formats section for more details. categoryPurpose: type: string example: PYMT minLength: 1 maxLength: 35 description: Set by the Creditor/CSP to offer specific transaction processing. * Refer to Codes and Formats section for more details. restriction: type: string example: 18PLUS minLength: 1 maxLength: 30 description: Set by the Creditor/CSP to communicate any restrictions to be verified by DSP before payment authorization. * Refer to Codes and Formats section for more details. creditAccountAllowed: type: boolean example: true description: Indicator to specify Credit account can be used for the payment. strongCustomerAuthentication: type: boolean example: true description: Indicates a request from Creditor to DSP to step-up authentication for the transaction. Debtor: 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. CreditorForSRR: 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. AgreementConForPaymentAdvice: description: Agreement Confirmation from DSP type: object required: - agreementConfirmed properties: agreementConfirmed: type: boolean example: true description: Indicates true whether Agreement was confirmed by Debtor. False for any other reasons. agreementStatusReason: type: string example: SYSP maxLength: 4 minLength: 4 description: Reason for declined agreement. * Refer to Codes and Formats section for more details. accountNickname: type: string x-guarded-string: 'true' example: bankname_account minLength: 1 maxLength: 35 description: Nickname of the account is passed when agreementConfirmed is true. ErrorWrapper: description: A top level object for errors type: object required: - Errors properties: Errors: $ref: '#/components/schemas/Errors' PaymentRequestStatusRetrievalAck: allOf: - $ref: '#/components/schemas/MessageResponseBlock' - type: object required: - paymentRequestStatusRetrievalLifecycleId - retrievalRequestStatus properties: paymentRequestStatusRetrievalLifecycleId: type: string example: '111123123123123111' minLength: 1 maxLength: 35 description: Unique identifier assigned by Mastercard, to identify the Payment 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. 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. StepUpNotification: allOf: - $ref: '#/components/schemas/MessageResponseBlock_2' PaymentRequestDetailRetrieval: allOf: - $ref: '#/components/schemas/MessageResponseBlock_2' - type: object required: - creditor - debtor - transaction properties: debtor: $ref: '#/components/schemas/DebtorAckForPaymentRetrieval' creditor: $ref: '#/components/schemas/CreditorAckForPaymentRetrieval' transaction: $ref: '#/components/schemas/TransactionAcknowledgement' agreementType: type: string example: AOF minLength: 1 maxLength: 4 description: Creditor requesting DSP to display to Debtor to setup Agreement during payment confirmation. * Refer to Codes and Formats section for more details. Errors: description: Object that contains the list of errors type: object required: - Error properties: Error: $ref: '#/components/schemas/ErrorList' RequestStatus: type: object required: - paymentRequestStatus properties: paymentRequestStatus: type: string example: RJCT maxLength: 4 minLength: 4 description: Status of the Payment Request returned by Mastercard. * Refer to Codes and Formats section for more details. NewPaymentRequestStatusRetrieval: allOf: - $ref: '#/components/schemas/MessageRequestBlock' - type: object required: - paymentRequestLifecycleId - creditor 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. creditor: $ref: '#/components/schemas/CreditorForSRR' 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. TransactionForStepUpNotification: type: object required: - paymentRequestLifecycleId - stepUpMessage 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. stepUpMessage: type: string example: Please go to your Banking App and Authorise the transaction minLength: 1 maxLength: 250 description: Text message that DSP will be providing to display to the Debtor on Creditor website or application. applicationUrl: type: string example: zapp://812768758639876189746 minLength: 1 maxLength: 512 description: URL that will be used by the Debtor to open the banking app from Creditor's website or application on a single device journey. Creditor should only use this when it's a single device journey. 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. TransactionForPaymentRetrieval: type: object required: - debtorServiceProviderId - debtorId - retrieveInitMethod 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. 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. retrieveInitMethod: type: string example: INTENT minLength: 1 maxLength: 30 description: Set by DSP to specify Payment Request retrieval initiation method. * Refer to Codes and Formats section for more details. paymentRequestReferenceNumber: type: string example: '789563' minLength: 6 maxLength: 6 description: Unique 6 character reference provided by Mastercard to the CSP to be conveyed to the Debtor to make a payment. 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 requestBodies: StepUpNotificationRequest: required: true description: Step Up Notification. content: application/json: schema: $ref: '#/components/schemas/NewStepUpNotification' PaymentConfirmationAdviceRequest: required: true description: Payment Request Confirmation Advice. content: application/json: schema: $ref: '#/components/schemas/NewPaymentConfirmationAdvice' PaymentRequestDetailRetrievalRequest: required: true description: Retrieve Payment Request. content: application/json: schema: $ref: '#/components/schemas/NewPaymentRequestDetailRetrieval' PaymentRequestStatusRetrievalRequest: required: true description: Payment request status retrieval request. content: application/json: schema: $ref: '#/components/schemas/NewPaymentRequestStatusRetrieval' 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 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. responses: PaymentRequestDetailRetrievalResponse: description: Payment Request creation successful. 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' X-JWS-Signature: $ref: '#/components/headers/X-JWS-Signature' content: application/json: schema: $ref: '#/components/schemas/PaymentRequestDetailRetrieval' PaymentRequestStatusRetrievalResponse: description: Payment request Status Retrieval Request was successfully received by Mastercard. 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/PaymentRequestStatusRetrievalAck' PaymentConfirmationAdviceResponse: description: Payment Request Status update successful. 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' X-JWS-Signature: $ref: '#/components/headers/X-JWS-Signature' content: application/json: schema: $ref: '#/components/schemas/PaymentConfirmationAdvice' 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' StepUpNotificationResponse: description: Step Up Notification Request creation successful. 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' X-JWS-Signature: $ref: '#/components/headers/X-JWS-Signature' content: application/json: schema: $ref: '#/components/schemas/StepUpNotification' 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' 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