# Code and Formats source: https://developer.mastercard.com/bill-payment-validator/documentation/code-and-formats/index.md ## Error Codes {#error-codes} All Bill Payment Validator business errors are returned with **HTTP 200** . The `ResponseString` field in the response body carries the error description. Use the table below to identify the error, understand its cause, and follow the resolution steps. **Endpoint:** All errors below can be returned by `POST /billpayAPI/v1/isRoutingValid`. | Error Code | Error Description | When It Occurs | Resolution Steps | |------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | OA001 | RPPSID is required | `RppsId` field is empty or missing in the request | 1. Check that `BillPayAccountValidation.RppsId` is present in the request body. 2. Populate it with your 8-character RPPS Originator ID. 3. Resubmit the request. | | OA002 | BillerID is required | `BillerId` field is empty or missing in the request | 1. Check that `BillPayAccountValidation.BillerId` is present in the request body. 2. Populate it with a valid 10-character Biller ID. 3. Resubmit the request. | | OA003 | Account Number is required | `AccountNumber` field is empty or missing in the request | 1. Check that `BillPayAccountValidation.AccountNumber` is present in the request body. 2. Populate it with the consumer's account number (1--22 characters). 3. Resubmit the request. | | OA004 | Account Number did not match BillerID masks | The account number format does not match the mask rules registered for the specified BillerID | 1. Verify the consumer's account number format against the biller's requirements. 2. Check that leading zeros and account number length match what the biller expects. 3. Correct the account number in the request and resubmit. | | OA005 | Account Number failed on a check digit | The account number fails the check digit algorithm registered for the specified BillerID | 1. Verify the account number digit-by-digit with the consumer (transcription errors are common). 2. Ensure the full account number including any check digit character is provided. 3. Correct the account number and resubmit. | | OA008 | RPPSID is not an Originator | The `RppsId` provided is not registered as an RPPS Originator | 1. Confirm you are using your RPPS Originator ID (not a Receiver or Biller ID). 2. Contact your CIS Implementation Manager to verify your RPPS Originator status. 3. Resubmit with the correct Originator RPPS ID. | | OA009 | RPPSID does not have access to BillerID | The RPPS Originator does not have RPPS network access to the specified Biller | 1. Confirm the BillerID is correct for the intended biller. 2. Contact your CIS Implementation Manager to verify your originator's access to that biller. 3. If access is confirmed, resubmit; if not, contact Mastercard to establish access. | | OA010 | Invalid BillerID | The `BillerId` provided is not a valid RPPS Biller ID | 1. Verify the BillerID value (must be 10 digits). 2. Check for typos or incorrect biller information provided by the consumer. 3. Correct the BillerID in the request and resubmit. | | OA011 | BillerID is not active | The specified BillerID exists in RPPS but is not currently active | 1. Confirm with the consumer that the biller is still accepting RPPS payments. 2. Contact your CIS Implementation Manager to check biller status. 3. Do not submit RPPS payment transactions to inactive billers. | | OA012 | Invalid RPPSID | The `RppsId` provided is not a valid RPPS ID | 1. Verify your RPPS Originator ID in your Mastercard Developers project. 2. Ensure the value is exactly 8 characters with no leading/trailing spaces. 3. Correct and resubmit. | | OA013 | RPPSID is not active | The specified RPPS Originator ID is not currently active | 1. Contact your CIS Implementation Manager to check the status of your RPPS Originator ID. 2. Do not submit payment transactions while the RPPS ID is inactive. | | OA017 | Transaction Amount exceeds BillerID maximum | The `TransactionAmount` exceeds the maximum payment amount configured for the specified BillerID | 1. Check the biller's maximum transaction limit (varies by biller). 2. Reduce the transaction amount or split into multiple payments if permitted. 3. Resubmit with an amount at or below the biller's limit. | | OA018 | BillerID will not accept transactions for the Account Number | The biller's RPPS configuration excludes the specified account number from payment acceptance | 1. Verify the consumer's account number with their biller statement. 2. Contact your CIS Implementation Manager for guidance on whether the biller accepts the account type. 3. Advise the consumer to contact their biller directly to confirm payment eligibility. | | OA019 | Invalid Account Number | The account number provided is structurally invalid (e.g., exceeds maximum length of 22 characters) | 1. Check that `AccountNumber` is between 1 and 22 characters. 2. Remove any spaces, special characters, or extra digits. 3. Correct and resubmit. | ## Resolution Tips {#resolution-tips} When a non-`Successful` `ResponseString` is returned, follow this recovery workflow before re-submitting: 1. **Identify the error code** --- match the `ResponseString` value to the Error Code table above (e.g., `"Invalid BillerID"` → OA010) 2. **Check the originating field** --- the error code prefix maps directly to the affected field: `RppsId` (OA001/OA008/OA012/OA013), `BillerId` (OA002/OA009/OA010/OA011), `AccountNumber` (OA003/OA004/OA005/OA018/OA019), `TransactionAmount` (OA017) 3. **Validate the input value** --- confirm the value meets field-level format requirements (8-char RPPSID, 10-char BillerID, 1--22 char AccountNumber, numeric TransactionAmount) 4. **Check RPPS access and status** --- for OA008, OA009, OA011, OA013 errors, the issue is configuration-based (inactive or unauthorized), not a data-entry error; contact your CIS Implementation Manager 5. **Correct and re-submit** --- fix only the field identified by the error code; other fields do not need to change 6. **Escalate if unresolved** --- if the error persists after correcting the input, refer to the [Support](https://developer.mastercard.com/bill-payment-validator/documentation/support/index.md) page and use the Get Help button to contact your CIS Implementation Manager ## Response Codes {#response-codes} This API returns **HTTP 200** for all successful and business-error scenarios. The business result is communicated via the `ResponseString` field in the response body: * `"Successful"` --- all RPPS validation rules passed; the payment transaction may be submitted * Any other value --- a specific error description from the table above ## Gateway Error Codes {#gateway-error-codes} HTTP 4xx/5xx responses indicate gateway-layer issues (authentication failures, malformed requests, server errors) rather than business validation results. For further information about 4xx/5xx response codes and possible resolutions, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/gateway-error-codes/). Common gateway errors for Bill Payment Validator: | HTTP Status | Likely Cause | Resolution | |-------------|-----------------------------------------------------|-----------------------------------------------------------------------------------| | 400 | Malformed OAuth signature or invalid request format | Verify OAuth 1.0a header generation; check JSON request body syntax | | 401 | Invalid Consumer Key or signing key | Confirm Consumer Key and `.p12` file match your Mastercard Developers project | | 404 | Incorrect endpoint URL | Use `https://sandbox.api.mastercard.com/billpayAPI/v1/isRoutingValid` for Sandbox | ## Error Structure {#error-structure} To ensure a consistent experience across all Mastercard APIs, the following structure is used by Bill Payment Validator for gateway-layer errors: Single Error: ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true } ] } } ``` Multiple Errors: ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true }, { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": false } ] } } ``` ## Bill Payment Validator Specific Errors {#bill-payment-validator-specific-errors} Business-level errors (OA001--OA019) are returned inside the standard `BillPayAccountValidation` response object with a non-`Successful` `ResponseString`. Example: ```json { "BillPayAccountValidation": { "RppsId": "", "BillerId": "0206990420", "AccountNumber": "4820008501111117", "TransactionAmount": "223", "ResponseString": "RPPSID is required" } } ``` ## Next Steps {#next-steps} * [Testing](https://developer.mastercard.com/bill-payment-validator/documentation/testing/index.md) --- sandbox test data for triggering each error scenario * [API Reference](https://developer.mastercard.com/bill-payment-validator/documentation/api-reference/index.md) --- full request/response field definitions * [Support](https://developer.mastercard.com/bill-payment-validator/documentation/support/index.md) --- FAQ and contact information if errors persist