The POLi Nudge


The POLi nudge ensures that the merchant receives a real-time notification that a transaction has reached a terminal state.

If a customer closes their web browser before returning to the merchant's website but after completing the payment, this is how their transaction gets credited and is how the merchant's system is updated.


POLi API Workflow



How do I implement the nudge?


Merchants can specify that the POLi nudge be sent to them by specifying a notification URL in their Initiate transaction request.

POLi will send a HTTP POST to the merchant’s specified Notification URL upon the transaction reaching a terminal state. The data contains the token which is URL-encoded and is posted inside the Request.Form collection in a field marked as Token. The Notification URL must be publicly accessible.

The merchant can then call the GETTransaction API with the token to check the status of the transaction, and update the transaction to credited.

Note: The nudge is only a notification that a transaction has reached an end (terminal) state. This is not a notification indicating that funds will be received. The information you receive in your GETTransaction call should update your system in the correct way. Daily reconciliation should then be performed to ensure funds are received before issuing the good/service purchased.

The transaction process ends with one of the following terminal statuses:

Completed A successful payment, indicating funds are to be credited to the merchant
TimedOut The customer did not complete the payment in the allotted time
Failed The customer was unable to complete the transaction
ReceiptUnverified POLi is unable to determine if the transaction was successful
Cancelled The transaction was cancelled by the user
Important: For security reasons, the POLi Nudge contains no detailed information about the transaction and alone cannot be used as confirmation that a payment was successful; it only indicates that the transaction process has now ended.

Using HTTPS?


In order to maintain secure communications, Merchants must configure their Nudge endpoint to comply with industry standards on encryption for web servers using TLS.

Webservers must be configured to use a minimum of TLS version 1.2. POLi currently requires TLS 1.2 communication to be enabled for Nudge functionality to operate correctly. TLS versions 1.1, 1.0 and SSL versions 2 and 3 are considered unsafe and/or vulnerable.

The following recommended cipher suites are supported by the POLi Nudge service:

  • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384(P384)
  • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256(P256, P384)
  • TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
  • TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

More information and additional detail on a secure TLS configuration can be found at the following publications:


Nudge Example


Caution: The POLi Nudge can only be sent to port 80 or 443.
                
                    #### << Headers >> ####
                    Connection: Keep-Alive
                    Expect: 100-continue
                    Host: your.url.com
                    Content-Length: 40
                    Content-Type: application/x-www-form-urlencoded
                    #### << Content >> ####
                    Token=EIgVQw2%2bvHofiynsAW41X5r4AhqbfpL2