# Quick Start Guide
source: https://developer.mastercard.com/bill-payment-validator/documentation/getting-started/index.md

## Before You Start {#before-you-start}

**Prerequisites checklist** --- have the following ready before proceeding:

* [ ] Your organization is a registered RPPS customer (RPPS agreements and enrollment forms signed and returned)
* [ ] Mastercard Product Delivery and/or CIS Implementation Manager has been assigned to you
* [ ] Mastercard Developers account created at [developer.mastercard.com](https://developer.mastercard.com)
* [ ] Bill Payment Validator project created in Mastercard Developers (Consumer Key + Sandbox Signing Key downloaded)
* [ ] `.p12` Sandbox Signing Key file stored securely (you will need the file path, key alias, and key password)

**Requirements**

* Your organization must be a registered RPPS customer to use the Bill Payment Validator API
* Bill Payment Validator API is only compatible with RPPS transaction data, and does NOT support card payment networks

**Used by**

Licensed RPPS Originators (banks, financial institutions, fintech providers and walk-in payment providers who support consumer bill payments)

**Pricing**

Contact us for pricing information

## Good to Know {#good-to-know}

To start using the Bill Payment Validator API, you must set up a project in Mastercard Developers (which creates the necessary project keys) and complete testing in the Mastercard Testing Facility (MTF) Sandbox environment before proceeding to the Production environment. Sandbox testing cannot begin until the eligibility requirements have been met.

## Sandbox Setup Steps {#sandbox-setup-steps}

The following steps assume you have already completed and returned the Mastercard RPPS agreements and enrollment forms.

1. **\[Entry criteria: signed RPPS agreements received by Mastercard\]** Upon receipt of signed agreements/enrollment forms, Mastercard Product Delivery and/or CIS Implementation Managers are assigned to you, based upon resources.
2. Create a Mastercard Developers project and the necessary Sandbox keys by clicking **Create Project**.
3. For Select an API, choose **Bill Payment Validator**.
4. Download the Sandbox Signing Key and confirm that you have stored the file. You will receive notification that the project was created.
5. Copy the Consumer Key from your project page using **Actions \> Copy Consumer Key**.
6. **\[Entry criteria: Mastercard confirms Sandbox configuration is complete\]** Complete all onboarding steps.
7. **\[Entry criteria: implementation plan steps completed\]** Complete attended testing certification in the MTF Sandbox. The Implementation Manager will provide the test cases.

## First Sandbox Call {#first-sandbox-call}

Once your project is set up and Sandbox configuration is confirmed, you can make your first Bill Payment Validator call.

### Authentication Setup {#authentication-setup}

Bill Payment Validator uses **OAuth 1.0a**. You will need:

|       Credential        |                         Where to find it                         |
|-------------------------|------------------------------------------------------------------|
| Consumer Key            | Mastercard Developers project page → Actions → Copy Consumer Key |
| `.p12` Signing Key file | Downloaded during project creation                               |
| Key alias               | `keyalias` (default for Sandbox)                                 |
| Key password            | `keystorepassword` (default for Sandbox)                         |

For detailed OAuth 1.0a setup, see [API Basics](https://developer.mastercard.com/bill-payment-validator/documentation/api-basics/index.md).

### Sandbox Base URL {#sandbox-base-url}

    https://sandbox.api.mastercard.com/billpayAPI/v1/isRoutingValid

### Sample Sandbox Request {#sample-sandbox-request}

Use the following curl example to make your first call. Replace the OAuth Authorization header with one generated using your credentials (see [API Basics](https://developer.mastercard.com/bill-payment-validator/documentation/api-basics/index.md)):

```bash
curl -X POST "https://sandbox.api.mastercard.com/billpayAPI/v1/isRoutingValid" \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth realm=\"\",...(generated OAuth 1.0a header)" \
  -d '{
    "BillPayAccountValidation": {
      "RppsId": "99887761",
      "BillerId": "9998887771",
      "AccountNumber": "1234567890",
      "TransactionAmount": "250.00"
    }
  }'
```

### What Success Looks Like {#what-success-looks-like}

A successful first call returns **HTTP 200** with the following response body:

```json
{
  "BillPayAccountValidation": {
    "RppsId": "99887761",
    "BillerId": "9998887771",
    "AccountNumber": "1234567890",
    "TransactionAmount": "250.00",
    "ResponseString": "Successful"
  }
}
```

`"ResponseString": "Successful"` confirms that the biller account details pass all RPPS transaction processing edits. If validation fails, `ResponseString` will contain 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 full list of error codes and resolution guidance.

## Moving to Production {#moving-to-production}

### Entry/Exit Criteria for Each Stage {#entryexit-criteria-for-each-stage}

|         Stage          |                         Entry Criteria                         |                                 Exit Criteria                                  |
|------------------------|----------------------------------------------------------------|--------------------------------------------------------------------------------|
| **Sandbox Setup**      | RPPS agreements signed; Mastercard Developers project created  | Mastercard confirms Sandbox configuration complete (allow 5-7 business days)   |
| **MTF Certification**  | Sandbox configuration complete; implementation plan steps done | All attended test cases provided by Implementation Manager pass                |
| **Production Request** | MTF certification complete; Go Live date agreed                | Production Access approved in Mastercard Developers; Production keys generated |
| **Production Enabled** | Production keys provided to Implementation Manager             | Mastercard confirms Production configuration complete                          |

### Production Request: Required Artifacts {#production-request-required-artifacts}

When submitting your **Request Production Access** in Mastercard Developers, have the following ready:

* Signed RPPS contract amendment (confirming Production eligibility)
* Agreed Go Live date with your Implementation Manager
* Completed MTF Sandbox certification (all test cases passed)
* Production Consumer Key and `.p12` Signing Key (generated after approval)

### Production Steps {#production-steps}

8. Agree a Go Live date with the Implementation Manager.
9. In your project page, click **Request Production Access** to start moving your project to Production and create the Production keys. Once your request is approved, provide the keys to the Implementation Manager. If you are implementing multiple Mastercard Send programs, you might only need to perform this step once.

### Escalation Path {#escalation-path}

If the documented **5-7 business day** Sandbox configuration SLA is exceeded, or if Production enablement is delayed:

1. Contact your assigned **CIS Implementation Manager** directly (contact details provided in your implementation project plan)
2. If unresolved within 2 additional business days, escalate to your **Product Delivery Manager**
3. For general support outside of assigned contacts, use the [Get Help](https://developer.mastercard.com/bill-payment-validator/documentation/support/index.md) button on the Support page, referencing your project name and the date configuration was initiated

## Next Steps {#next-steps}

* [API Basics](https://developer.mastercard.com/bill-payment-validator/documentation/api-basics/index.md) --- OAuth 1.0a authentication details, TLS encryption, and SDK setup
* [Use Cases](https://developer.mastercard.com/bill-payment-validator/documentation/use-cases/index.md) --- walk-in payments, biller onboarding, consumer-biller linking, and bill payment validation flows
* [Testing](https://developer.mastercard.com/bill-payment-validator/documentation/testing/index.md) --- positive and negative sandbox test scenarios
* [API Reference](https://developer.mastercard.com/bill-payment-validator/documentation/api-reference/index.md) --- full OpenAPI specification and environment URLs