Mastercard Agreements API

openapi: 3.2.0
info:
  title: Mastercard Account to Account Commerce for Creditor Service Providers Agreements 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 creditor service providers (CSP) to provide their creditors (merchants) and debtors (consumers) with an intuitive checkout experience that will improve the overall online payments experience, reduce friction at checkout, and improve customer conversions. Through Account to Account Commerce, creditors can initiate payment requests, offer refunds, and offer account-on-file services to debtors of participating debtor service providers.
  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/csp
  description: Mastercard Test Facility (MTF) is a Production-like environment that enables DSP and CSP to integrate and test end to end solution with Mastercard APIs.
- url: https://services.mastercard.com/zapp/pbarfp/csp
  description: Production environment
tags:
- name: Agreements
  description: API endpoints used by CSP to create agreements and manage lifecycle of agreements.
paths:
  /agreements:
    post:
      tags:
      - Agreements
      summary: Mastercard Agreement Creation.
      description: Enables the CSP to present request for agreement creation.
      operationId: createAgreement
      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'
      requestBody:
        $ref: '#/components/requestBodies/CreditorAgreementCreationRequest'
      responses:
        '200':
          $ref: '#/components/responses/CreditorAgreementCreationResponse'
        '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 construct 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 used for tracing, troubleshooting and analysis purposes.
  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
        example: '000545'
        minLength: 1
        maxLength: 50
      description: Unique identifier assigned to the participant by Mastercard during onboarding.
    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.
    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
    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
  schemas:
    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.
    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'
    CreditorForAgreementCreation:
      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.
        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 checkout page.
    AgreementCreation:
      allOf:
      - $ref: '#/components/schemas/MessageResponseBlock'
      - type: object
        required:
        - confirmationExpiryTimeInterval
        - agreement
        properties:
          confirmationExpiryTimeInterval:
            type: number
            example: 430
            description: Time window given in seconds within which the Agreement Confirmation must be received by the Creditor.
          agreement:
            $ref: '#/components/schemas/AgreementAckForAgmtCreation'
    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."
    NewAgreementCreation:
      allOf:
      - $ref: '#/components/schemas/MessageRequestBlock'
      - type: object
        required:
        - creditor
        - agreementType
        properties:
          categoryPurpose:
            type: string
            example: EP2M
            minLength: 1
            maxLength: 35
            description: Set by the Creditor/CSP to offer specific transaction processing. * Refer to Codes and Formats section for more details. This field (although optional) should always be provided to indicate the correct categoryPurpose to be associated with the agreement. If not provided, will be defaulted to MTOM (Me to Me Payments)
          creditor:
            $ref: '#/components/schemas/CreditorForAgreementCreation'
          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.
    AgreementAckForAgmtCreation:
      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: INPR
          minLength: 4
          maxLength: 4
          description: Agreement Status returned by Mastercard. * Refer to Codes and Formats section for more details.
        agreementReferenceNumber:
          type: string
          example: '789563'
          minLength: 6
          maxLength: 6
          description: Unique 6 digit reference provided by Mastercard to the CSP to be conveyed to the Debtor in order to create an agreement.
  responses:
    CreditorAgreementCreationResponse:
      description: 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'
        X-JWS-Signature:
          $ref: '#/components/headers/X-JWS-Signature'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AgreementCreation'
    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:
    CreditorAgreementCreationRequest:
      required: true
      description: Create agreement request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewAgreementCreation'