InitiateTransaction

The InitiateTransaction web service is used to initiate a POLi™ transaction with details specified by the merchant. POLi™ will authenticate the requesting merchant and validate the data passed in the request. If successful, a POLi ID, transaction token and URL will be returned in the response.
The POLi ID is a unique 12-digits reference to a POLi™ transaction. This TRN is used in the reference field of the user bank transfer payment and should be used by the merchant to reconcile the payment. The transaction token is an encrypted form of the TRN. For security purposes, the token should be used when enquiring about the transaction in subsequent web service calls.
The URL returned by the InitiateTransaction web service is the URL that a merchant should redirect the customer to, in order to continue with their POLi™ payment. It is the URL of the POLi™ page where the customer can select the bank that they want to use to make the payment.

For an example of how to implement this functionality, click here.

For an overview of how POLi works, click here.

API Endpoint


https://poliapi.apac.paywithpoli.com/api/v2/Transaction/Initiate


This API endpoint is a “POST” method.


Merchant Return URLs

Merchants can specify different URLs for the users to be redirected to when a transaction is finished. There are 4 different URLs that can be specified:

  • SuccessURL,
  • FailureURL,
  • CancellationURL, and
  • MerchantHomepageURL.
SuccessURL

A user is redirected back to the SuccessURL if the user has completed a POLi™ payment successfully, and POLi™ has successfully processed the bank receipt page. POLi™ will append the transaction token as a query string parameter called ‘token’ in the SuccessURL specified. For example,

  • If the specified URL has no query string parameter:
http://mywebsite.com/POLi/Receipt.aspx


the user will be redirected to the following URL:

http://mywebsite.com/POLi/Receipt.aspx?token=[transaction_token]


  • If the specified URL has a single parameter:
http://mywebsite.com/POLi/Receipt.aspx?param1=value1


the user will be redirected to the following URL:

http://mywebsite.com/POLi/Receipt.aspx?param1=value1&token=[transaction_token]


  • If the specified URL has multiple parameters:
http://mywebsite.com/POLi/Receipt.aspx?param1=value1&param2=value2


the user will be redirected to the following URL

http://mywebsite.com/POLi/Receipt.aspx?param1=value1&param2=value2&token=[transaction_token]


FailureURL

A user is redirected back to the FailureURL if the user has encountered an error during a POLi™ payment and is unable to proceed. POLi™ will append the transaction token as a query string parameter called ‘token’ in the FailureURL specified. For example,

  • If the specified URL has no query string parameter:
http://mywebsite.com/POLi/Failure.aspx


The user will be redirected to the following URL:

http://mywebsite.com/POLi/Failure.aspx?token=[transaction_token]


  • If the specified URL has a single parameter:
http://mywebsite.com/POLi/Failure.aspx?param1=value1


The user will be redirected to the following URL:

http://mywebsite.com/POLi/Failure.aspx?param1=value1&token=[transaction_token]


  • If the specified URL has multiple parameters:
http://mywebsite.com/POLi/Failure.aspx?param1=value1&param2=value2


the user will be redirected to the following URL

http://mywebsite.com/POLi/Failure.aspx?param1=value1&param2=value2&token=[transaction_token]


CancellationURL and MerchantHomepageURL

A user is redirected back to the CancellationURL or MerchantHomepageURL if the user has the ability to proceed with the transaction but chooses not to. There are 5 different scenarios where this can occur:

  • User chooses to return to the merchant on POLi™ bank selection page,
  • User chooses to cancel the payment,
  • User closes their Internet Banking before confirming the transaction,
  • User does not have the pre-requisite installed on their machine and chooses to return to the merchant, or
  • User does not have javascript enabled on their browser and chooses to return to the merchant (instead of enabling it and proceeding with the transaction).

The MerchantHomepage URL will be used if the CancellationURL is not supplied. The MerchantHomepageURL and CancellationURL will be used as is, that is, POLi™ will not append the transaction token to the URLs specified.

InitiateTransaction Request


To authenticate your request, you must use Basic Authentication. Click Here to find out more.

NameType & Length / UsageExamples
AmountDecimal number10.50
CurrencyCodeString/Text. Usually 3 charactersAUD
MerchantReferenceString - Unique reference for the transaction, specified by the merchant. 100 characters max. Has character constraintsORDER123ABC
MerchantReferenceFormatString - Used for NZ reconciliation. 50 characters max.
MerchantDataMerchant specified information that is carried along with the transaction for the merchant’s internal use, post-transaction(See GetTransaction). 2000 characters
MerchantHomepageURLDisplayed on the POLi Landing page. 1000 characters max.
http://my.online.shop
SuccessURLRedirect to this location if the transaction succeeds(1000 characters max). Appends transaction token as query parameter automatically
http://my.online.shop/successfullPayment.aspx
FailureURLRedirect to this location if the transaction fails(1000 characters max). Appends transaction token as query parameter automatically
http://my.online.shop/FailedPayment.aspx
CancellationURLRedirect to this location if the customer cancels the transaction(1000 characters max). Appends transaction token as query parameter automatically
http://my.online.shop/CancelledPayment.aspx
NotificationURLSend a ‘Nudge’ to this location when the transaction reaches a terminal state(1000 characters max)
http://my.online.shop/nudge.aspx
TimeoutNumber of seconds before transaction times out900
SelectedFICodeString representing the FI the customer will pay with. (Optional)
CompanyCodeFor future use. Specification to be defined

InitiateTransaction Response

FieldDescriptionData TypePossible Values
Success A boolean value indication success Boolean true or false
TransactionRefNo The POLi ID associated with the transaction. String A unique 12 digit reference to a POLi™ transaction.
NavigateURL The Navigate URL is the location that the user should be redirected to, in order to proceed with the POLi™ transaction. String A valid URL for the POLi™ landing page appended with a query string containing the transaction token. Example:
Australia / New Zealand:
https://txn.apac.paywithpoli.com/?token=[token]
ErrorCode An error code, if there was one (O if none) Integer See Error Codes
ErrorMessage A string containing details about the error String

Invalid Special Characters

For Australian Merchants

The allowable characters for the merchant reference field are: Alphanumeric characters, spaces, and the following special characters: @-_=:?./

For New Zealand Merchants

The only accepted characters in the merchant reference field are Alphanumeric characters and spaces. The following characters will be accepted in the merchant reference field, but replaced with a space when entered into the bank field: @-_=:?./

All other symbols will result in an initiate transaction error

Error Codes used by InitiateTransaction

Error CodeDescription
14050A transaction-specific error has occurred
14053The amount specified exceeds the individual transaction limit set by the merchant
14054The amount specified will cause the daily transaction limit to be exceeded
14055General failure to initiate a transaction
14056Error in merchant-defined data
14057One or more values specified have failed a validation check
14058The monetary amount specified is invalid
14059A URL provided for one or more fields was not formatted correctly
14060The currency code supplied is not supported by POLi or the specific merchant
14061The MerchantReference field contains invalid characters
14062One or more fields that are mandatory did not have values specified
14099An unexpected error has occurred within transaction functionality
initiate.txt · Last modified: 2017/05/16 16:04 (external edit)