# API Basics
source: https://developer.mastercard.com/bill-payment-validator/documentation/api-basics/index.md

## Authentication {#authentication}

Bill Payment Validator uses **OAuth 1.0a** for all API calls.

* Mastercard uses OAuth 1.0a for authenticating client applications
* Requests with a body must be signed using the Google Request Body Hash extension for OAuth
* OAuth Keys for your project can be set up in your Mastercard Developers dashboard
* Client authentication libraries can be found on GitHub, with how-to information provided in README.md files

### OAuth Keys \& Authentication Libraries {#oauth-keys--authentication-libraries}

For detailed setup instructions and language-specific libraries, refer to [Using OAuth 1.0a to Access Mastercard APIs](https://developer.mastercard.com/platform/documentation/using-oauth-1a-to-access-mastercard-apis/).

**Required OAuth credentials for Bill Payment Validator:**

|     Credential     |                                  Description                                   |
|--------------------|--------------------------------------------------------------------------------|
| Consumer Key       | Obtained from Mastercard Developers project page (Actions → Copy Consumer Key) |
| `.p12` Signing Key | Downloaded during project creation in Mastercard Developers                    |
| Key Alias          | The alias you set when creating your key (default Sandbox value: `keyalias`)   |
| Key Password       | The password for your `.p12` file (default Sandbox value: `keystorepassword`)  |

## Transport Encryption {#transport-encryption}

* All Bill Payment Validator API calls must be made over **HTTPS (TLS 1.2 or higher)**
* No additional payload-level encryption is required for this service
* The OAuth 1.0a signature covers the request body hash, ensuring request integrity

## Generating and Configuring a Mastercard API Client {#generating-and-configuring-a-mastercard-api-client}

Use the Mastercard OAuth 1.0a signing library to generate the `Authorization` header required for every API call. The library handles nonce generation, timestamp, signature base string construction, and RSA-SHA256 signing automatically.

### Step-by-Step Setup {#step-by-step-setup}

1. **Download the signing library** for your language from the [Mastercard Developers GitHub](https://github.com/Mastercard):

   * Java: `oauth1-signer-java`
   * Node.js: `oauth1-signer-nodejs`
   * Python: `oauth1-signer-python`
   * C#: `oauth1-signer-csharp`
   * PHP: `oauth1-signer-php`
   * Ruby: `oauth1-signer-ruby`
2. **Load your `.p12` Signing Key** --- provide the file path, key alias, and key password obtained from your Mastercard Developers project.

3. **Construct the request URI** --- the full URL including query parameters (if any): `https://sandbox.api.mastercard.com/billpayAPI/v1/isRoutingValid`

4. **Call the signing helper** --- pass the HTTP method (`POST`), request URI, payload body, Consumer Key, and loaded private key. The library returns a fully formed `Authorization` header value.

5. **Add the header to your request** --- set `Authorization: <generated value>` and `Content-Type: application/json` before sending.

**Java example:**

```java
String consumerKey = "your-consumer-key";
PrivateKey signingKey = AuthenticationUtils.loadSigningKey(
    "/path/to/sandbox-signing-key.p12", "keyalias", "keystorepassword");

HttpEntity payload = new StringEntity("{\"BillPayAccountValidation\":{...}}");
OkHttpClient client = new OkHttpClient();
Request request = new OkHttpOAuth1Interceptor(consumerKey, signingKey)
    .intercept(new Request.Builder()
        .url("https://sandbox.api.mastercard.com/billpayAPI/v1/isRoutingValid")
        .post(RequestBody.create(MediaType.parse("application/json"), payload))
        .build());
```

For a complete runnable example, see [SDK Reference](https://developer.mastercard.com/bill-payment-validator/documentation/sdk-reference/index.md) and [Reference App](https://developer.mastercard.com/bill-payment-validator/documentation/reference-app/index.md).

## How to Consume the API {#how-to-consume-the-api}

Bill Payment Validator exposes a single endpoint:

| Method |              Path               |     Environment      |
|--------|---------------------------------|----------------------|
| `POST` | `/billpayAPI/v1/isRoutingValid` | Sandbox / Production |

**Request format:** JSON (`Content-Type: application/json`)

**Response format:** HTTP 200 for all outcomes (both successful validation and business-level errors). The `ResponseString` field in the response body carries the business result:

* `"Successful"` --- payment details passed all RPPS validation rules
* Any other value --- a specific error description (e.g., `"Invalid RPPSID"`, `"Transaction Amount exceeds BillerID maximum"`)

See [Code and Formats](https://developer.mastercard.com/bill-payment-validator/documentation/code-and-formats/index.md) for the complete error code reference and resolution guidance.

## Next Steps {#next-steps}

* [Quick Start Guide](https://developer.mastercard.com/bill-payment-validator/documentation/getting-started/index.md) --- get your credentials and make your first sandbox call
* [API Reference](https://developer.mastercard.com/bill-payment-validator/documentation/api-reference/index.md) --- full OpenAPI specification with all request/response fields
* [SDK Reference](https://developer.mastercard.com/bill-payment-validator/documentation/sdk-reference/index.md) --- language-specific code samples (Java, C#, Node.js, PHP, Python, Ruby)
* [Testing](https://developer.mastercard.com/bill-payment-validator/documentation/testing/index.md) --- sandbox test scenarios for positive and negative validation cases