Mastercard
Mastercard Transactions API

The Transactions API from Mastercard — 6 operation(s) for transactions.
Documentation GitHub OpenAPI
OpenAPI Specification

swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Transactions 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: Transactions
paths:
  /donations/transactions:
    get:
      tags:
      - Transactions
      summary: Donation Transaction Status
      description: This API can retrieve the status of a particular donation transaction by passing the respective transaction Id or correlation Id. To retrieve the transaction status, donor need to provide either the `transactionId` or `correlationId` or both as query parameters. In case both parameters are passed, transaction Id value takes precedence over correlation Id.
      operationId: fetchDonationTransactionStatusGET
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - name: transactionId
        in: query
        description: TransactionId is a unique identifier for the donation at Mastercard Donate platform. It is recommended to pass the transactionId as query parameter by the customer while retrieving its status. If correlation Id not passed as query parameter, then this field becomes mandatory.
        required: false
        schema:
          type: string
          example: OTimfp86SL6Q7eaRRh2KfA
      - name: correlationId
        in: query
        description: CorrelationId is a unique donation request ID. It is recommended to pass the x-correlation-id by the customer while retrieving the donation transaction status. If transaction Id not passed as query parameter, then this field becomes mandatory.
        required: false
        schema:
          type: string
          example: 03f8c4e8-8bdc-4a30-a2b4-b6f989e96ca3
      responses:
        '200':
          $ref: '#/components/responses/RetrieveTransactionStatus'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error-DonationTransactionStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error-InternalServerError'
      deprecated: false
  /donors/{donor_id}/transactions:
    post:
      tags:
      - Transactions
      summary: Donation History API
      description: Get Donation History based on given request."cardID", "charityID" and "donationType" are optional fields. If a Micro donation is setup, it won't show up in Donation History until the end of the month when the transaction happen. Encrypting request body is not required.
      operationId: getDonationHistoryUsingPOST
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/CorrelationId'
      - $ref: '#/components/parameters/ProgramId'
      - $ref: '#/components/parameters/Donor'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      requestBody:
        $ref: '#/components/requestBodies/DonationHistory'
      responses:
        '200':
          $ref: '#/components/responses/DonationHistoryPaged'
        '201':
          $ref: '#/components/responses/Created'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/Unsupported'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: false
  /donations/program/{programId}/transactions:
    post:
      tags:
      - Transactions
      summary: Program Transaction History API
      description: Get Program Transaction History Details based on retrieves a list of donation transactions by programId in a given timeframe."cardID", "charityID" and "donationType" are optional fields. If a Micro donation is setup, it won't show up in Program Transaction History until the end of the month when the transaction happen. Encrypting request body is not required.
      operationId: getProgramTransactionHistoryUsingPOST
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/CorrelationId'
      - $ref: '#/components/parameters/Programid'
      - $ref: '#/components/parameters/donorId'
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      requestBody:
        $ref: '#/components/requestBodies/ProgramTransactionHistoryRequest'
      responses:
        '200':
          $ref: '#/components/responses/ProgramTransactionHistoryPaged'
        '201':
          $ref: '#/components/responses/Created'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '415':
          $ref: '#/components/responses/Unsupported'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: false
  /donations/non-ma/transactions:
    post:
      tags:
      - Transactions
      summary: Upload Non Mastercard Brand Card transactions API
      description: This API is to be used by API Consumer to upload the non-Mastercard transactions details to the Donate Platform.
      operationId: uploadDonationNonMA
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/ProgramId'
      - name: x-correlation-id
        in: header
        description: CorrelationId is a unique donation request ID. It is recommended to pass the x-correlation-id by the customer and to use the format "bankname_UUID" (bank name can be indicated using the first 4 digits). Maximum length of this field should be 100 alphanumeric characters. If not passed, Mastercard will generate it. ***Note:*** If there is a timeout when doing the guest api call, it is important to redo the same api call with same x-correlation-id to get the status of the previous api call
        required: false
        schema:
          type: string
          example: 03f8c4e8-8bdc-4a30-a2b4-b6f989e96ca3
      requestBody:
        $ref: '#/components/requestBodies/UploadNonMACardTrxRequest'
      responses:
        '200':
          $ref: '#/components/responses/UploadNonMACardTrxResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error-IncorrectNonMACardTransactionData'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error-InternalServerError'
      deprecated: false
  /api/orders:
    post:
      tags:
      - Transactions
      summary: Searches order details based on the search criteria
      description: Search for orders based on transaction fields that you currently support
      operationId: getTransactionDetails
      parameters:
      - $ref: '#/components/parameters/eth_date'
      - $ref: '#/components/parameters/authorization'
      requestBody:
        $ref: '#/components/requestBodies/OrderApi'
      responses:
        '200':
          $ref: '#/components/responses/OrderApiAcknowledgement'
        '400':
          $ref: '#/components/responses/BadRequest_2'
        '401':
          $ref: '#/components/responses/Unauthorized_2'
        '403':
          $ref: '#/components/responses/Forbidden_2'
        '405':
          $ref: '#/components/responses/MethodNotAllowed'
  /transactions:
    post:
      tags:
      - Transactions
      responses:
        '200':
          $ref: '#/components/responses/TransactionResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
      description: Provides merchants transaction or device or identity scores to help with pre-authorization and pre-authentication decisioning. Using this API enables merchants or acquirer to be able to catch fraud early on & reduce fraudulent transactions while improving their risk models.
      summary: Mastercard Response Will Be Individual and Device Insights for Mvp.
      operationId: retrieveTransactionInsights
      requestBody:
        $ref: '#/components/requestBodies/TransactionRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  requestBodies:
    ProgramTransactionHistoryRequest:
      description: ProgramTransactionHistoryRequest
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProgramTransactionHistory'
      required: true
    UploadNonMACardTrxRequest:
      description: uploadNonMATransactions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UploadNonMACardTrxRequest'
      required: false
    DonationHistory:
      description: donationHistoryRequest
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DonationHistory'
      required: true
    OrderApi:
      description: The request object Merchant API expects
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrderApi'
    TransactionRequest:
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TransactionInsightsData'
  schemas:
    PagedResult_RealTimeTransaction_DonationHistoryResponse_:
      type: object
      properties:
        items:
          type: array
          description: Items
          items:
            $ref: '#/components/schemas/DonationHistoryRes'
        limit:
          type: integer
          example: 25
          format: int32
          minLength: 1
          maxLength: 5
          description: Limit
        offset:
          type: integer
          example: 10
          format: int32
          minLength: 1
          maxLength: 10
          description: Offset
        totalItems:
          type: integer
          example: 60
          format: int64
          minLength: 1
          maxLength: 10
          description: Total Items
      title: PagedResult�DonationHistoryResponse�
      description: ONE-TIME or Monthly transactions will be returned in list,because for monthly setup one real time transaction happens and then monthly donation is started
    Error-415:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused
          properties:
            Error:
              type: array
              description: Only returned in the event of an authorization is failed.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: DONATE_SERVICE
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: UNSUPPORTED_CONTENT_TYPE
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: The request Content-Type (<request content-type value>) is not supported for this service
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    Error-InternalServerError:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused
          properties:
            Error:
              type: array
              description: Only returned in the event of an authorization is failed.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: DONATE_SERVICE
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: INTERNAL_SERVER_ERROR
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: An error occurred on the server.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    Error-DonationTransactionStatus:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          properties:
            Error:
              type: array
              description: Only returned in the event of an error condition.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: DONATE_SERVICE
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: INVALID_TXN_OR_CORRELATION_ID
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: No record found in DB. Please verify client-id/transactionId/correlationId passed in the request and re-try.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: null
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    Error-401:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused due to authorization failure
          properties:
            Error:
              type: array
              description: Only returned in the event of an authorization is failed.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: Gateway
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: AUTHENTICATION_FAILED
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: OAuth signatures did not match.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    Error-403:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused due to forbidden requests
          properties:
            Error:
              type: array
              description: Only returned in the event of forbidden request.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: Gateway
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: INVALID_KEY
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: The signing certificate is not valid.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    ProgramTransactionHistoryPaged:
      type: object
      properties:
        limit:
          type: integer
          example: 25
          format: int32
          minLength: 1
          maxLength: 5
          description: Limit
        offset:
          type: integer
          example: 10
          format: int32
          minLength: 1
          maxLength: 10
          description: Offset
        totalTransactions:
          type: integer
          example: 60
          format: int64
          minLength: 1
          maxLength: 10
          description: Total Transactions
        filteredTransactions:
          type: integer
          example: 60
          format: int64
          minLength: 1
          maxLength: 10
          description: Filtered Transactions
        realTimeTransaction:
          $ref: '#/components/schemas/PagedResult_RealTimeTransaction_ProgramTransactionHistoryResponse_'
        recurringTransaction:
          $ref: '#/components/schemas/PagedResult_RecurringTransaction_ProgramTransactionHistoryResponse_'
      title: ProgramTransactionHistoryPaged
    Error-201:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused
          properties:
            Error:
              type: array
              description: Only returned in the event of an authorization is failed.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: Gateway
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: CREATED
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: OAuth signatures did not match.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    PagedResult_RecurringTransaction_DonationHistoryResponse_:
      type: object
      properties:
        items:
          type: array
          description: Items
          items:
            $ref: '#/components/schemas/DonationHistoryRes'
        limit:
          type: integer
          example: 25
          format: int32
          minLength: 1
          maxLength: 5
          description: Limit
        offset:
          type: integer
          example: 10
          format: int32
          minLength: 1
          maxLength: 10
          description: Offset
        totalItems:
          type: integer
          example: 60
          format: int64
          minLength: 1
          maxLength: 10
          description: Total Items
      title: PagedResult�DonationHistoryResponse�
      description: All Micro OR Monthly transactions will be returned in list
    PagedResult_RealTimeTransaction_ProgramTransactionHistoryResponse_:
      type: object
      properties:
        items:
          type: array
          description: Items
          items:
            $ref: '#/components/schemas/DonationHistoryRes'
        limit:
          type: integer
          example: 25
          format: int32
          minLength: 1
          maxLength: 5
          description: Limit
        offset:
          type: integer
          example: 10
          format: int32
          minLength: 1
          maxLength: 10
          description: Offset
        totalItems:
          type: integer
          example: 60
          format: int64
          minLength: 1
          maxLength: 10
          description: Total Items
      title: PagedResult�ProgramTransactionHistoryResponse�
      description: ONE-TIME or Monthly transactions will be returned in list,because for monthly setup one real time transaction happens and then monthly donation is started
    ProgramTransactionHistory:
      type: object
      required:
      - fromDate
      - toDate
      properties:
        cardId:
          type: string
          example: ebee3d81-18d4-409a-8330-73db083f2cfc
          minLength: 36
          maxLength: 36
          description: Card Id (UUID)
        charityId:
          type: string
          example: ae3c5f35-084a-4df9-a2af-7e0efd512fc0
          minLength: 36
          maxLength: 36
          description: Charity Id (UUID)
        donorId:
          type: string
          minLength: 36
          maxLength: 36
          example: 652ce9ff-fa5f-4e9f-8151-c73fa20088f7
          format: uuid
          description: Valid UUID.
        donationType:
          type: string
          example: Micro
          minLength: 5
          maxLength: 20
          description: Donation Type
        fromDate:
          type: string
          example: '2019-02-25'
          minLength: 10
          maxLength: 10
          description: From Date
        toDate:
          type: string
          example: '2020-02-25'
          minLength: 10
          maxLength: 10
          description: To Date
        transactionStatus:
          type: string
          example: SUCCESS
          minLength: 3
          maxLength: 30
          description: Transaction Status
        limit:
          type: integer
          example: 25
          format: int32
          minLength: 1
          maxLength: 5
          description: Limit
        offset:
          type: integer
          example: 10
          format: int32
          minLength: 1
          maxLength: 10
          description: Offset
      title: ProgramTransactionHistory
    DonationHistoryRes:
      type: object
      properties:
        amount:
          type: number
          format: double
          example: 11
          minLength: 1
          maxLength: 20
          description: Amount
        cardId:
          type: string
          example: ebee3d81-18d4-409a-8330-73db083f2cfc
          minLength: 36
          maxLength: 36
          description: Card Id (UUID)
        charityId:
          type: string
          example: ae3c5f35-084a-4df9-a2af-7e0efd512fc0
          minLength: 36
          maxLength: 36
          description: Charity Id (UUID)
        charityName:
          type: string
          example: WFP
          minLength: 3
          maxLength: 30
          description: Charity Name
        clientId:
          type: string
          example: 0a7e433a-63fc-4557-8cf4
          minLength: 3
          maxLength: 30
          description: Client Id
        currency:
          type: string
          example: USD
          minLength: 3
          maxLength: 3
          description: Currency
        date:
          type: string
          example: '2021-09-03'
          format: date
          minLength: 10
          maxLength: 10
          description: Date
        donationType:
          type: string
          example: Micro
          minLength: 5
          maxLength: 20
          description: Donation Type
        donorId:
          type: string
          example: 652ce9ff-fa5f-4e9f-8151-c73fa20088f7
          minLength: 36
          maxLength: 36
          description: Donor Id (UUID)
        orderId:
          type: string
          example: 5dfa4509-1bf2-425b-965b-d44dd11f5f95
          minLength: 36
          maxLength: 36
          description: Order Id
        paymentNetwork:
          type: string
          example: mastercard
          minLength: 3
          maxLength: 30
          description: Payment Network
        primaryAccountNumberSuffix:
          type: string
          example: '3538'
          minLength: 4
          maxLength: 4
          description: PAN Suffix
        programId:
          type: string
          example: 80380ef2-5037-4e57-86bf-1bdd1efb0ae2
          minLength: 36
          maxLength: 36
          description: Program Id (UUID)
        transactionId:
          type: string
          example: 3311e859-3ee4-4155-a640-8cae447c27ca
          minLength: 36
          maxLength: 36
          description: Transaction Id
        transactionStatus:
          type: string
          example: SUCCESS
          minLength: 3
          maxLength: 30
          description: Transaction Status
        updatedDate:
          type: string
          example: '2021-09-14'
          format: date
          minLength: 10
          maxLength: 10
          description: Updated Date
      title: DonationHistoryResponse
    Transactions:
      type: object
      required:
      - transactionId
      - transactionDate
      - amount
      properties:
        transactionId:
          type: string
          example: 3311e859-3ee4-4155-a640-8cae447c27ca
          minLength: 36
          maxLength: 36
          description: Transaction Id
        transactionDate:
          type: string
          example: '2021-09-03'
          format: date
          minLength: 10
          maxLength: 10
          description: Date of the transaction
        amount:
          type: string
          example: 50
          minLength: 3
          maxLength: 30
          description: Transaction amount
      title: Transactions
    RetrieveTransactionStatus:
      type: object
      properties:
        transactionId:
          type: string
          example: OTimfp86SL6Q7eaRRh2KfA
          minLength: 22
          maxLength: 22
          description: Transaction Id
        transactionStatus:
          type: string
          example: SUCCESS
          minLength: 5
          maxLength: 20
          description: Transaction Status
        transactionMessage:
          type: string
          example: Transaction APPROVED.
          minLength: 3
          maxLength: 30
          description: Transaction Message
      title: RetrieveTransactionStatus
    Error-404:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused due to resource not found
          properties:
            Error:
              type: array
              description: Only returned in the event of an resource not found.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: Gateway
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: NOT_FOUND
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: The signing certificate is not valid.
                    description: Short description of the ReasonCode field
                  Recoverable:
                    type: boolean
                    example: false
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome
                  Details:
                    type: string
                    example: 'null'
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
    UploadNonMACardTrxRequest:
      type: object
      required:
      - currencyCode
      - transactionsSummary
      properties:
        currencyCode:
          type: string
          example: USD
          minLength: 3
          maxLength: 3
          description: Currency
        transactionsSummary:
          $ref: '#/components/schemas/TransactionsSummary'
      title: UploadNonMACardTrxRequest
    DonationHistory:
      type: object
      required:
      - fromDate
      - toDate
      properties:
        cardId:
          type: string
          example: ebee3d81-18d4-409a-8330-73db083f2cfc
          minLength: 36
          maxLength: 36
          description: Card Id (UUID)
        charityId:
          type: string
          example: ae3c5f35-084a-4df9-a2af-7e0efd512fc0
          minLength: 36
          maxLength: 36
          description: Charity Id (UUID)
        donationType:
          type: string
          example: Micro
          minLength: 5
          maxLength: 20
          description: Donation Type
        fromDate:
          type: string
          example: '2019-02-25'
          minLength: 10
          maxLength: 10
          description: From Date
        toDate:
          type: string
          example: '2020-02-25'
          minLength: 10
          maxLength: 10
          description: To Date
        transactionStatus:
          type: string
          example: SUCCESS/PENDING/FAILURE/ALL
          minLength: 3
          maxLength: 30
          description: Transaction Status
      title: DonationHistoryRequest
    UploadNonMACardResponse:
      type: string
      example: '{Data load for Non MA Card Transactions is success.}'
    TransactionsSummary:
      type: object
     

# --- truncated at 32 KB (182 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mastercard/refs/heads/main/openapi/mastercard-transactions-api-openapi.yml
Mastercard Transactions API

Documentation

Specifications

Code Examples

Other Resources

OpenAPI Specification
