# API Basics
source: https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/api-basics/index.md

## API Security {#api-security}

### Client Authentication {#client-authentication}

Mastercard uses OAuth 1.0a to authenticate your application. After you create a project for the Remote Payment and Presentment Service (RPPS) Biller Maintenance Service, you can manage your authentication keys from your [Developer Dashboard](https://developer.mastercard.com/dashboard).
Tip: Do you want to learn more about the authentication scheme Mastercard uses? For that, read our [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) guide.

### Transport Encryption {#transport-encryption}

All API requests must be sent over HTTPS using **TLS 1.2 or higher**. This secures communication between your application and the Mastercard API servers.

**Payload encryption:** Not required for this API.

## How to Consume the RPPS Biller Maintenance Service {#how-to-consume-the-rpps-biller-maintenance-service}

You can integrate with the RPPS Biller Maintenance Service in more than one way. Choose the approach that best fits your development workflow.

### Integration Approaches {#integration-approaches}

|       Approach       |                      Best For                      |                                                                                                                                            Get Started                                                                                                                                            |
|----------------------|----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Generated API Client | Production integrations; automatic OAuth signing   | [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/)                                                                                                     |
| Manual Integration   | Custom implementations; full control over workflow | [REST API Reference](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/api-reference/index.md) and [OAuth Libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/#client-libraries) |

### Request Format {#request-format}

All requests to the RPPS Biller Maintenance Service must:

* Use REST over HTTPS (TLS 1.2 or higher)
* Include an OAuth 1.0a `Authorization` header signed with your Consumer Key and Signing Key
* Set `Content-Type: application/json` on requests that have a body
* Send the request body as JSON

The example below adds a Biller in the Sandbox. Replace `$AUTH_HEADER` with the OAuth 1.0a header that a Mastercard OAuth library generates for this URL, method, and body. The [Quick Start Guide](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/getting-started/index.md#generate-the-oauth-10a-header) shows how to generate it.

```bash
curl -X POST "https://sandbox.api.mastercard.com/billpay/biller-maintenance-sandbox/biller-request" \
  -H "Authorization: $AUTH_HEADER" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      },
      "addresses": [
        {
          "type": "Sta",
          "address1": "PO BOX 1",
          "city": "O'\''FALLON",
          "state": "MO",
          "postalCode": "63368-0000"
        }
      ],
      "masks": [
        { "maskFormat": "##########", "maskDescriptions": ["auto"] }
      ],
      "akas": [
        { "name": "Capital" }
      ]
    }
  }'
```

### Response Format and Success Criteria {#response-format-and-success-criteria}

Check the HTTP status code and the response body:

* **Success (HTTP 200):** The body contains `"statusIndicator": "SUCCESS"` and a `workRequestId`. Store the `workRequestId` to track the request.
* **Failure (HTTP 400 or 403):** The body contains an `Errors` object. Each error has a `ReasonCode`, a `Description`, and `Details`.

Example success response:

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

For the meaning and resolution of each reason code, see [Code and Formats](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/code-and-formats/index.md).

### Available Endpoints {#available-endpoints}

| Method |                    Path                    |        Environment         |                   Purpose                    |
|--------|--------------------------------------------|----------------------------|----------------------------------------------|
| POST   | `/biller-request`                          | Sandbox / MTF / Production | Add, edit, or deactivate a Biller            |
| GET    | `/biller/{biller_id}`                      | Sandbox / MTF / Production | Retrieve Biller details                      |
| GET    | `/biller-request/{work_request_id}/status` | Sandbox / MTF / Production | Check the status of a submitted work request |

For all parameters, see the [API Reference](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/api-reference/index.md).

### Generating Your Own RPPS Biller Maintenance Service Client {#generating-your-own-rpps-biller-maintenance-service-client}

Create customizable API clients from the RPPS Biller Maintenance Service API specification and let the Mastercard open-source client libraries handle authentication for you. This approach offers the most flexibility and is strongly recommended.

To do this, follow the [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/) tutorial with:

* The following API specification: [rpps-biller-maintenance-service.yaml](https://static.developer.mastercard.com/content/rpps-biller-maintenance-service/swagger/rpps-biller-maintenance-service.yaml) (46KB)

## Environments {#environments}

The table below describes the available environments and their base URLs.

|        **Environment**         |                              **Base URL**                               |                                                                                                    **Description**                                                                                                    |
|--------------------------------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Sandbox                        | `https://sandbox.api.mastercard.com/billpay/biller-maintenance-sandbox` | Limited-capability mock API that helps new clients with initial integration. The Sandbox returns mock responses for defined requests. Use the JSON samples as a reference for sending requests and reading responses. |
| Mastercard Test Facility (MTF) | `https://api.mastercard.com/billpay/mtf/biller-maintenance`             | Pre-production test environment for full integration testing before you move to Production. MTF uses your Production keys.                                                                                            |
| Production                     | `https://api.mastercard.com/billpay/biller-maintenance`                 | Full production environment that contains the latest production API release.                                                                                                                                          |

## Next Steps {#next-steps}

* [Quick Start Guide](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/getting-started/index.md): get credentials and make your first call.
* [API Reference](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/api-reference/index.md): review the full OpenAPI specification.
* [Testing](https://developer.mastercard.com/rpps-biller-maintenance-service/documentation/testing/index.md): review the MTF test scenarios.