Mastercard Vendors API

swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Vendors 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: Vendors
paths:
  /vendors/{vendor_id}/orders/status:
    post:
      tags:
      - Vendors
      summary: API used by external Vendors to provide the orders status
      description: The Loyalty Rewards Order Management Mastercard API is used by external vendor to provide orders status
      operationId: updateOrderStatus
      parameters:
      - $ref: '#/components/parameters/VendorId'
      requestBody:
        $ref: '#/components/requestBodies/OrderStatusRequest'
      responses:
        '200':
          $ref: '#/components/responses/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequestOrderErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedOrderErrorResponse'
components:
  schemas:
    OrderItemStatus:
      type: object
      properties:
        id:
          type: string
          description: Order Item Id of Vendor
          example: order-item-1
        mcId:
          type: string
          description: Order Item Id of Mastercard
          example: efa03f08-b9c0-11ed-afa1-0242ac120002
        status:
          type: string
          description: Item status
          example: Pending
        trackingNumber:
          type: string
          description: Order tracking number
          example: Track123
        trackingUrl:
          type: string
          description: Order tracking url
          example: https://tracking-url.com/order/123
        errors:
          type: array
          description: order items error list
          items:
            $ref: '#/components/schemas/OrderItemError'
        histories:
          type: array
          description: history detail of order item
          items:
            $ref: '#/components/schemas/History'
    Errors:
      required:
      - Error
      type: object
      properties:
        Error:
          type: array
          description: Error details
          items:
            $ref: '#/components/schemas/ErrorItem'
    History:
      type: object
      properties:
        orderItemNumber:
          type: string
          description: order_item_number
          example: order-item-1
        eventType:
          type: string
          description: event_type
          example: note
        eventDate:
          type: string
          description: event_date
          example: '2023-10-03T21:05:10Z'
        note:
          type: string
          description: note
          example: 'GRS order item created for partner system order number: SL_OCT-03-2023-16-431 Status is pending.'
    ErrorItem:
      type: object
      properties:
        Source:
          type: string
          description: Source of the error
          example: mrs-catalog-api
        ReasonCode:
          type: string
          description: A unique constant identifying the error case encountered during API request processing.
          example: INVALID_INPUT
        Description:
          type: string
          description: Short description of the ReasonCode field.
          example: Invalid Reward Catalog HierarchyId.
        Recoverable:
          type: boolean
          description: Indicates whether this error will always be returned for this request, or retrying could change the outcome.
          example: false
        Details:
          type: string
          description: Where appropriate, indicates detailed information about the data received.
          example: Invalid Details
      description: Error Details
    ErrorsWrapper:
      required:
      - Errors
      type: object
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    OrderStatus:
      type: object
      properties:
        orderId:
          type: string
          description: Order Id of Vendor
          example: 656afd7-2396-54345-34545
        mcOrderId:
          type: string
          description: Order Id of Mastercard
          example: afd72396-b9c0-11ed-afa1-0242ac120002
        orderItems:
          type: array
          description: order items list
          items:
            $ref: '#/components/schemas/OrderItemStatus'
        status:
          type: string
          description: Order Status
          example: Pending
    OrderItemError:
      type: object
      properties:
        fieldName:
          type: string
          description: field name
          example: address1
        code:
          type: string
          description: errorcode
          example: GRS_1001
        message:
          type: string
          description: error message
          example: address1 is required
    OrderStatusArray:
      type: array
      description: order status array list
      items:
        $ref: '#/components/schemas/OrderStatus'
  examples:
    BadOrderRequestExample:
      value:
        Errors:
          Error:
          - Source: rewards-order-management
            ReasonCode: MISSING_REQUIRED_FIELD_VENDORS_UPDATE_ORDER_REQUEST_LIST[0].MC_ORDER_ID
            Description: McOrderId is blank or null.
            Recoverable: false
    UnauthorizedOrderExample:
      value:
        Errors:
          Error:
          - Source: rewards-order-management
            ReasonCode: INVALID_CLIENT_ID
            Description: ClientId doesn't have access to the requested service.
            Recoverable: false
    OrderStatusExample:
      value:
      - orderId: 656afd7-2396-54345-34545
        mcOrderId: afd72396-b9c0-11ed-afa1-0242ac120002
        status: FAILED
        errorCode: 1001
        description: '[Combination of ExternalOrderId: (656afd7-2396-54345-34545) and OrderId: (afd72396-b9c0-11ed-afa1-0242ac120002) invalid.]'
  responses:
    BadRequestOrderErrorResponse:
      description: Something was wrong with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/BadOrderRequestExample'
    UnauthorizedOrderErrorResponse:
      description: User does not have access to the resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorsWrapper'
          examples:
            UnauthorizedExample:
              $ref: '#/components/examples/UnauthorizedOrderExample'
    SuccessResponse:
      description: Status updated successfully
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrderStatusArray'
          examples:
            SuccessRequestExample:
              $ref: '#/components/examples/OrderStatusExample'
  requestBodies:
    OrderStatusRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrderStatusArray'
  parameters:
    VendorId:
      name: vendor_id
      in: path
      description: The internal Mastercard vendor Id for order fulfilment.
      required: true
      schema:
        type: string
      example: carltonone