# Onboarding New Biller
source: https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/add-biller/index.md

### Onboarding New Biller {#onboarding-new-biller}

Concentrators can add their new billers via the Remote Payment and Presentment Service (RPPS) Biller Maintenance Service directly from their system. The API will ensure all the business rules are being met, and if not, will advise the Concentrator when issues arise and how to correct them. This is accomplished by calling the biller-request path.

### Step-by-Step Workflow {#step-by-step-workflow}

**Step 1:** Prepare biller data (name, ID, type, addresses, masks) according to requirements
**Step 2:** Call POST `/biller-request` with action "Add" and biller details
**Step 3:** Receive Work Request ID if successful
**Step 4:** Store the Work Request ID for status tracking
**Step 5:** Poll Work Request Status to check approval (minimum 5 business days + effective date)
**Step 6:** Once approved and effective date passed, biller is live in RPPS

#### Rationale {#rationale}

The Add Biller endpoint is used to initiate the onboarding process. RPPS validates format and basic business rules immediately, then runs additional background validations over several days. This staged approach ensures data quality while maintaining fast API response times.

#### API Reference {#api-reference}


API Reference: `POST /biller-request`

## Adding a Biller {#adding-a-biller}

### Request - Static Test Data {#request---static-test-data}

Below is an example request body for onboarding a new biller.

```json
{
  "billerRecordAction": "Add",
  "effectiveDate": "2030/12/31",
  "rppsBiller": {
    "billerInfo": {
      "rppsId": "01234567",
      "billerId": "0123456789",
      "billerName": "ABC Lawn Service",
      "batchName": "ABC Lawn",
      "billerClass": "INS",
      "billerType": "CRE",
      "remittanceRTN": "111111111",
      "remittanceDDA": "654321",
      "preNotes": "Y",
      "externalNotes": "Please remove all dashes from the consumer's account number before matching to the RPPS account mask and sending the payment."
    },
    "addresses": [
      {
        "type": "Sta",
        "address1": "PO BOX 1",
        "city": "O'FALLON",
        "state": "MO",
        "postalCode": "63368-0000"
      }
    ],
    "masks": [
      {
        "maskFormat": "##########",
        "maskDescriptions": [
          "auto"
        ]
      }
    ],
    "akas": [
      {
        "name": "Capital"
      }
    ]
  }
}
```

### Response - Success {#response---success}

```json
{
  "billerRecordAction": "Add",
  "billerId": "0123456789",
  "statusIndicator": "SUCCESS",
  "statusDescription": "Successfully created workflow request",
  "workRequestId": 100001,
  "effectiveDate": "2030/12/31"
}
```

### Response - Error {#response---error}

The following example shows the error returned when your Client ID does not have access to manage Billers:

```json
{
  "Errors": {
    "Error": [
      {
        "Source": "RPPS Biller Maintenance Service",
        "ReasonCode": "BPBMSAPI_ERR_0072",
        "Description": "Access Denied",
        "Recoverable": false,
        "Details": "Client ID does not have access to manage billers"
      }
    ]
  }
}
```

<br />

## Next Steps {#next-steps}

For what is required in the payload, please refer to [Parameters](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/parameters/add-biller-parameters/index.md).

Please continue to [Work Request Status](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/use-cases/work-request-status/index.md).