Mastercard
Mastercard Program API

The Program API from Mastercard — 1 operation(s) for program.
Documentation GitHub OpenAPI
OpenAPI Specification

swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Program 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: Program
paths:
  /donations/program/{programId}/transactions:
    post:
      tags:
      - Program
      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
components:
  requestBodies:
    ProgramTransactionHistoryRequest:
      description: ProgramTransactionHistoryRequest
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProgramTransactionHistory'
      required: true
  responses:
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-403'
    Created:
      description: The specified resource was created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-201'
    Unauthorized:
      description: Unauthorised
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-401'
    InternalServerError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-500'
    Unsupported:
      description: Unsupported Content Type
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-415'
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-404'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ProgramTransactionHistoryPaged:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProgramTransactionHistoryPaged'
          examples:
            success:
              $ref: '#/components/examples/ProgramTransactionHistoryPagedExample'
  schemas:
    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-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_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
    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.
    PagedResult_RecurringTransaction_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: All Micro OR Monthly transactions will be returned in list
    Error-500:
      type: object
      required:
      - Errors
      properties:
        Errors:
          type: object
          required:
          - Error
          description: Contains all errors caused due to server error
          properties:
            Error:
              type: array
              description: Only returned in the event of an server issue.
              items:
                type: object
                properties:
                  Source:
                    type: string
                    example: DONATE_SERVICE
                    description: The application that generated this error
                  ReasonCode:
                    type: string
                    example: PROGRAM_ID_NOT_FOUND
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: Program id is required as this client is mapped to multiple programs.
                    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:
      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: DONOR_ID_INVALID
                    description: A unique constant identifying the error case encountered during API processing
                  Description:
                    type: string
                    example: Invalid donorId, it must be a valid UUID.
                    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: Provided donorId is not valid, Please check and provide valid Unique Id.
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing.
  parameters:
    ClientId:
      name: x-openapi-clientid
      in: header
      description: ClientId is a unique and a mandatory ID shared while creating a project on Mastercard Developers Portal.
      required: true
      schema:
        type: string
        example: 0a7e433a-63fc-4557-8cf4
    Limit:
      name: limit
      in: query
      description: limit
      required: false
      schema:
        type: integer
        format: int32
        example: 25
    Offset:
      name: offset
      in: query
      description: offset
      required: false
      schema:
        type: integer
        format: int32
        example: 10
    donorId:
      name: donor_id
      in: query
      description: Donor
      required: false
      schema:
        type: integer
        example: 652ce9ff-fa5f-4e9f-8151-c73fa20088f7
    Programid:
      name: ProgramId
      in: header
      description: ProgramId is an required field.
      required: true
      schema:
        type: string
        example: 80380ef2-5037-4e57-86bf-1bdd1efb0ae2
    CorrelationId:
      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.
      required: false
      schema:
        type: string
        example: 03f8c4e8-8bdc-4a30-a2b4-b6f989e96ca3
  examples:
    ProgramTransactionHistoryPagedExample:
      value:
        limit: 2000,
        offset: 0,
        totalTransactions: 602,
        filteredTransactions: 4,
        realTimeTransaction:
          totalTransactions: 137,
          filteredTransactions: 3,
          transactions:
          - charityName: Save the Children,
            primaryAccountNumberSuffix: 1111,
            donationType: ONE-TIME,
            date: 2022-11-07,
            updatedDate: 2022-11-07,
            amount: 10.0,
            currency: EUR,
            paymentNetwork: null,
            clientId: 4dG5GoNZizSe_hDkUULGvYoaK9jmbEZsQbGxg-CA7fca22dc,
            programId: da28a815-fd25-4df4-8b60-1a735d81e473,
            donorId: 10d212f0-198e-466e-8d9b-ac26746f7fb4,
            cardId: d518967d-2b76-4d83-8fad-b9c43cdba076,
            charityId: 9a2e0ca5-e574-440e-af0a-5f58c035d7e8,
            transactionId: OTrPjQjNS3SC0d-BCPeb1Q,
            orderId: 84b57c00-63b8-4392-afc6-a1286f02ccd8,
            transactionStatus: FAILURE
          - charityName: Save the Children,
            primaryAccountNumberSuffix: 0019,
            donationType: ONE-TIME,
            date: 2022-11-07,
            updatedDate: 2022-11-07,
            amount: 40.0,
            currency: EUR,
            paymentNetwork: null,
            clientId: 4dG5GoNZizSe_hDkUULGvYoaK9jmbEZsQbGxg-CA7fca22dc,
            programId: da28a815-fd25-4df4-8b60-1a735d81e473,
            donorId: 10d212f0-198e-466e-8d9b-ac26746f7fb4,
            cardId: 2bd45372-c4cb-4cd2-8d20-9ac0b7f51e2f,
            charityId: 9a2e0ca5-e574-440e-af0a-5f58c035d7e8,
            transactionId: OTtgadqNSrmybjRx6f9GmA,
            orderId: e0002e19-90de-422a-bac2-3001f4bd13ac,
            transactionStatus: SUCCESS
          - charityName: Save the Children,
            primaryAccountNumberSuffix: 0007,
            donationType: ONE-TIME,
            date: 2022-11-07,
            updatedDate: 2022-11-07,
            amount: 100.0,
            currency: EUR,
            paymentNetwork: mastercard,
            clientId: 4dG5GoNZizSe_hDkUULGvYoaK9jmbEZsQbGxg-CA7fca22dc,
            programId: da28a815-fd25-4df4-8b60-1a735d81e473,
            donorId: 10d212f0-198e-466e-8d9b-ac26746f7fb4,
            cardId: 234c51a1-ee50-4f98-ad3c-e304f2d6f846,
            charityId: 9a2e0ca5-e574-440e-af0a-5f58c035d7e8,
            transactionId: OTUpK9mGShS_0BRY8Zv8Rg,
            orderId: 0bf04655-ff03-4d09-82bf-e6b590dbffba,
            transactionStatus: FAILURE
        recurringTransaction:
          totalTransactions: 465,
          filteredTransactions: 1,
          transactions:
          - charityName: Save the Children,
            primaryAccountNumberSuffix: 0007,
            donationType: MICRO,
            date: 2019-08-24,
            updatedDate: 2020-10-01,
            amount: 50.0,
            currency: EUR,
            paymentNetwork: mastercard,
            clientId: 4dG5GoNZizSe_hDkUULGvYoaK9jmbEZsQbGxg-CA7fca22dc,
            programId: da28a815-fd25-4df4-8b60-1a735d81e473,
            donorId: 10d212f0-198e-466e-8d9b-ac26746f7fb4,
            cardId: 234c51a1-ee50-4f98-ad3c-e304f2d6f812,
            charityId: 9a2e0ca5-e574-440e-af0a-5f58c035d7e8,
            transactionId: OTUpK9mGShS_0BRY8Zv8Af,
            orderId: 0bf04655-ff03-4d09-82bf-e6b590dbffer,
            transactionStatus: FAILURE
Mastercard Program API

Documentation

Specifications

Code Examples

Other Resources

OpenAPI Specification
