openapi: 3.1.0
info:
  title: Mastercard Payment Gateway REST API
  version: '100'
  description: |
    The Mastercard Payment Gateway exposes a JSON REST API for processing
    payments, managing orders, and integrating hosted checkout, sessions,
    tokenization, 3-D Secure authentication, agreements, batches, and
    wallet operations. All transaction operations on an order use a single
    URL pattern parameterized by merchant, order, and transaction
    identifiers; the specific operation (AUTHORIZE, PAY, CAPTURE, REFUND,
    VOID, VERIFY, etc.) is selected by the `apiOperation` body field.
  contact:
    name: Mastercard Payment Gateway Services
    url: https://ap-gateway.mastercard.com/api/documentation/apiDocumentation/index.html
servers:
  - url: https://ap-gateway.mastercard.com/api/rest/version/100
    description: Asia Pacific gateway
  - url: https://{gateway_host}/api/rest/version/100
    description: Regional or test gateway
    variables:
      gateway_host:
        default: ap-gateway.mastercard.com
security:
  - BasicAuth: []
  - CertificateAuth: []
paths:
  /merchant/{merchantId}/order/{orderid}/transaction/{transactionid}:
    put:
      summary: Submit a transaction on an order
      operationId: transaction
      description: |
        Single endpoint for the Transaction operation set. The action is
        chosen by the `apiOperation` field in the request body, e.g.
        `AUTHORIZE`, `PAY`, `CAPTURE`, `REFUND`, `VOID`, `VERIFY`,
        `STANDALONE_REFUND`, `ACCOUNT_FUNDING_TRANSACTION`.
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/TransactionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [apiOperation]
              properties:
                apiOperation:
                  type: string
                  enum: [AUTHORIZE, PAY, CAPTURE, REFUND, VOID, VERIFY, STANDALONE_REFUND, ACCOUNT_FUNDING_TRANSACTION]
                order:
                  type: object
                  properties:
                    amount:
                      type: string
                      description: Total amount of the order.
                    currency:
                      type: string
                      description: ISO 4217 currency code.
                sourceOfFunds:
                  type: object
                transaction:
                  type: object
      responses:
        '201':
          description: Transaction processed.
        '400':
          description: Invalid request.
        '401':
          description: Authentication failed.
    get:
      summary: Retrieve a transaction
      operationId: retrieveTransaction
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/OrderId'
        - $ref: '#/components/parameters/TransactionId'
      responses:
        '200':
          description: Transaction details.
  /merchant/{merchantId}/order/{orderid}:
    get:
      summary: Retrieve an order and all its transactions
      operationId: retrieveOrder
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/OrderId'
      responses:
        '200':
          description: Order details.
  /merchant/{merchantId}/session:
    post:
      summary: Create a session
      operationId: createSession
      description: |
        Creates a temporary, server-side container of request fields that
        can be referenced by other Gateway requests (e.g. Hosted Checkout
        or Hosted Session).
      parameters:
        - $ref: '#/components/parameters/MerchantId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Session created.
  /merchant/{merchantId}/session/{sessionId}:
    put:
      summary: Update a session
      operationId: updateSession
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - in: path
          name: sessionId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Session updated.
    get:
      summary: Retrieve a session
      operationId: retrieveSession
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - in: path
          name: sessionId
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Session details.
  /merchant/{merchantId}/token:
    post:
      summary: Create a payment token
      operationId: createToken
      parameters:
        - $ref: '#/components/parameters/MerchantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceOfFunds:
                  type: object
                session:
                  type: object
      responses:
        '201':
          description: Token created.
  /merchant/{merchantId}/token/{tokenId}:
    put:
      summary: Create or update a payment token at a specific identifier
      operationId: createOrUpdateToken
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/TokenId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Token created or updated.
    get:
      summary: Retrieve a payment token
      operationId: retrieveToken
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/TokenId'
      responses:
        '200':
          description: Token details.
    delete:
      summary: Delete a payment token
      operationId: deleteToken
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - $ref: '#/components/parameters/TokenId'
      responses:
        '200':
          description: Token deleted.
  /merchant/{merchantId}/3DSecureId/{3DSecureId}:
    put:
      summary: 3-D Secure authentication operation
      operationId: threeDSecure
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - in: path
          name: 3DSecureId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [apiOperation]
              properties:
                apiOperation:
                  type: string
                  enum: [INITIATE_AUTHENTICATION, AUTHENTICATE_PAYER, CHECK_3DS_ENROLLMENT, PROCESS_ACS_RESULT]
      responses:
        '200':
          description: 3-D Secure operation result.
  /merchant/{merchantId}/hostedCheckout:
    post:
      summary: Hosted Checkout initiation helper
      operationId: hostedCheckoutInitiate
      parameters:
        - $ref: '#/components/parameters/MerchantId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Hosted Checkout context.
  /merchant/{merchantId}/batch/{batchId}:
    put:
      summary: Submit or close a batch of operations
      operationId: batch
      parameters:
        - $ref: '#/components/parameters/MerchantId'
        - in: path
          name: batchId
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Batch processed.
  /merchant/{merchantId}/gatewayStatus:
    get:
      summary: Check the gateway availability
      operationId: checkGateway
      parameters:
        - $ref: '#/components/parameters/MerchantId'
      responses:
        '200':
          description: Gateway status.
components:
  parameters:
    MerchantId:
      in: path
      name: merchantId
      required: true
      schema:
        type: string
      description: The merchant ID assigned to you by the gateway.
    OrderId:
      in: path
      name: orderid
      required: true
      schema:
        type: string
      description: Merchant-supplied order identifier.
    TransactionId:
      in: path
      name: transactionid
      required: true
      schema:
        type: string
      description: Merchant-supplied transaction identifier within the order.
    TokenId:
      in: path
      name: tokenId
      required: true
      schema:
        type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: |
        HTTP Basic authentication using `merchant.<merchantId>` as the
        username and the API password (integration password) as the
        password.
    CertificateAuth:
      type: mutualTLS
      description: |
        Client-certificate (mutual TLS) authentication, available as an
        alternative to password-based merchant authentication.