Mastercard Confirmations API

openapi: 3.2.0
info:
  title: Mastercard Debtor Service Provider Resources Confirmations API
  description: Online checkouts can be frustrating and tedious. As shopping habits shift to digital, consumers and merchants require secure and streamlined online experiences. Mastercard Account to Account Commerce enables debtor service providers (DSP) to provide their debtors (customers) with a fast, secure, and convenient way to pay using their mobile banking app.= Through Account to Account Commerce, the debtors can view their balance before checkout, initiate refunds, and use their accounts for recurring payments or frequent purchases.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 1.2.1
servers:
- url: https://mtf.services.mastercard.com/zapp/pbarfp/dsp
  description: Mastercard Test Facility (MTF) is a Production-like environment that enables DSP and Creditor Service Provider (CSP) to integrate and test end to end solution with Mastercard APIs.
- url: https://services.mastercard.com/zapp/pbarfp/dsp
  description: Production environment.
tags:
- name: Confirmations
paths:
  /payment-requests/{payment_request_lifecycle_id}/payment-confirmation-advices:
    post:
      tags:
      - Confirmations
      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'
      - $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
components:
  headers:
    X-Product-ID:
      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:
      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:
      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:
      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.
  schemas:
    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.
    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
          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.
        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.
    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.
    PaymentConfirmationAdvice:
      allOf:
      - $ref: '#/components/schemas/MessageResponseBlock'
      - 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'
    ErrorWrapper:
      description: A top level object for errors.
      type: object
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    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.
    Errors:
      description: Object that contains the list of errors.
      type: object
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    ErrorList:
      description: The list of errors.
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    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.
    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'
    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
    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 the request message.
    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.
    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.
    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.
  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
  parameters:
    X-Participant-ID:
      name: X-Participant-ID
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 50
        example: '000545'
      description: Unique identifier assigned to the participant by Mastercard during onboarding.
    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
        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:
      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.
    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
    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
  responses:
    PaymentConfirmationAdviceResponse:
      description: Payment Request Status update 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/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'
    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:
    PaymentConfirmationAdviceRequest:
      required: true
      description: Payment Request Confirmation Advice.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewPaymentConfirmationAdvice'