# Remote Payment and Presentment Service (RPPS) Biller Maintenance Service
source: https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/index.md

## Overview {#overview}

This documentation describes the Mastercard Remote Payment and Presentment Service (RPPS) Biller Maintenance Service and explains how to use it. It is written for developers and technical managers at RPPS Concentrators who want to integrate with the Bill Pay platform to manage Billers programmatically. The service removes manual data entry in the RPPS user interface (UI), reduces errors, and enables automated Biller onboarding at scale.

**Key problems this API solves:**

* **Manual Biller management is slow and error-prone:** Submit Biller additions, edits, and deactivations as API requests instead of entering them in the RPPS UI.
* **Limited visibility into Biller status:** Retrieve the current work request status through the API instead of repeatedly logging in to the UI.
* **Late discovery of data errors:** The service validates the format of each request on submission and returns specific reason codes, so you can correct errors before Mastercard reviews the Biller.
* **Slow approval workflows:** Track each Biller through the approval process, which requires an effective date at least 5 business days after submission.

Mastercard Bill Pay meets the everyday bill payment needs of Concentrators and Originators. It connects the two sides of the bill pay ecosystem, Billers and consumers, and facilitates bill payments between them, bringing transparency, consistency, speed, and simplicity to the bill pay experience.

For marketing and case study details, see [the product page](https://developer.mastercard.com/product/bill-pay).

### Technical Context {#technical-context}

* **Protocol:** HTTPS REST / JSON
* **Authentication:** OAuth 1.0a (signature-based)
* **Main Endpoints:**
  * POST `/biller-request`: Add, edit, or deactivate a Biller
  * GET `/biller/{biller_id}`: Retrieve Biller details
  * GET `/biller-request/{work_request_id}/status`: Retrieve the status of a work request
* **Response Pattern:** HTTP 200 with `statusIndicator: SUCCESS` and a `workRequestId` when a request is accepted; HTTP 400 or 403 with an `Errors` object that contains a `ReasonCode` when it is rejected. See [Code and Formats](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/code-and-formats/index.md).
* **Ecosystem Role:** Call this API during Biller onboarding and maintenance, before the Biller can be used in RPPS payment transactions.

## How It Works {#how-it-works}

Diagram overview

The RPPS Biller Maintenance Service allows Concentrators to add, edit, and deactivate Billers in the RPPS system through an API. Business rules require the effective date (live date) to be at least 5 business days after the submission date.

### Add Biller {#add-biller}

1. A Concentrator submits a work request with the `Add` action to the RPPS Biller Maintenance Service.
2. The service validates formatting and basic business rules, such as field formats, lengths, and valid values.
3. If validation succeeds, the service creates a work request for the Biller.
4. The service returns a successful response with the work request ID to the Concentrator.
5. Fine-grained business rules run in the background to check whether all values meet the additional requirements.

The Concentrator should store the work request ID. Secondary business rule validations can reject a Biller or require manual edits. For example, a Biller that matches an existing Biller is a duplicate and is rejected. Billers that match restricted words are also rejected to prevent payments to illegal Billers. The RPPS UI does not display rejected work requests, so use the [Work Request Status](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/work-request-status/index.md) API to retrieve their status. Alternatively, log in to the Mastercard RPPS system to confirm which work requests are approved, which are pending further review or edits, and which are rejected after manual matching.

For details, see [Add Biller](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/add-biller/index.md).
Diagram add

### Edit Biller / Get Biller Details {#edit-biller--get-biller-details}

1. An edit requires key fields to update child records, such as remittance addresses, AKAs (also-known-as names), masks, and mask descriptions. The Concentrator retrieves these keys by calling GET `/biller/{biller_id}`.
2. The service returns the Biller details, which the Concentrator uses to build the `Edit` request.
3. The Concentrator submits a work request with the `Edit` action to the RPPS Biller Maintenance Service.
4. The service validates formatting and basic business rules, such as field formats, lengths, and valid values.
5. If validation succeeds, the service creates a work request for the Biller.
6. The service returns a successful response with the work request ID to the Concentrator.

The Concentrator should store the work request ID and use the Work Request Status API to retrieve the status of the work request. Alternatively, log in to the Mastercard RPPS system. For details, see [Edit Biller](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/edit-biller/index.md) and [Get Biller Details](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/get-biller-details/index.md).
Diagram edit

### Deactivate Biller {#deactivate-biller}

1. A Concentrator submits a work request with the `Deactivate` action to the RPPS Biller Maintenance Service.
2. The service validates formatting and basic business rules, such as field formats, lengths, and valid values.
3. If validation succeeds, the service creates a work request for the Biller.
4. The service returns a successful response with the work request ID to the Concentrator.

The Concentrator should store the work request ID and use the Work Request Status API to retrieve the status of the work request. Alternatively, log in to the Mastercard RPPS system. For details, see [Deactivate Biller](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/deactivate-biller/index.md).
Diagram deactivate

### Get Work Request Details {#get-work-request-details}

1. A Concentrator calls GET `/biller-request/{work_request_id}/status` with the work request ID.
2. The service validates the format of the work request ID.
3. The service returns the current status of the work request.

Diagram getworkrequest

An approved work request stays in the `APPROVED` state until the submitted effective date. After the changes go live (`IMPLEMENTED`), the Biller can be edited again. If a Concentrator needs to remove a Biller from Bill Pay, it can deactivate the Biller. For details, see [Work Request Status](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/work-request-status/index.md).

## Get Started {#get-started}

To set up access and make your first Sandbox call, follow the [Quick Start Guide](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/getting-started/index.md). It covers prerequisites, credentials, OAuth 1.0a signing, a runnable first request, the expected response, and the steps to move to Production.

## Next Steps {#next-steps}

* [Quick Start Guide](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/getting-started/index.md): set up access and make your first Sandbox call.
* [Add Biller](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/add-biller/index.md): onboard a new Biller and review the required parameters.
* [Work Request Status](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/work-request-status/index.md): check the status of submitted work requests.
* [API Reference](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/api-reference/index.md): review the full OpenAPI specification and environment URLs.