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