swagger: '2.0' info: title: Mastercard Bill Payment Validator Account Opening References 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: References paths: /alerts/merchants/{member_id}/acquirer-reference-ids: post: tags: - References summary: Mastercard Create Acquirer Reference Id Config. description: Create an acquirer reference id configuration. operationId: createAlertsAcquirerReferenceIdConfig parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MemberIdParam' requestBody: $ref: '#/components/requestBodies/AlertsAcquirerReferenceIdConfigRequestBody' responses: '200': $ref: '#/components/responses/AlertsMerchantIdentifierSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/PermissionDenied' '403': $ref: '#/components/responses/ForbiddenOperation' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK put: tags: - References summary: Mastercard Update Acquirer Reference Id Config. description: Update an acquirer reference id configuration. operationId: updateAlertsAcquirerReferenceIdConfig parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MemberIdParam' - $ref: '#/components/parameters/MerchantIdentifierConfigIdParam' requestBody: $ref: '#/components/requestBodies/AlertsAcquirerReferenceIdConfigUpdateRequestBody' responses: '200': $ref: '#/components/responses/AlertsMerchantIdentifierSuccess' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/PermissionDenied' '403': $ref: '#/components/responses/ForbiddenOperation' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationFailed' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK get: tags: - References summary: Mastercard Get Acquirer Reference Id Configs. description: Get the acquirer reference id configs filtered by acquirer reference id and card scheme. operationId: getAlertsAcquirerReferenceIdConfigs parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MemberIdParam' - $ref: '#/components/parameters/AcquirerReferenceIdParam' - $ref: '#/components/parameters/CardSchemeParam' - $ref: '#/components/parameters/OffsetParam' - $ref: '#/components/parameters/PageNumberParam' responses: '200': $ref: '#/components/responses/AlertsPageableAcquirerReferenceIdConfigs' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/PermissionDenied' '403': $ref: '#/components/responses/ForbiddenOperation' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK delete: tags: - References summary: Mastercard Delete Acquirer Reference Id Config. description: Delete an acquirer reference id configuration. operationId: deleteAlertsAcquirerReferenceIdConfig parameters: - $ref: '#/components/parameters/UserIdParam' - $ref: '#/components/parameters/SubmitterFirstNameParam' - $ref: '#/components/parameters/SubmitterLastNameParam' - $ref: '#/components/parameters/MemberIdParam' - $ref: '#/components/parameters/MerchantIdentifierConfigIdParam' responses: '200': $ref: '#/components/responses/SuccessWithoutBody' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/PermissionDenied' '403': $ref: '#/components/responses/ForbiddenOperation' '404': $ref: '#/components/responses/NotFound' default: $ref: '#/components/responses/Default' x-microcks-operation: delay: 0 dispatcher: FALLBACK components: requestBodies: AlertsAcquirerReferenceIdConfigUpdateRequestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AlertsAcquirerReferenceIdConfigUpdate' examples: AlertsAcquirerReferenceIdConfigUpdate: $ref: '#/components/examples/AlertsAcquirerReferenceIdConfigUpdate' AlertsAcquirerReferenceIdConfigRequestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AlertsAcquirerReferenceIdConfig' examples: AlertsAcquirerReferenceIdConfig: $ref: '#/components/examples/AlertsAcquirerReferenceIdConfig' examples: ForbiddenOperation: summary: Member does not have permission to add/update/delete a resource description: If the merchant tries operate on a resource that is not related to them or if they are not allowed perform a specific operation on their resource, then ForbiddenOperation error response is returned to the caller with HTTP Status code 403. value: Errors: Error: - Source: service ReasonCode: operation.not.allowed Description: Member is not allowed to perform a specific operation on a particular resource Recoverable: false Details: '' AlertsAcquirerReferenceIdConfig: summary: Alerts Acquirer Reference Id Configuration value: cardScheme: MASTERCARD acquirerReferenceId: '123456' binOnlyMatch: true AlertsMerchantIdentifierConfigIdOnly: summary: Alerts Merchant Identifier Configuration ID value: merchantIdentifierConfigId: 88ca4b15-72a6-41dd-8127-573d4b07875c AlertsEntityNotFound: summary: Entity Not Found Error Response For Alerts description: If a requested entity(e.g. Sub-Merchant or Card Acceptor ID or Card Acceptor Name) doesn't exist in the system, then EntityNotFound error response is returned to the caller with HTTP Status code 404. value: Errors: Error: - Source: service ReasonCode: 'invalid data: subMerchantId' Description: Sub-Merchant 99ca4b15-72a6-41dd-8127-573d4b07669c not found Recoverable: false Details: '' MissingRequiredHeader: summary: Missing Required Header Error Response description: If a required request header is missing or null, then MissingRequiredHeader error response is returned to the caller with HTTP Status code 400. value: Errors: Error: - Source: service ReasonCode: missing required header Description: Submitter-First-Name Recoverable: false Details: '' ResourceNotFound: summary: Resource Not Found Error Response description: If request URI doesn't match with any available endpoints, then ResourceNotFound error response is returned the caller with HTTP Status code 404. value: Errors: Error: - Source: service ReasonCode: resource.not.found Description: Not Found Recoverable: false Details: /merchant-self-services/sub-merchantTs/ ServerError: summary: Server Error Response description: If an unexpected internal server error occurs, then ServerError response is returned to the caller with HTTP Status code 500. value: Errors: Error: - Source: service ReasonCode: server.error Description: Internal Server Error Recoverable: false Details: '' AlertsAcquirerReferenceIdConfigUpdate: summary: Alerts Acquirer Reference Id Configuration for Update value: binOnlyMatch: true FormatInvalid: summary: Format Invalid Error Response For Consumer Clarity description: If a field is not correctly formatted (e.g. a String value is sent in an Integer type field), then FormatInvalid response is returned to the caller with HTTP Status code 400. value: Errors: Error: - Source: service ReasonCode: format.invalid Description: orderHistoryMonths Recoverable: false Details: '' AlertsFormatInvalid: summary: Format Invalid Error Response For Alerts description: If a field is not correctly formatted (e.g. a String value is sent in an Integer type field), then FormatInvalid response is returned to the caller with HTTP Status code 400. value: Errors: Error: - Source: service ReasonCode: 'invalid data: merchantCategoryCode' Description: must match \"^[0-9]*$\" Recoverable: false Details: '' EntityNotFound: summary: Entity Not Found Error Response For Consumer Clarity description: If a requested entity(e.g. Merchant or Logo) doesn't exist in the system, then EntityNotFound error response is returned to the caller with HTTP Status code 404. value: Errors: Error: - Source: service ReasonCode: 'invalid data: GUID' Description: Merchant 1E37M8VSX1D28QYX not found Recoverable: false Details: '' PermissionDenied: summary: Permission Denied Error Response description: If the client id in the request doesn't correspond to any member in the system, then PermissionDenied error response is returned to the caller with HTTP Status code 401. value: Errors: Error: - Source: service ReasonCode: permission.denied Description: Member does not have permission to perform any operation Recoverable: false Details: '' InvalidParameterSet: summary: Invalid Parameter Set Error Response description: If request body is malformed or missing, then InvalidParameterSet error response is returned to the caller with HTTP Status code 400. value: Errors: Error: - Source: service ReasonCode: invalid.parameter.set Description: request body is malformed Recoverable: false Details: '' InvalidData: summary: Invalid Data Error Response For Consumer Clarity description: If a field or set of fields fails a validation (eg. NotNull, Length, Pattern etc.), then InvalidData response will be returned to the caller for each invalid field with HTTP Status code 400. value: Errors: Error: - Source: service ReasonCode: 'invalid data: merchantType' Description: must not be blank Recoverable: false Details: '' ValidationFailed: summary: Validation of the request failed description: If the fields in the request did not pass the validation, a ValidationFailed error response is returned to the caller with HTTP Status code 422. value: Errors: Error: - Source: service ReasonCode: validation.failed Description: Validation of the request fields failed Recoverable: false Details: '' AlertsInvalidData: summary: Invalid Data Field Error Response For Alerts description: If a field or set of fields fails a validation (eg. NotNull, Length, Pattern etc.), then InvalidData response will be returned to the caller for each invalid field with HTTP Status code 400. value: Errors: Error: - Source: service ReasonCode: 'invalid data: name' Description: size must be between 3 and 200 Recoverable: false Details: '' responses: Default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ServerError: $ref: '#/components/examples/ServerError' ValidationFailed: description: Validation Failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ValidationFailed: $ref: '#/components/examples/ValidationFailed' ForbiddenOperation: description: Forbidden Operation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ForbiddenOperation: $ref: '#/components/examples/ForbiddenOperation' NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: ResourceNotFound: $ref: '#/components/examples/ResourceNotFound' EntityNotFound: $ref: '#/components/examples/EntityNotFound' AlertsEntityNotFound: $ref: '#/components/examples/AlertsEntityNotFound' SuccessWithoutBody: description: Successful Operation BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: InvalidData: $ref: '#/components/examples/InvalidData' AlertsInvalidData: $ref: '#/components/examples/AlertsInvalidData' InvalidParameterSet: $ref: '#/components/examples/InvalidParameterSet' FormatInvalid: $ref: '#/components/examples/FormatInvalid' AlertsFormatInvalid: $ref: '#/components/examples/AlertsFormatInvalid' MissingRequiredHeader: $ref: '#/components/examples/MissingRequiredHeader' PermissionDenied: description: Permission Denied content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: PermissionDenied: $ref: '#/components/examples/PermissionDenied' AlertsPageableAcquirerReferenceIdConfigs: description: Pageable list of acquirer reference id configurations content: application/json: schema: $ref: '#/components/schemas/AlertsPageableAcquirerReferenceIdConfigs' AlertsMerchantIdentifierSuccess: description: Sub-merchant identifiers for either card acceptor id or card acceptor name configuration content: application/json: schema: $ref: '#/components/schemas/AlertsMerchantIdentifierConfigIdOnly' examples: AlertsMerchantIdentifierConfigIdOnly: $ref: '#/components/examples/AlertsMerchantIdentifierConfigIdOnly' schemas: AlertsAcquirerReferenceIdConfigs: description: Acquirer reference id configurations type: array items: $ref: '#/components/schemas/AlertsAcquirerReferenceIdConfig' UserId: title: User Id maxLength: 300 minLength: 1 type: string description: The user id of the submitter/technical contact. example: princess.diana AlertsAcquirerReferenceIdConfigUpdate: description: Acquirer reference id configuration for update type: object properties: binOnlyMatch: $ref: '#/components/schemas/BinOnlyMatch' required: - binOnlyMatch AcquirerReferenceId: title: Acquirer Reference ID (ARID) description: The acquirer BINs that a partner currently services under their portfolio. This is represented by Mastercard DE 31 - Subfield 2 (Clearing), DE 32 (Authorization), or Visa Field 32. type: string minLength: 6 maxLength: 6 pattern: ^[\d]+$ example: '123456' BinOnlyMatch: description: Indicates whether to use only acquirer reference ID (Acquirer BIN) for merchant matching type: boolean default: false example: true CardScheme: description: Name of card scheme may be one of - MASTERCARD, VISA or any other supported schemes type: string minLength: 1 maxLength: 20 example: MASTERCARD AlertsMerchantMemberId: title: Unique identifier for merchants description: Internal Universally Unique Identifier (UUID) which uniquely identifies the merchants type: string format: uuid example: 99ca4b15-72a6-41dd-8127-573d4b07669c ErrorResponse: required: - Errors type: object properties: Errors: $ref: '#/components/schemas/Errors' description: Error Response object FirstName: title: First Name maxLength: 30 minLength: 1 type: string description: The individual's first name example: Michael nullable: true ResponseHeader: type: object properties: totalRecords: type: integer format: int64 description: Total number of records found minimum: 0 maximum: 999999999 example: 500 totalPages: type: integer description: Total number of pages based on limit minimum: 0 maximum: 999999999 example: 10 currentPage: type: integer description: The current page number minimum: 1 maximum: 999999999 example: 2 responseTime: $ref: '#/components/schemas/ResponseTime' AlertsMerchantIdentifierConfigIdOnly: description: Merchant identifier configuration Id (referring to card acceptor id or name configuration) type: object properties: merchantIdentifierConfigId: $ref: '#/components/schemas/AlertsMerchantConfigId' AlertsAcquirerReferenceIdConfig: description: Acquirer reference id configuration type: object properties: merchantIdentifierConfigId: $ref: '#/components/schemas/AlertsMerchantConfigId' acquirerReferenceId: $ref: '#/components/schemas/AcquirerReferenceId' cardScheme: $ref: '#/components/schemas/CardScheme' binOnlyMatch: $ref: '#/components/schemas/BinOnlyMatch' required: - acquirerReferenceId - cardScheme Errors: required: - Error type: object properties: Error: type: array description: List of error objects items: $ref: '#/components/schemas/Error' example: [] description: Errors object LastName: title: Last Name maxLength: 30 minLength: 1 type: string description: The individual's last name example: Fox nullable: true AlertsPageableAcquirerReferenceIdConfigs: description: Pageable response containing acquirer reference id configurations type: object properties: responseHeader: $ref: '#/components/schemas/ResponseHeader' configs: $ref: '#/components/schemas/AlertsAcquirerReferenceIdConfigs' ResponseTime: type: string description: Total response time in ms minLength: 0 maxLength: 10 example: 300 ms AlertsMerchantConfigId: title: Unique identifier for merchants identifier (such as acquirer reference id, card acceptor id or name) configuration description: Internal Universally Unique Identifier (UUID) which uniquely identifies the merchants configuration type: string format: uuid example: 88ca4b15-72a6-41dd-8127-573d4b07558c Error: type: object properties: Source: maxLength: 100 minLength: 0 type: string description: Source of the error example: Service nullable: true ReasonCode: maxLength: 100 minLength: 0 type: string description: A unique constant identifying the error example: format.invalid nullable: true Description: maxLength: 1000 minLength: 0 type: string description: Short description of the error example: Short description of the error nullable: true Recoverable: type: boolean description: Indicates whether this error will always be returned for this request, or retrying could change the outcome example: false default: false nullable: true Details: maxLength: 1000 minLength: 0 type: string description: Optional detailed description of the issue example: Detailed description of the error nullable: true description: Error object parameters: OffsetParam: name: offset in: query required: false description: Number of items per page schema: type: integer default: 25 maximum: 25 example: 25 MerchantIdentifierConfigIdParam: name: merchant_identifier_config_id in: query required: true description: The Configuration ID for acquirer reference ID or card acceptor ID or card acceptor name configurations. schema: $ref: '#/components/schemas/AlertsMerchantConfigId' example: 88ca4b15-72a6-41dd-8127-573d4b07875c SubmitterFirstNameParam: name: Submitter-First-Name in: header required: true example: Diana description: The first name of the submitter/technical contact. schema: $ref: '#/components/schemas/FirstName' CardSchemeParam: name: card_scheme description: Name of card scheme may be one of - MASTERCARD, VISA or any other supported schemes in: query schema: $ref: '#/components/schemas/CardScheme' example: MASTERCARD SubmitterLastNameParam: name: Submitter-Last-Name in: header required: true example: Princess description: The last name of the submitter/technical contact. schema: $ref: '#/components/schemas/LastName' MemberIdParam: name: member_id in: path required: true description: Merchant member ID (parent of the sub-merchant) example: 99ca4b15-72a6-41dd-8127-573d4b07669c schema: $ref: '#/components/schemas/AlertsMerchantMemberId' UserIdParam: name: User-Id in: header required: true example: princess.diana description: The user id of the submitter/technical contact. schema: $ref: '#/components/schemas/UserId' AcquirerReferenceIdParam: name: acquirer_reference_id in: query required: false description: BIN that a partner currently services under their portfolio. schema: $ref: '#/components/schemas/AcquirerReferenceId' example: '123456' PageNumberParam: name: page_number in: query required: false description: Current page number schema: type: integer default: 1 minimum: 1 example: 1