swagger: '2.0' info: title: Mastercard Bill Payment Validator Account Opening Donor 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: Donor paths: /donors/{donor_id}: get: tags: - Donor summary: Get Donor API description: This API will be used for fetching user on platform. Entire response body is encrypted and it should be decrypted to view the actual response. operationId: fetchUserUsingGET parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/Donor' responses: '200': $ref: '#/components/responses/RetrieveUser' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' deprecated: false put: tags: - Donor summary: Update Donor API description: This API will be used for updating user on platform. Entire request body should be encrypted. operationId: updateUserUsingPUT parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/Donor' responses: '200': $ref: '#/components/responses/DonateUser' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '415': $ref: '#/components/responses/Unsupported' '500': $ref: '#/components/responses/InternalServerError' deprecated: false requestBody: $ref: '#/components/requestBodies/UpdateUser' delete: tags: - Donor summary: Delete Donor API description: This API will be used for deleting user on platform operationId: deleteUserUsingDELETE parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/Donor' responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' deprecated: false /donors/{donor_id}/cards: get: tags: - Donor summary: Get All Cards API description: Fetches all the cards for given donor. Entire response body is encrypted and it should be decrypted to view the actual response. operationId: getAllCardsUsingGET parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/Donor' responses: '200': $ref: '#/components/responses/DonateGetAllCards' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' deprecated: false post: tags: - Donor summary: Add Card API description: Donor can add his/her card onto platform by calling this API, so that next time he/she wants to donate, he/she don't have to provide card details.A card will be added once. Second time, the initial card Id will be returned.Entire request body should be encrypted. operationId: addCardUsingPOST parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/Donor' requestBody: $ref: '#/components/requestBodies/AddCard' responses: '200': $ref: '#/components/responses/DonateCard' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error-AddCard' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' deprecated: false /donors/{donor_id}/cards/searches: post: tags: - Donor summary: Search Card API description: Search card by pan or user id passed. Entire request body should be encrypted. operationId: searchCardUsingPOST parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/Donor' requestBody: $ref: '#/components/requestBodies/SearchCard' responses: '200': $ref: '#/components/responses/DonateGetAllCards' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' deprecated: false /donors/{donor_id}/cards/{card_id}: get: tags: - Donor summary: Retrieve Card API description: Retrieves card by card id passed. Entire response body is encrypted and it should be decrypted to view the actual response. operationId: retrieveCardUsingGET parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/Card' - $ref: '#/components/parameters/Donor' responses: '200': $ref: '#/components/responses/DonateCardRetrieve' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' deprecated: false put: tags: - Donor summary: Update Card API description: Donor can update his/her already added card by providing new card informatin along with cardId. Entire request body should be encrypted. operationId: updateCardUsingPUT parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/Card' - $ref: '#/components/parameters/Donor' responses: '200': $ref: '#/components/responses/DonateCardUpdate' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' deprecated: false requestBody: $ref: '#/components/requestBodies/UpdateCard' delete: tags: - Donor summary: Delete Card API description: Donor can delete his/her saved card from Donation platform. operationId: deleteCardUsingDELETE parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/Card' - $ref: '#/components/parameters/Donor' responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' deprecated: false /donors/{donor_id}/setups: get: tags: - Donor 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: - Donor 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 /donors/{donor_id}/setups/{donation_setup_id}: get: tags: - Donor summary: Get Recurring Donation description: Retrieve donation setup details by setupid operationId: retriveDonationSetupByIdUsingGET parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/DonationSetup' - $ref: '#/components/parameters/Donor' responses: '200': $ref: '#/components/responses/RetrieveDonateSetUpDetails' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' deprecated: false put: tags: - Donor summary: Update Recurring Donation description: Update Monthly, Micro or Round-up donation for a registered user. Encrypting request body is not required. operationId: updateDonationSetupUsingPUT parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/DonationSetup' - $ref: '#/components/parameters/Donor' requestBody: $ref: '#/components/requestBodies/DonateSetupUpdate' responses: '200': $ref: '#/components/responses/DonateSetup' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' deprecated: false delete: tags: - Donor summary: Delete Recurring Donation description: Delete Monthly, Micro or Round-up donation for a registered user operationId: deleteDonationSetupUsingDELETE parameters: - $ref: '#/components/parameters/ClientId' - $ref: '#/components/parameters/CorrelationId' - $ref: '#/components/parameters/ProgramId' - $ref: '#/components/parameters/DonationSetup' - $ref: '#/components/parameters/Donor' responses: '204': $ref: '#/components/responses/NoContent' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' deprecated: false /donors/{donor_id}/transactions: post: tags: - Donor 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 components: schemas: DonorEmail: type: object properties: type: type: string example: home minLength: 3 maxLength: 20 description: Type value: type: string example: John.Doe@mail.com minLength: 5 maxLength: 30 description: Email Id title: DonorEmail 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 () 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. DonateCardUpdate: type: object properties: cardId: type: string example: ebee3d81-18d4-409a-8330-73db083f2cfc minLength: 36 maxLength: 36 description: Card Id (UUID) primaryAccountNumberSuffix: type: string example: '3538' minLength: 4 maxLength: 4 description: PAN Suffix title: DonateCardUpdateResponse 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' UpdateUser: type: object required: - acceptedConsents - emails - locale - name - username properties: acceptedConsents: $ref: '#/components/schemas/AcceptedConsent' addresses: type: array description: Address items: $ref: '#/components/schemas/DonateUserAddress' emails: type: array description: Emails items: $ref: '#/components/schemas/ConsumerEmail' locale: type: string example: en-us minLength: 5 maxLength: 5 description: Locale name: $ref: '#/components/schemas/UserName' password: type: string example: WzzX3GjXAmjYCLdz minLength: 8 maxLength: 30 description: Password personalInformation: $ref: '#/components/schemas/PersonalInformation' phoneNumbers: type: array description: Phone numbers items: $ref: '#/components/schemas/DonorPhoneNumber' timezone: type: string description: Timezone example: UTC-06:00 minLength: 8 maxLength: 30 title: type: string example: Mr minLength: 2 maxLength: 30 description: Title username: type: string example: test1203@yopmail.com minLength: 2 maxLength: 30 description: UserName title: UpdateUserRequest 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 AuthPayerResponse: type: object properties: authentication: $ref: '#/components/schemas/Authentication' cardExpiry: type: object properties: month: type: string example: 10 minLength: 2 maxLength: 2 description: Month year: type: string example: 2025 minLength: 4 maxLength: 4 description: Year title: Card Expiry Details PersonalInformation: title: PersonalInformation type: object properties: identifications: type: array description: identifications items: $ref: '#/components/schemas/Identification' DonateUserAddress: required: - type - country - streetAddress type: object properties: country: type: string example: USA minLength: 3 maxLength: 3 description: Country formatted: type: string minLength: 3 maxLength: 150 example: 7832 West Elm Street Huntington Station, NY 11746 description: Address locality: type: string minLength: 3 maxLength: 30 example: Rly Station description: Locality postalCode: type: string example: 11746 minLength: 5 maxLength: 5 description: Postal Code region: type: string example: Huntington minLength: 3 maxLength: 20 description: Region streetAddress: type: string example: 7832 West Elm Street minLength: 3 maxLength: 30 description: Street Address type: type: string example: work minLength: 3 maxLength: 20 description: Type title: DonateUserAddress Error-AddCard: 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 error condition. items: type: object properties: Source: type: string example: DONATE_SERVICE description: The application that generated this error ReasonCode: type: string example: PAN_ALREADY_EXISTS_FOR_USER description: A unique constant identifying the error case encountered during API processing Description: type: string example: The provided card already exists for this user. 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: array items: type: string example: 'CardId: 327ebf98-f3cc-4733-a041-c60e7d743b04' 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� DonorPhoneNumber: type: object properties: type: type: string example: home minLength: 3 maxLength: 20 description: Type value: type: string example: '+16367222222' minLength: 11 maxLength: 20 description: Phone number with country code. title: DonorPhoneNumber UserName: type: object required: - firstName - lastName properties: firstName: type: string example: John minLength: 3 maxLength: 30 description: First Name lastName: type: string example: Doe minLength: 3 maxLength: 30 description: Last Name honorificPrefix: type: string example: Mr minLength: 2 maxLength: 30 description: Honorific Prefix honorificSuffix: type: string example: Jr. minLength: 2 maxLength: 30 description: Honorific Suffix title: UserName 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. AddCard: type: object required: - cardholderName - expiryInfo - primaryAccountNumber - primaryAccountNumberSource properties: billingAddress: $ref: '#/components/schemas/CardBillingAddress' cardAlias: type: string example: CardA minLength: 3 maxLength: 20 description: Card Alias cardholderName: type: string example: John Doe minLength: 3 maxLength: 20 description: Card holder name expiryInfo: $ref: '#/components/schemas/cardExpiry' primaryAccountNumber: type: string example: '5450985888403538' minLength: 16 maxLength: 16 description: PAN number primaryAccountNumberSource: type: string example: CARD_ON_FILE minLength: 3 maxLength: 20 description: PAN Source title: AddCard AcceptedConsent: type: object required: - marketingEmailSubscribed - privacyNoticeVersion - tncVersion properties: marketingEmailSubscribed: type: string example: Y minLength: 1 maxLength: 1 description: Marketing Email Subscribed privacyNoticeVersion: type: string example: PN.2-#-xr.en-us.99.01 minLength: 21 maxLength: 21 description: Privacy Notice Version tncVersion: type: string example: TC.##r#12.EN-Us.99.99 minLength: 21 maxLength: 21 description: Tnc Version title: AcceptedConsent DonateSetupUpdate: type: object required: - amount properties: amount: type: string example: '5' minLength: 1 maxLength: 20 description: Fixed amount incase of Monthly and Per Real-Transaction incase of Micro maxCap: type: string example: '50' minLength: 1 maxLength: 20 description: Max limit is applicable only for Micro Donations authPayerResponse: $ref: '#/components/schemas/AuthPayerResponse' title: DonateSetupUpdateRequest 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. 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 DonateUser: type: object properties: donorId: type: string minLength: 36 maxLength: 36 example: 652ce9ff-fa5f-4e9f-8151-c73fa20088f7 format: uuid description: Valid UUID. userName: type: string example: John.Doe@mail.com minLength: 5 maxLength: 30 description: User Name title: DonateUserResponse ConsumerName: type: object properties: lastName: type: string example: Doe minLength: 3 maxLength: 30 description: Family Name firstName: type: string example: John minLength: 3 maxLength: 30 description: Given Name honorificPrefix: type: string example: Mr minLength: 2 maxLength: 20 description: Honorific Prefix honorificSuffix: type: string example: Jr. minLength: 2 maxLength: 20 description: Honorific Suffix title: ConsumerName DonateSetup: type: object properties: donationSetupId: type: string example: 4a520af0-8e47-44cd-8925-9f3ecd09baff format: uuid minLength: 36 maxLength: 36 description: Donation SetupId donorId: type: string minLength: 36 maxLength: 36 example: 652ce9ff-fa5f-4e9f-8151-c73fa20088f7 format: uuid description: Valid UUID. setupStatus: type: string example: ACTIVE minLength: 5 maxLength: 20 description: Can be ACTIVE / DELETED / INACTIVE transactionId: type: string example: 3311e859-3ee4-4155-a640-8cae447c27ca minLength: 36 maxLength: 36 description: Generated upon successful donation setup. transactionMessage: type: string example: Transaction APPROVED. minLength: 3 maxLength: 30 description: Message for donation setup transaction. transactionStatus: type: string example: SUCCESS minLength: 3 maxLength: 30 description: Status of transaction. title: DonateSetupResponse ConsumerEmail: type: object required: - type properties: type: type: string example: home description: The type must be "home" for at least one email address. minLength: 4 maxLength: 20 value: type: string example: John.Doe@mail.com description: Email Id minLength: 10 maxLength: 30 title: ConsumerEmail 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. CardBillingAddress: type: object properties: city: type: string example: Brooklyn minLength: 3 maxLength: 20 description: Billing Address city countryCode: type: string example: USA minLength: 3 maxLength: 3 description: Billing Address country code line1: type: string example: 83 Mayfair Street minLength: 3 maxLength: 20 description: Billing Address line1 line2: type: string example: Main Road minLength: 3 maxLength: 20 description: Billing Address line2 line3: type: string example: Snake Hill Ave minLength: 3 maxLength: 20 description: Billing Address line3 postalCode: type: string example: 11235 minLength: 5 maxLength: 20 description: Billing Address postal code state: type: string example: NY minLength: 2 maxLength: 20 description: Billing Address state title: CardBillingAddress UpdateCard: type: object required: - cardholderName - expiryInfo - primaryAccountNumberSource - primaryAccountNumber properties: billingAddress: $ref: '#/components/schemas/CardBillingAddress' cardAlias: type: string example: CardB minLength: 3 maxLength: 20 description: Card Alias cardholderName: type: string example: John Doe minLength: 3 maxLength: 20 description: Card Holder Name CardExpiry: $ref: '#/components/schemas/cardExpiry' primaryAccountNumberSource: type: string example: CARD_ON_FILE description: PAN minLength: 3 maxLength: 20 primaryAccountNumber: type: string example: '5450985888403538' minLength: 16 maxLength: 16 description: PAN number title: UpdateCardRequest 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. SearchCard: required: - primaryAccountNumber type: object properties: primaryAccountNumber: type: string description: PAN minLength: 16 maxLength: 16 example: '5450985888403538' title: SearchCardRequest DonateGetAllCards: type: object properties: items: type: array description: Items items: $ref: '#/components/schemas/DonateCardRetrieve' title: DonateGetAllCardsResponse 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 Identification: type: object properties: country: type: string example: MX minLength: 2 maxLength: 3 description: Country type: type: string example: GovtId minLength: 3 maxLength: 20 description: Type value: type: string example: '16367222222' minLength: 11 maxLength: 20 description: Value title: Identification 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 DonateCard: type: object properties: cardId: type: string example: ebee3d81-18d4-409a-8330-73db083f2cfc minLength: 36 maxLength: 36 description: Card id (UUID) primaryAccountNumberSuffix: type: string example: '3538' minLength: 4 maxLength: 4 description: PAN Suffix title: DonateCardResponse 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. 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 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 RetrieveUser: type: object properties: acceptedConsents: $ref: '#/components/schemas/AcceptedConsent' addresses: type: array description: Address items: $ref: '#/components/schemas/DonateUserAddress' emails: type: array description: Emails items: $ref: '#/components/schemas/DonorEmail' locale: type: string description: Locale example: en-us minLength: 5 maxLength: 5 name: $ref: '#/components/schemas/ConsumerName' personalInformation: $ref: '#/components/schemas/PersonalInformation' phoneNumbers: type: array description: Phone Numbers items: $ref: '#/components/schemas/DonorPhoneNumber' timezone: type: string description: Timezone example: UTC-06:00 minLength: 8 maxLength: 20 title: type: string description: Title example: Mr minLength: 2 maxLength: 20 userName: type: string description: User Name example: John.Doe@mail.com minLength: 3 maxLength: 30 userType: type: string description: User Type example: API minLength: 6 maxLength: 20 title: RetrieveUserResponse DonationHistoryPaged: type: object properties: realTimeTransaction: $ref: '#/components/schemas/PagedResult_RealTimeTransaction_DonationHistoryResponse_' recurringTransaction: $ref: '#/components/schemas/PagedResult_RecurringTransaction_DonationHistoryResponse_' title: DonationHistoryPagedResponse DonateCardRetrieve: type: object properties: billingAddress: $ref: '#/components/schemas/CardBillingAddress' cardAlias: type: string example: CardA minLength: 3 maxLength: 30 description: The card alias cardId: type: string example: ebee3d81-18d4-409a-8330-73db083f2cfc minLength: 36 maxLength: 36 description: Card Id (UUID) cardholderName: type: string example: John Doe minLength: 3 maxLength: 30 description: Cardholder Name cardExpiry: $ref: '#/components/schemas/cardExpiry' paymentNetworkName: type: string example: Mastercard minLength: 3 maxLength: 20 description: Payment Network Name primaryAccountNumber: type: string example: '5450985888403538' minLength: 16 maxLength: 16 description: PAN primaryAccountNumberSource: type: string example: CARD_ON_FILE minLength: 3 maxLength: 20 description: PAN Source primaryAccountNumberSuffix: type: string example: '3538' minLength: 4 maxLength: 4 description: PAN Suffix status: type: string example: ACTIVE minLength: 5 maxLength: 20 description: Status title: DonateCardRetrieveResponse 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. responses: DonateSetups: description: Success content: application/json: schema: $ref: '#/components/schemas/DonateSetups' examples: SUCCESS: $ref: '#/components/examples/monthlySetupSuccess' FAILURE: $ref: '#/components/examples/monthlySetupFail' Created: description: The specified resource was created content: application/json: schema: $ref: '#/components/schemas/Error-201' Unsupported: description: Unsupported Content Type content: application/json: schema: $ref: '#/components/schemas/Error-415' DonateCard: description: Success content: application/json: schema: $ref: '#/components/schemas/DonateCard' NoContent: description: The Setup is successfully deleted. DonateSetup: description: Success content: application/json: schema: $ref: '#/components/schemas/DonateSetup' PagedResultRetrieveDonateSetUpDetails: description: Success content: application/json: schema: $ref: '#/components/schemas/PagedResultRetrieveDonateSetUpDetails' Unauthorized: description: Unauthorised content: application/json: schema: $ref: '#/components/schemas/Error-401' DonationHistoryPaged: description: Success content: application/json: schema: $ref: '#/components/schemas/DonationHistoryPaged' examples: success: $ref: '#/components/examples/DonationHistoryPagedExample' RetrieveUser: description: Success content: application/json: schema: $ref: '#/components/schemas/RetrieveUser' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error-403' DonateCardRetrieve: description: Success content: application/json: schema: $ref: '#/components/schemas/DonateCardRetrieve' InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error-500' RetrieveDonateSetUpDetails: description: Success content: application/json: schema: $ref: '#/components/schemas/RetrieveDonateSetUpDetails' DonateGetAllCards: description: Success content: application/json: schema: $ref: '#/components/schemas/DonateGetAllCards' DonateUser: description: Success content: application/json: schema: $ref: '#/components/schemas/DonateUser' NotFound: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/Error-404' DonateCardUpdate: description: Success content: application/json: schema: $ref: '#/components/schemas/DonateCardUpdate' BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' parameters: Limit: name: limit in: query description: limit required: false schema: type: integer format: int32 example: 25 Card: name: card_id in: path description: card_id required: true schema: type: string example: ebee3d81-18d4-409a-8330-73db083f2cfc 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 DonationSetup: name: donation_setup_id in: path description: donation_setup_id required: true schema: type: string example: 4a520af0-8e47-44cd-8925-9f3ecd09baff 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 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 requestBodies: AddCard: description: addCardRequest content: application/json: schema: $ref: '#/components/schemas/AddCard' required: false UpdateCard: description: updateCardRequest content: application/json: schema: $ref: '#/components/schemas/UpdateCard' required: false SearchCard: description: searchCardRequest content: application/json: schema: $ref: '#/components/schemas/SearchCard' required: false DonationHistory: description: donationHistoryRequest content: application/json: schema: $ref: '#/components/schemas/DonationHistory' required: true DonationSetup: description: donationSetupRequest content: application/json: schema: $ref: '#/components/schemas/DonationSetup' required: true UpdateUser: description: updateUserRequest content: application/json: schema: $ref: '#/components/schemas/UpdateUser' required: false DonateSetupUpdate: description: donateSetupUpdateRequest content: application/json: schema: $ref: '#/components/schemas/DonateSetupUpdate' required: false examples: 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. 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 DonationHistoryPagedExample: value: realTimeTransaction: limit: 10 offset: 0 totalItems: 2 items: - charityName: Stripe Charity primaryAccountNumberSuffix: 1118 donationType: ONE-TIME date: '2023-07-03T00:00:00.000Z' updatedDate: '2023-07-03T00:00:00.000Z' amount: 10 currency: USD paymentNetwork: mastercard dedication: null clientId: C7i6WOvQp2obVbB_EtX8XCsQ5YwQ_FN2yIz7Mf9m31e6102d programId: aa0f99f5-75d2-46ed-81b8-7ac80ccd0f6c donorId: bdacdcfc-7d74-406c-9be3-a9f46dcfa27f cardId: 88b34e2d-4c80-4469-8049-f713c39530f1 charityId: 4b6047c8-b71a-f8e1-4a1f-7b00e09d19ab transactionId: OTsb7v4QRGqR1Ci9xIcPEA orderId: b53bc97b-25b2-4116-927b-ba1f5fa3d809 transactionStatus: FAILURE - charityName: Save the Children primaryAccountNumberSuffix: 1118 donationType: ONE-TIME date: '2023-04-20T00:00:00.000Z' updatedDate: '2023-04-20T00:00:00.000Z' amount: 8 currency: USD paymentNetwork: mastercard dedication: null clientId: C7i6WOvQp2obVbB_EtX8XCsQ5YwQ_FN2yIz7Mf9m31e6102d programId: aa0f99f5-75d2-46ed-81b8-7ac80ccd0f6c donorId: bdacdcfc-7d74-406c-9be3-a9f46dcfa27f cardId: 88b34e2d-4c80-4469-8049-f713c39530f1 charityId: 9a2e0ca5-e574-440e-af0a-5f58c035d7e8 transactionId: OTaIpn_bRsmOOYC-4IML8g orderId: 89119e66-14d6-4a94-b2e2-f01a7932d9a3 transactionStatus: SUCCESS recurringTransaction: limit: 10 offset: 0 totalItems: 3 items: - charityName: Save the Children primaryAccountNumberSuffix: 1118 donationType: MICRO date: '2023-04-20T00:00:00.000Z' updatedDate: '2023-04-20T00:00:00.000Z' amount: 8 currency: USD paymentNetwork: mastercard dedication: null clientId: C7i6WOvQp2obVbB_EtX8XCsQ5YwQ_FN2yIz7Mf9m31e6102d programId: aa0f99f5-75d2-46ed-81b8-7ac80ccd0f6c donorId: bdacdcfc-7d74-406c-9be3-a9f46dcfa27f cardId: 88b34e2d-4c80-4469-8049-f713c39530f1 charityId: 9a2e0ca5-e574-440e-af0a-5f58c035d7e8 transactionId: MIaIpn_bRsmOOYC-4IML8g orderId: 89119e66-14d6-4a94-b2e2-f01a7932d9a3 transactionStatus: SUCCESS - charityName: AST-CLIENT-1-PROGRAM-1-CHARITY-1 primaryAccountNumberSuffix: 1118 donationType: MICRO date: '2023-04-20T00:00:00.000Z' updatedDate: '2023-04-20T00:00:00.000Z' amount: 8 currency: USD paymentNetwork: mastercard dedication: null clientId: C7i6WOvQp2obVbB_EtX8XCsQ5YwQ_FN2yIz7Mf9m31e6102d programId: aa0f99f5-75d2-46ed-81b8-7ac80ccd0f6c donorId: bdacdcfc-7d74-406c-9be3-a9f46dcfa27f cardId: 88b34e2d-4c80-4469-8049-f713c39530f1 charityId: 496e1703-7e2c-4135-8b99-6cba97cd2f9b transactionId: MI5pPstFTpGFZdoR2Ho3yA orderId: 188817d9-5d4a-430c-86a4-d38fac672d46 transactionStatus: FAILURE - charityName: AST-CLIENT-1-PROGRAM-1-CHARITY-1 primaryAccountNumberSuffix: 1118 donationType: MICRO date: '2023-04-20T00:00:00.000Z' updatedDate: '2023-04-20T00:00:00.000Z' amount: 5 currency: USD paymentNetwork: mastercard dedication: null clientId: C7i6WOvQp2obVbB_EtX8XCsQ5YwQ_FN2yIz7Mf9m31e6102d programId: aa0f99f5-75d2-46ed-81b8-7ac80ccd0f6c donorId: bdacdcfc-7d74-406c-9be3-a9f46dcfa27f cardId: 88b34e2d-4c80-4469-8049-f713c39530f1 charityId: 496e1703-7e2c-4135-8b99-6cba97cd2f9b transactionId: MIbLg8G5SEOGF6SB_f86aA orderId: 51d96a3b-5493-48a6-b22e-42ab0b0e8ca0 transactionStatus: FAILURE reasonCode: INCORRECT_NUMBER reasonMessage: The card number is incorrect. Please check the cards number and try again use a different card.