The Order Validation Callback (OVC) gives clients the ability to create and/or update orders without the hassle of additional bulk file submissions or manual interventions. These near real-time validations allow merchants to validate a consumer’s account quickly and then decide whether to accept or decline the payment.

The callback can be set up in two different configurations: Classic Order Validation and Revalidation. Classic OVC can be used to create/update orders and gives merchants the ability to approve, conditionally approve, or stop consumers from making payments. The Revalidation callback is used for synchronizing data at the time of payment so that consumers have the most up-to-date information. PayNearMe can also configure the Revalidation callback to suspend the order to prevent payment after receiving an exception response from the server.

The callback is triggered when consumers or agents submit non-PII data via PayNearMe-hosted payment forms in the Consumer Portal, Business Portal, Embedded Form, Embedded Client or IVR. Using the submitted data, PayNearMe makes a HTTPS GET or POST call to a merchant-hosted API endpoint or third-party service (e.g., such as Loan Management or EBPP systems) to authenticate the consumer’s account and either create or update the order. Parameter values are submitted within the URL for GETs or within the body for POSTs. The data can be formatted either as XML or JSON.

The merchant has five seconds to determine if the submitted data is valid and then respond with one of three options:

approval=go – The account data matches, and the consumer or agent can continue through the PayNearMe web flow.
approval=approve – The account data matches, but the consumer or agent needs to confirm additional information (e.g., an address or name). If confirmed, the consumer or agent proceeds through the PayNearMe web flow. If not confirmed, the web flow is canceled. NOTE: Not available for the Revalidation callback.
approval=stop – The account data does not match, and the modal or embedded form displays an error message and offers a chance for the user to try again (in case of data-entry error).

With each response, the merchant can include updated parameter values (including custom parameters), which PayNearMe uses to automatically update the order. For example, a lending merchant could send an approval=stop response with site_order_suspend=true if an account was now marked delinquent and in collections in their system. A gaming merchant might want to return the current balance of funds available for a withdrawal.

Understanding the Different OVC Versions

Classic OVC

Merchants use the classic Order Validation callback to create/update orders and then indicate whether to accept the payment (go), conditionally accept the payment after additional consumer input (approve), or decline the payment (stop). For example, a health club that wanted to accept cash payments for dues could set up their system so that when consumers enter lookup data (e.g., member number and/or name) the Order Validation callback is triggered to validate the account with the club and then create and return the order with a barcode. If the member number is associated with a closed or delinquent account, the club could respond with approval=stop to prevent the consumer from making a payment. If the consumer entered the correct member number but used a different name to validate, the club could respond with approval=approve and ask the consumer to re-enter or confirm his/her information. The classic Order Validation callback can be used to create orders along with the consumer-entered data from the hosted payment form.

Revalidation

The Revalidation callback is used with existing orders to update and synchronize data. For example, if a lending merchant needed to provide a consumer with an exact payoff amount for a loan, the Revalidation callback could be used to return that calculated amount. The Revalidation callback requires merchants to define a timeframe in seconds for how long the revalidated values are good for. Typically, this is 300 seconds (i.e., 5 minutes), but can be customized according to the merchant’s business and compliance rules. If the consumer or agent does not complete the payment within the revalidation timeframe, the payment form will update again to provide the latest value. For example, a merchant selling bitcoin or stock could use the Revalidation callback to honor a quoted price for 5 minutes. If the consumer failed to complete his/her payment within that 5-minute timeframe, the Revalidation callback would fire again and update the quoted price on the payment form. Merchants can configure the Revalidation callback to approve all payments after updates (the default setting known as autopilot) or can have PayNearMe set up the form to suspend orders when an exception occurs.

Configuring Access for PayNearMe

Both versions of the Order Validation callback require an initial setup to grant PayNearMe access to the your API server endpoints or third-party data management system/services. While each setup configuration is different and beyond the scope of this document, the following may need to be provided to PayNearMe:

API Keys and/or access tokens
A Sandbox environment for testing
An API specification document
Whitelisting PayNearMe IP Addresses

Setting Up the Validation Form

The validation form displayed to the consumer or agent can be customized according to your validation standards. All forms must include a unique account identifier, which is stored in either the site_customer_identifier or site_order_identifier parameters. Account identifiers can include the following:

Case Number
Docket Number
Citation Number
Loan Number
Account ID
Invoice Number
Bill ID

Additional validation fields can include the parameters from PayNearMe’s API or custom parameters created specifically for your site.

Configuring the Callback

To configure either Classic OVC or the Revalidation callback, you must go to the Configure section of the PayNearMe Business Portal using Callbacks > Configure and Status. You will need to set the following in the section for Order Validation:

Order Validation URL
- For Classic OVC use https://server.mycompany.com/order_validation
- For Revalidation use https://server.mycompany.com/pnm-revalidate
- NOTE: Removing the value for the Order Validation URL will disable the callback and can be used as an on/off switch.
HTTP verb (e.g., post_json)

Setting Up the Revalidation Callback

You will need to provide the following information:

The revalidation window in seconds.
- This is how often PayNearMe will make a subsequent Revalidation callback after a successful revalidation to refresh data while a customer/agent has a payment flow open in a browser. In most cases, this should be 300 seconds minimum. timeframe in seconds.
- In case of a revalidation error, PayNearMe will retry every 30 seconds while in a payment flow.
- The very first time a customer/agent accesses a specific payment flow, the Revalidation callback will always occur.
Behavior regarding callback errors/exceptions. If enabled and a callback returns an error (timeout, server error, etc.), the customer account will be suspended (and be unable to pay). The customer record is not updated.
Do you want to support order suspension from RVC?
- If enabled, returning STOP in the approval field will suspend the current customer account. PayNearMe will still update the customer account with any returned data.
- If disabled (referred to as auto-pilot mode), all non-error responses will be treated as approval GO (customer account updated and payments allowed).

Understanding the Callback Parameters

The body or URL of the Order Validation callback includes the submitted validation fields (site_order_identifier or site_customer_identifier) along with the following required parameters:

Parameter	Description	Type	Req
`origin`	Indicates where the callback was triggered. Supported values for this field include the following: `agent` – The callback was triggered by an agent submitting data via the agent interface in the business portal or via the embedded form. `buynow` – The callback was triggered by the consumer submitting data in the consumer portal via the web flow or the embedded client. `ivr` – The callback was triggered by the consumer submitting data telephonically via the merchant’s interactive voice recognition (IVR) system. `reval` – The callback was triggered by the consumer or agent requesting the most up-to-date data values for an existing order (revalidation).	string	R
`signature`	A unique string of characters that is calculated by running the alphabetized, concatenated parameters of the call through an HMAC-SHA256 digest. Use this parameter to authenticate genuine PayNearMe callbacks.	string	R
`site_identifier`	The merchant’s unique Site ID.	string	R
`timestamp`	The Unix Epoch time of the call.	string	R
`version`	The version of the API you’re using. This version must match the version associated with your API key pair.	string	R

The submitted validation fields plus the required call parameters listed above are concatenated into name-value pairs and appended into the callback URL for GETs or sorted as name-value pairs in the body for POSTs. The following is a GET sample request:

https://www.merchantdomain.com/order_validation?origin=buynow&amp;signature=4d05ddb426f492fe99999999999&amp;site_customer_email=user%2B8326%40paynearme.com&amp;site_customer_identifier=123488888&amp;site_customer_language=en&amp;site_customer_last_name=Smith&amp;site_identifier=S1575119257&amp;site_order_description=1970&amp;site_order_identifier=123488888&amp;timestamp=1449252553&amp;version=3.0

The following is a POST sample request:

{
  "site_customer_language": "en",
  "site_order_identifier": "12434",
  "site_customer_postal_code": "94062",
  "site_customer_phone": "6085551212",
  "site_identifier": "S1575119257",
  "origin": "buynow",
  "version": "2.0",
  "timestamp": "1635981576",
  "signature": "ea83675b84b0089a90d2d3f84258fcec"
}

Responding to the Callback

Responses to the Order Validation callback echo back the submitted validation parameters along with the approval response. You can also pass back additional parameters to update the order with PayNearMe. These can include the parameters listed below or custom, site-level parameters that the merchant defines (e.g., Closed Date, Current Payoff Balance, Current Impound Balance, etc.).

See the appropriate PayNearMe XML Callback Response Schema for the API Version (e.g., https://www.paynearme.com/api/pnm_xmlschema_v3_0). The schema is validated by PayNearMe, and if the response does not conform, the callback will result in an error. Note the required parameters and namespacing in the schema.

While the schema does not include custom parameters, any configured custom parameter can be returned as part of the Order Validation callback using the appropriate API name that is configured for the custom parameter. Custom parameters are always updated from return values.

The following table displays all the potential parameters (excluding custom parameters) that can be included in the response:

Parameter	Description	Type	Req
`version`	The API version number echoed back from the callback request.	string	R
`approval`	Indicates if the validation data matches the current account data and whether the consumer or agent can proceed with the PayNearMe web flow. Supported options include the following: `go` – Allow the consumer or agent to continue the flow. `approve` – Allow the consumer or agent to continue the flow if he or she confirms additional validation data (e.g., address, citation number, etc.). NOTE: Not available for use with the Revalidation callback. `stop` – Display an error message on the modal or embedded form indicating the validation values do not match current account data.	enum	R
`prompt`	A string message that displays on the modal or embedded form for approve and stop responses. For `approve` responses, use this field to add confirmation verbiage (e.g., Please confirm that your street address is 123 Fake Avenue before proceeding.) For `stop` responses, use this field to add error messaging or to append contact information or additional information to site-level default error messages. This field supports HTML class and style attributes, as well as the following HTML tags: `<table>` `<tbody>` `<tr>` `<td>` `<span>` `<b>` `<div>` `<ul>` `<ol>` `<li>` `<br>`	string	O
`parameters`	A list of parameter values that are either echoed back in the response or are sent as updates to the existing order.	string/obj	O
`site_order_identifier`	An arbitrary string that the merchant site uses to refer to this order. This value can map to any unique identifier in the merchant’s system that identifies the consumer’s account. NOTE: This value is return-only and cannot be updated.	string	O
`site_order_annotation`	Use this parameter to pass back additional information about the order. The values passed in this field are available in receipt text, macros, and the confirmation verbiage that displays in approve response.	string	O
`site_order_notes`	Use this parameter to pass back additional information about the order.	string	O
`site_order_description`	Use this parameter to pass back descriptive text of the order.	string	O
`proxy_site_identifier`	The Site ID of an ISV’s child site.	string	O
`order_amount`	The requested order amount in US Dollars including the decimal point.	string	O
`order_currency`	`USD` NOTE: If amount is included, you must include the currency.	string	O
`order_type`	Supported options include the following: `exact` – Only the exact order amount will be accepted as payment. Any other amount is rejected. `up-to` - The upper limit for all combined payments. The consumer can never pay more than this amount. `any` - The consumer can pay any amount.	enum	O
`order_duration`	The number of days from the order creation that payments will be accepted. If omitted from an order, payments can be accepted forever.	string	O
`order_expiration_date`	The date and time when the order expires in Unix Epoch Standard time. The value in this field is based on the value in the `order_duration` parameter.	string	O
`order_is_standing`	Supported options include the following: `true` – Indicates the order remains open after payment. `false` – Indicates the order closes after payment.	boolean	O
`minimum_payment_amount`	The minimum payment amount in US Dollars including the decimal point.	string	O
`minimum_payment_amount_currency`	`USD` NOTE: If amount is included, you must include the currency.	string	O
`site_order_suspend`	Use `true` to suspend the order so the consumer cannot make a payment against it until it is unsuspended or cancelled.	boolean	O
`site_order_suspend_reason`	A string message that indicates the reason for the order suspension.	string	O
`settlement_friendly_name`	The nickname of the merchant bank account where transaction settlements occur.	string	O
`site_customer_identifier`	An arbitrary string the merchant site uses to refer to the consumer and his/her account. NOTE: This parameter is return-only and cannot be updated.	string	O
`site_customer_name`	The consumer’s full name.	string	O
`site_customer_first_name`	The consumer’s first name.	string	O
`site_customer_last_name`	The consumer’s last name.	string	O
`site_customer_email`	The consumer’s email address.	string	O
`site_customer_phone`	The consumer’s phone number.	string	O
`site_customer_street`	The consumer’s billing street address.	string	O
`site_customer_city`	The consumer’s billing city.	string	O
`site_customer_state`	The consumer’s 2-character billing state abbreviation.	string	O
`site_customer_postal_code`	The consumer’s 5- or 9-digit billing zip code.	string	O
`site_customer_latitude`	The latitudinal coordinate of the consumer’s provided address.	string	O
`site_customer_longitude`	The longitudinal coordinate of the consumer’s provided address.	string	O
`site_customer_sms_ok`	Use `true` to indicate that the consumer has granted permission to receive text messages regarding his or her account.	boolean	O
`site_customer_language`	The preferred language of the consumer. Supported options for this value include the following: `en` – English `sp` – Spanish NOTE: This parameter is return-only and cannot be updated.	enum	O

Code Samples

Go Response Code Sample – Classic OVC

http://www.merchant.com/order_validation?origin=buynow&signature=d0cfa8a2a36c8d8e78193894efbe998d&site_customer_email=mcook%40server.com&site_customer_first_name=Melinda&site_customer_identifier=9416297066&site_customer_language=en&site_customer_last_name=Cook&site_identifier=S2358563001&site_order_identifier=9416297066&timestamp=1458070857&version=3.0

{
  "order_validation_response": {
    "version": "2.0",
    "approval": "go",
    "parameters": {
      "site_order_notes": "some notes",
      "site_order_identifier": "12434",
      "site_customer_phone": "8085551212",
      "site_customer_postal_code": "94062",
      "site_customer_language": "en",
      "site_order_annotation": "Note: 2 weeks past due"
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<t:order_validation_response xmlns:t="http://www.paynearme.com/api/pnm_xmlschema_v3_
0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.paynearme.com/api/pnm_xmlschema_v3_0 pnm_xmlschema_v3_0.xsd" version="3.0">
 <t:approval>go</t:approval>
 <t:prompt></t:prompt>
 <t:parameters>
 <t:site_order_description/>
 <t:site_order_identifier>9416297066</t:site_order_identifier>
 <t:site_customer_identifier>9416297066</t:site_customer_identifier>
 <t:site_customer_first_name>Melinda</t:site_customer_first_name>
 <t:site_customer_last_name>Cook</t:site_customer_last_name>
 <t:site_customer_email>[email protected]</t:site_customer_email>
 <t:site_customer_language>en</t:site_customer_language>
 <t:site_order_annotation/>
 </t:parameters>
</t:order_validation_response>

Go Response Code Sample – Revalidation

https://www.paynearme-sandbox.com/order-validation-service?origin=reval&signature=9ad8fa6049e501832af7c6903455da72bec9e528f057fbd8f861a7d2cdfd85a9&site_customer_identifier=1268888&site_identifier=S4608953896&site_order_identifier=P-999950&timestamp=1644807648&version=3.0

{
  "order_validation_response": {
    "version": "3.0",
    "approval":"go",
    "parameters": {
       "ext_total_balance":"39989.88",
       "ext_loan_payoff_by_5":"", 
       "ext_ytd_interest_rates":"", 
       "ext_loan_payoff_after_5":""
     }
   }
}

<ov:order_validation_response>
version = "3.0"
xsi:schemaLocation = "https://www.paynearme.com/api/pnm_xmlschema_v3_0 pnm_xmlschema_v3_0.xsd"
<ov:approval>
go
</ov:approval>
<ov:parameters>
<ov:ext_total_balance>
39989.88
</ov:ext_total_balance>
<ov:ext_loan_payoff_by_5>
</ov:ext_loan_payoff_by_5>
<ov:ext_ytd_interest_rates>
</ov:ext_ytd_interest_rates>
<ov:ext_loan_payoff_after_5>
</ov:ext_loan_payoff_after_5>
</ov:parameters>
</ov:order_validation_response>

Approve Response Code Sample – Classic OVC

https://www.merchantdomain.com/order_validation?origin=buynow&signature=4d05ddb426f492fe99999999999&site_customer_email=user%40paynearme.com&site_customer_identifier=123488888&site_customer_language=en&site_customer_last_name=Smith&site_identifier=S1575119257&site_order_description=1970&site_order_identifier=123488888&timestamp=1449252553&version=3.0

{
  "order_validation_response": {
    "version": "2.0",
    "approval": "approve",
     "prompt": "Is your name Johnny Smith, and do you live at 123 Fake Street? If so, click 'Confirm' below to Continue.",
    "parameters": {
      "site_order_description": "1970",
      "site_order_identifier": "123488888",
      "site_customer_identifier": "123488888",
      "site_customer_last_name": "Smith",
      "site_customer_email": "[email protected]",
      "site_customer_language": "en",
      "site_order_annotation": "Citation - Speeding"
    }
  }
}

<?xml version="1.0"?>
<t:order_validation_response
xmlns:t="http://www.paynearme.com/api/pnm_xmlschema_v3_0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.paynearme.com/api/pnm_xmlschema_v3_0
pnm_xmlschema_v3_0.xsd" version="3.0">
<t:approval>approve</t:approval>
<t:prompt>"Is your name Johnny Smith, and do you live at 123 Fake Street? If so, click 'Confirm' below to Continue."</t:prompt>
<t:parameters>
<t:site_order_description>1970</t:site_order_description>
 <t:site_order_identifier>123488888</t:site_order_identifier>
 <t:site_customer_identifier>123488888</t:site_customer_identifier>
 <t:site_customer_last_name>Smith</t:site_customer_name>
<t:site_customer_email>[email protected]</t:site_customer_email>
 <t:site_customer_language>en</t:site_customer_language>
 <t:site_order_annotation>optional additional information<t:site_order_annotation/>
</t:parameters>
</t:order_validation_response>

Stop Response Code – Classic OVC

http://www.merchant.com/order_validation?origin=buynow&signature=6f2a083f7142c21d45d179ce39a02f4c&site_customer_email=caley%40paynearme.com&site_customer_first_name=John&site_customer_identifier=4632515064&site_customer_language=en&site_customer_last_name=Smith&site_identifier=S2358563001&site_order_identifier=4632515064&timestamp=1458680082&version=3.0

{
  "order_validation_response": {
    "version": "2.0",
    "approval": "stop",
     "prompt": "Your account cannot be validated. Please go back and verify the information entered is correct before trying again..",
    "parameters": {
      "site_order_identifier": "4632515064",
      "site_customer_identifier": "4632515064",
      "site_customer_first_name": "John",
      "site_customer_last_name": "Smith",
      "site_customer_email": "[email protected]",
      "site_customer_language": "en",
      "site_order_annotation": ""
    }
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<t:order_validation_response xmlns:t="http://www.paynearme.com/api/pnm_xmlschema_v3_
0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.paynearme.com/api/pnm_xmlschema_v3_0 pnm_xmlschema_v3_0.xsd" version="3.0">
 <t:approval>stop</t:approval>
 <t:prompt>"Your account cannot be validated. Please go back and verify the information entered is correct before trying again."</t:prompt>
 <t:parameters>
 <t:site_order_description/>
 <t:site_order_identifier>4632515064</t:site_order_identifier>
 <t:site_customer_identifier>4632515064</t:site_customer_identifier>
 <t:site_customer_first_name>John</t:site_customer_first_name>
 <t:site_customer_last_name>Smith</t:site_customer_last_name>
 <t:site_customer_email>[email protected]</t:site_customer_email>
 <t:site_customer_language>en</t:site_customer_language>
 <t:site_order_annotation/>
 </t:parameters>
</t:order_validation_response>

Stop Response Code – Revalidation Callback

https://www.paynearme-sandbox.com/order-validation-service?origin=reval&signature=40886ce70b10c1dfe0eab33c8fda7866d0afb905fc9938ef88ed211862f7883a&site_customer_identifier=7553105&site_identifier=S4608953896&timestamp=1651260836&version=3.0

{
  "order_validation_response": {
    "version": "3.0",
    "approval":"stop",
    "prompt":"Suspended",
    "parameters": {
       "ext_total_balance":"",
       "ext_past_due_amount":"",
       "ext_loan_payoff_amount_by_5":"", 
       "ext_ytd_interest_rates":"", 
       "ext_loan_payoff_after_5":"",
       "ext_last_statement_balance":""
     }
   }
}

<ov:order_validation_response>
version = "3.0"
xsi:schemaLocation = "https://www.paynearme.com/api/pnm_xmlschema_v3_0 pnm_xmlschema_v3_0.xsd"
<ov:approval>
stop
</ov:approval>
<ov:prompt>
Suspended
</ov:prompt>
<ov:parameters>
<ov:ext_total_balance>
</ov:ext_total_balance>
<ov:ext_past_due_amount>
</ov:ext_past_due_amount>
<ov:ext_loan_payoff_by_5>
</ov:ext_loan_payoff_by_5>
<ov:ext_ytd_interest_rates>
</ov:ext_ytd_interest_rates>
<ov:ext_loan_payoff_after_5>
</ov:ext_loan_payoff_after_5>
<ov:ext_last_statement_balance>
</ov:ext_last_statement_balance>
</ov:parameters>
</ov:order_validation_response>