# Use Cases
source: https://developer.mastercard.com/bill-payment-validator/documentation/use-cases/index.md

Bill Payment Validator supports four integration scenarios for RPPS Originators. All four use cases call the same single endpoint --- `POST /billpayAPI/v1/isRoutingValid` --- but differ in when during the consumer/biller workflow the validation is triggered.

### Use Case Summary {#use-case-summary}

|              Use Case              |        Who Uses It        |                When Validation Is Called                 |                           Business Goal                            |
|------------------------------------|---------------------------|----------------------------------------------------------|--------------------------------------------------------------------|
| Walk-in Payments                   | Walk-in Payment Providers | Before consumer leaves the agent/retail location         | Immediate confirmation before over-the-counter payment is accepted |
| Biller Onboarding Validation       | Banks / FinTech Providers | When a consumer adds a new biller/payee                  | Prevent invalid biller setups before the first payment attempt     |
| Consumer-Biller Linking Validation | Banks / FinTech Providers | Periodically, to re-verify existing biller/payee setups  | Keep consumer payment records accurate and avoid future rejections |
| Bill Payment Validation            | Banks / FinTech Providers | Before submitting payment transaction in RPPS batch file | Reduce rejected RPPS transactions before file submission           |

*** ** * ** ***

### Use Case 1: Walk-in Payments {#use-case-1-walk-in-payments}

A Walk-in Payment Provider running an over-the-counter bill payment service that needs immediate confirmation that a potential RPPS transaction would process successfully before a consumer leaves the agent/retail location.

**Why `POST /isRoutingValid`:** The walk-in provider must confirm biller account validity in real time --- before the consumer's payment is accepted and cash/payment is collected. The validation endpoint returns an immediate pass/fail response so the agent can act before the consumer departs.

**Integration steps:**

1. Consumer presents bill payment details (biller, account number, amount) to the walk-in agent
2. Walk-in provider system calls `POST /isRoutingValid` with the consumer's payment details
3. If `ResponseString` is `"Successful"` --- accept the payment and proceed
4. If `ResponseString` is an error --- inform the consumer and request corrected details before accepting payment

Diagram walk-in-payment

**API call for this use case:**

API Reference: `POST /isRoutingValid`

*** ** * ** ***

### Use Case 2: Biller Onboarding Validation {#use-case-2-biller-onboarding-validation}

A Bank/Financial Institution/FinTech Provider running an online banking bill payment service that wants to validate new RPPS biller/payee setup requested by a consumer.

**Why `POST /isRoutingValid`:** When a consumer adds a new biller, the system should verify the biller account relationship is valid in RPPS before storing it. Early validation prevents future payment rejections caused by invalid account numbers, inactive billers, or account number format mismatches.

**Integration steps:**

1. Consumer requests to add a new biller/payee in the online banking portal
2. Bank/FinTech system calls `POST /isRoutingValid` with the proposed biller and account details
3. If `ResponseString` is `"Successful"` --- save the biller/payee setup and confirm to the consumer
4. If `ResponseString` is an error --- prompt the consumer to verify and re-enter their biller account details before saving

Diagram biller-onboarding

**API call for this use case:**

API Reference: `POST /isRoutingValid`

*** ** * ** ***

### Use Case 3: Consumer-Biller Linking Validation {#use-case-3-consumer-biller-linking-validation}

A Bank/Financial Institution/FinTech Provider running an online banking bill payment service that wants to periodically verify a consumer's existing RPPS biller/payee setup.

**Why `POST /isRoutingValid`:** Biller account rules can change over time (e.g., a biller becomes inactive or changes account masking requirements). Periodic re-validation of stored biller setups catches stale consumer-biller links before they result in payment rejections.

**Integration steps:**

1. Bank/FinTech system triggers periodic validation of stored consumer-biller relationships (e.g., during a nightly batch or at payment scheduling time)
2. System calls `POST /isRoutingValid` for each consumer-biller pair being verified
3. If `ResponseString` is `"Successful"` --- no action required; biller link remains valid
4. If `ResponseString` is an error --- flag the consumer-biller link for review and notify the consumer to update their biller account details

Diagram biller-linking

**API call for this use case:**

API Reference: `POST /isRoutingValid`

*** ** * ** ***

### Use Case 4: Bill Payment Validation {#use-case-4-bill-payment-validation}

A Bank/Financial Institution/FinTech Provider running an online banking bill payment service that wants to verify an RPPS bill payment transaction would process successfully before sending the payment transaction in their RPPS batch transaction file.

**Why `POST /isRoutingValid`:** RPPS batch files are processed on a schedule; a rejected payment in the batch causes delays and additional remediation effort. Calling the validation endpoint before batch submission allows the originator to catch and correct invalid transactions in advance, reducing costly and untimely rejections.

**Integration steps:**

1. Consumer initiates a bill payment in the online banking portal; the transaction is queued for RPPS batch submission
2. Before building the batch file, the Bank/FinTech system calls `POST /isRoutingValid` for each queued payment
3. If `ResponseString` is `"Successful"` --- include the transaction in the RPPS batch file
4. If `ResponseString` is an error --- remove the transaction from the batch, notify the consumer, and request corrected payment details before the next batch cycle

Diagram bill-payment-validation

**API call for this use case:**

API Reference: `POST /isRoutingValid`

*** ** * ** ***

## Next Steps {#next-steps}

* [API Reference](https://developer.mastercard.com/bill-payment-validator/documentation/api-reference/index.md) --- full OpenAPI specification with all request/response fields
* [Testing](https://developer.mastercard.com/bill-payment-validator/documentation/testing/index.md) --- sandbox test data for all four use cases, positive and negative scenarios
* [Code and Formats](https://developer.mastercard.com/bill-payment-validator/documentation/code-and-formats/index.md) --- complete error code reference and resolution guidance
* [SDK Reference](https://developer.mastercard.com/bill-payment-validator/documentation/sdk-reference/index.md) --- copy/paste code samples in Java, C#, Node.js, PHP, Python, Ruby