What is the POLi Nudge?

The nudge is POLi telling the merchant system that a payment is complete.

The nudge ensures that the merchant receives confirmation of transaction completion. If the customer closes the browser before returning to the merchant site but after completing payment, this is how their transaction gets credited and updated in the merchant system.

POLi Nudge Details

The POLi™ Nudge is an HTTP POST sent to the nominated notification URL of the merchant. The form data making up the HTTP POST contains the token (in a field marked as ‘Token’), for a particular transaction which has reached a terminal state.
For security reasons the model used is one where the nudge contains no detailed information about the transaction, other than that it has finished. The nudge is used as a notification to the merchant that the transaction is complete and has reached a terminal status. You can now call GetTransaction Example to obtain the final status of the transaction. The POLi™ Nudge alone cannot be used as confirmation that a payment was successful; it only indicates that the transaction process has now ended and finished with one of the following statuses:


A successful payment, indicating funds are to be credited to the merchant.
The customer did not complete the payment in the allotted time.
The customer was unable to complete the transaction.
POLi™ is unable to determine if the transaction was successful.
The transaction was cancelled by the user.

An example Nudge:

  • Content
Loading ...
#### << Headers >> ####
Connection: Keep-Alive
Expect: 100-continue
Host: your.url.com
Content-Length: 40
Content-Type: application/x-www-form-urlencoded

#### << Content >> ####

Note: The POLi™ Nudge can only be sent to the default port 80 or the secured port 443.

Merchants can specify that a nudge be sent to them by specifying a default notification URL in the POLi™ console, or specifying a notification URL when they initiate a transaction. If a notification URL is specified when a transaction is initiated, it will override the default notification URL specified in the POLi™ Console.

The ‘Nudge Notification URL’ above allows POLi™ to send a nudge for transaction in terminal state. With the above setting, upon the transaction reaching a terminal state, POLi™ will do a POST to the merchant’s configured URL. The token data is URL-encoded and posted inside the Request.Form collection. The ‘Nudge Notification URL’ must be publicly accessible and in this format.

The merchant can then call GetTransaction with the token to check the status of the transaction, and update the transaction to credited. Note, before crediting, you should check if it has already been credited to ensure that you only credit a transaction once.

Merchants that are unable to process the Nudge can wait until the customer is redirected to the successful or unsuccessful URL before they enquire the outcome of the transaction. The downside of this approach is that it is possible for a user to close their internet browser or have some other issue after completing the transaction in POLi™ before they are redirected back to the customer site. In this scenario, the user will never load the merchant’s successful or unsuccessful URL and the merchant will not know when a transaction has completed or failed.
POLi Payments highly recommends that merchants adopt Nudge processing and handling where possible to ensure all transactions get finalised correctly.

For an example Nudge page integration with a GetTransaction Request, click here.

Once you have completed the Nudge, there are other integration steps required. Return to the Integration Overview to understand and complete the remaining integration work.

nudge.txt · Last modified: 2017/10/24 10:03 (external edit)