Mastercard
Mastercard Setup Donation API

The Setup Donation API from Mastercard — 1 operation(s) for setup donation.
Documentation GitHub OpenAPI
OpenAPI Specification

swagger: '2.0'
info:
  title: Mastercard Bill Payment Validator Account Opening Setup  Donation 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: Setup  Donation
paths:
  /donors/{donor_id}/setups:
    get:
      tags:
      - Setup  Donation
      summary: Get All Recurring Donation
      description: Fetches the setup Ids pertaining to a donor
      operationId: getAllDonationSetupUsingGET
      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'
      responses:
        '200':
          $ref: '#/components/responses/PagedResultRetrieveDonateSetUpDetails'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: false
    post:
      tags:
      - Setup  Donation
      summary: Setup Donation
      description: Setup Monthly, Micro or Round-Up donation for a registered user. Encrypting request body is not required.
      operationId: setupDonationUsingPOST
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/CorrelationId'
      - $ref: '#/components/parameters/ProgramId'
      - $ref: '#/components/parameters/Donor'
      requestBody:
        $ref: '#/components/requestBodies/DonationSetup'
      responses:
        '200':
          $ref: '#/components/responses/DonateSetups'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      deprecated: false
components:
  requestBodies:
    DonationSetup:
      description: donationSetupRequest
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DonationSetup'
      required: true
  responses:
    DonateSetups:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DonateSetups'
          examples:
            SUCCESS:
              $ref: '#/components/examples/monthlySetupSuccess'
            FAILURE:
              $ref: '#/components/examples/monthlySetupFail'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error-403'
    PagedResultRetrieveDonateSetUpDetails:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PagedResultRetrieveDonateSetUpDetails'
    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'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    RetrieveDonateSetUpDetails:
      type: object
      properties:
        amount:
          type: string
          example: '11'
          minLength: 1
          maxLength: 10
          description: Fixed amount incase of Monthly and Per Real-Transaction incase of Micro
        cardId:
          type: string
          minLength: 36
          maxLength: 36
          description: Card Id
          example: ebee3d81-18d4-409a-8330-73db083f2cfc
        charityId:
          type: string
          minLength: 36
          maxLength: 36
          example: ae3c5f35-084a-4df9-a2af-7e0efd512fc0
          format: uuid
          description: Charity Id
        donationSetupId:
          type: string
          minLength: 36
          maxLength: 36
          example: 4a520af0-8e47-44cd-8925-9f3ecd09baff
          format: uuid
          description: Donation SetupId
        donationType:
          type: string
          example: Micro
          minLength: 3
          maxLength: 20
          description: Can be either Micro or Monthly
        donorId:
          type: string
          minLength: 36
          maxLength: 36
          example: 652ce9ff-fa5f-4e9f-8151-c73fa20088f7
          format: uuid
          description: Valid UUID.
        maxCap:
          type: string
          example: '50'
          minLength: 1
          maxLength: 10
          description: Max limit is applicable only for Micro Donations
        setupStatus:
          type: string
          example: ACTIVE
          minLength: 3
          maxLength: 20
          description: Can be ACTIVE / DELETED / INACTIVE
      title: RetrieveDonateSetUpDetailsResponse
    3ds2:
      type: object
      required:
      - transactionStatus
      properties:
        transactionStatus:
          type: string
          example: Y
          minLength: 1
          maxLength: 1
          description: Status of Transaction (recommended - Y)
        protocolVersion:
          type: string
          example: 2.2.2
          minLength: 5
          maxLength: 20
          description: Protocol Version
      description: Required If authPayerResponse object is passed, only for MPGS.
    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.
    Authentication:
      type: object
      properties:
        3ds:
          $ref: '#/components/schemas/3ds'
        3ds2:
          $ref: '#/components/schemas/3ds2'
    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.
    DonateSetups:
      type: object
      properties:
        donationSetupId:
          type: string
          format: uuid
          minLength: 36
          maxLength: 36
          description: Donation SetupId
        donorId:
          type: string
          minLength: 36
          maxLength: 36
          format: uuid
          description: Valid UUID.
        setupStatus:
          type: string
          minLength: 5
          maxLength: 20
          description: Can be ACTIVE / DELETED / INACTIVE
        transactionId:
          type: string
          minLength: 36
          maxLength: 36
          description: Generated upon successful donation setup.
        transactionMessage:
          type: string
          minLength: 3
          maxLength: 30
          description: Message for donation setup transaction.
        transactionStatus:
          type: string
          minLength: 3
          maxLength: 30
          description: Status of transaction.
      title: DonateSetup-Response
    AuthPayerResponse:
      type: object
      properties:
        authentication:
          $ref: '#/components/schemas/Authentication'
    3ds:
      type: object
      required:
      - authenticationToken
      - transactionId
      - version
      properties:
        acsEci:
          type: string
          example: 2
          minLength: 1
          maxLength: 2
          description: ascEci
        authenticationToken:
          type: string
          example: kHyn+7YFi1EUAREAAAAvNUe6Hv8=
          minLength: 28
          maxLength: 32
          description: Authentication Token
        transactionId:
          type: string
          example: 9f343e5d-fc28-4818-88d4-17a35fb7dea9
          minLength: 36
          maxLength: 36
          description: transaction ID (UUID)
        version:
          type: string
          example: 1.0.2
          minLength: 5
          maxLength: 20
          description: version
      description: Required If authPayerResponse object is passed.
    DonationSetup:
      type: object
      required:
      - amount
      - charityId
      - cardId
      - donationType
      properties:
        amount:
          type: string
          example: '11'
          minLength: 1
          maxLength: 20
          description: Fixed amount incase of Monthly and Per Real-Transaction incase of Micro
        cardId:
          type: string
          minLength: 36
          maxLength: 36
          example: ebee3d81-18d4-409a-8330-73db083f2cfc
          description: Card Id (UUID)
        charityId:
          type: string
          minLength: 36
          maxLength: 36
          example: ae3c5f35-084a-4df9-a2af-7e0efd512fc0
          description: Charity Id (UUID)
        donationType:
          type: string
          example: Monthly
          minLength: 5
          maxLength: 20
          description: Can be either Micro or Monthly
        maxCap:
          type: string
          example: '100'
          minLength: 1
          maxLength: 20
          description: Max Cap
        authPayerResponse:
          $ref: '#/components/schemas/AuthPayerResponse'
        source:
          type: string
          example: SOURCE
          minLength: 3
          maxLength: 20
          description: Source
      title: DonationSetupRequest
    PagedResultRetrieveDonateSetUpDetails:
      type: object
      properties:
        items:
          type: array
          description: Items
          items:
            $ref: '#/components/schemas/RetrieveDonateSetUpDetails'
        limit:
          type: integer
          example: 25
          format: int32
          minLength: 1
          maxLength: 10
          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�RetrieveDonateSetUpDetailsResponse�
    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.
  examples:
    monthlySetupSuccess:
      summary: Monthly payment success
      value:
        donorId: b25cfe74-1948-4697-8fcb-4b5acfb1e712
        setupStatus: ACTIVE
        transactionId: MF2vzvA1Syu1B2usotxWSg
        transactionStatus: SUCCESS
        transactionMessage: Transaction APPROVED
        donationSetupId: 21434906-596e-4216-b843-e0315eab8923
    monthlySetupFail:
      summary: Monthly payment failure
      value:
        donorId: b25cfe74-1948-4697-8fcb-4b5acfb1e712
        setupStatus: INACTIVE
        transactionId: MF2vzvA1Syu1B2usotxWSg
        transactionStatus: FAILURE
        transactionMessage: Transaction declined
        donationSetupId: 21434906-596e-4216-b843-e0315eab8923
        reasonCode: STOLEN_CARD
        reasonMessage: Your card was declined. Please try again using a different card or contact your card issuer for more information.
  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
    ProgramId:
      name: ProgramId
      in: header
      description: ProgramId is an optional field, but if a client has more than one program associated to it, then this field becomes mandatory.
      required: false
      schema:
        type: string
        example: 80380ef2-5037-4e57-86bf-1bdd1efb0ae2
    Offset:
      name: offset
      in: query
      description: offset
      required: false
      schema:
        type: integer
        format: int32
        example: 10
    Donor:
      name: donor_id
      in: path
      description: donor_id
      required: true
      schema:
        type: string
        example: 652ce9ff-fa5f-4e9f-8151-c73fa20088f7
    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
Mastercard Setup Donation API

Documentation

Specifications

Code Examples

Other Resources

OpenAPI Specification
