InitiateTransaction API


The InitiateTransaction web service is used to initiate a POLi transaction with details specified by the merchant. POLi will authenticate the merchant's request and validate the data passed.


POLi API Workflow



InitiateTransaction Request


Name Description Type & Length/ Usage JSON Data Type Mandatory Examples
Amount The transaction amount the customer should be charged Decimal. Value upto 2 decimal places. Number Yes 10.50
CurrencyCode The currency of the transaction

Note:This must match the currency of your merchant account

String/Text. Usually 3 characters String Yes AUD
MerchantReference Unique reference specified by the merchant for the transaction String - 100 characters max. Alphanumeric characters and spaces

Australian Merchants - Special characters: @-_=:?./ are allowed
New Zealand Merchants - Special characters: @-_=:?./ will be accepted, but replaced with a space when entered into the bank field

String Yes ORDER123ABC
MerchantReferenceFormat Used to specify a New Zealand reconciliation format. See NZReconciliation for more details String - Used for NZ reconciliation. 50 characters max String No See NZ reconciliation
MerchantData This field is for the merchant transaction reference Merchant specified information that is carried along with the transaction for the merchant’s internal use, post-transaction. 2000 characters String No See GETTransaction
MerchantHomepageURL The complete merchant URL is displayed in the merchant information on the POLi landing page Displayed on the POLi Landing page. 1000 characters max String Yes http://my.online.shop
SuccessURL The complete URL to redirect the customer to if the transaction is successful Adds transaction token as query parameter if no query string in the URL. If specified URL has single/multiple query strings then POLi will append transaction token to the query parameter automatically.1000 characters max String Yes Specified URL: http://my.online.shop/successfullPayment.aspx ReturnedURL: http://my.online.shop/successfullPayment.aspx?token=[transactiontoken]
FailureURL The complete URL to redirect the customer to if the transaction is not successful Adds transaction token as query parameter if no query string in the URL. If specified URL has single/multiple query strings then POLi will append transaction token to the query parameter automatically.1000 characters max String No Specified URL: http://my.online.shop/FailedPayment.aspx ReturnedURL: http://my.online.shop/FailedPayment.aspx?token=[transactiontoken]
CancellationURL The complete URL used to redirect the customer to if they cancel the transaction. Adds transaction token as query parameter if no query string in the URL. If specified URL has single/multiple query strings then POLi will append transaction token to the query parameter automatically.1000 characters max String No Specified URL: http://my.online.shop/CancelledPayment.aspx ReturnedURL: http://my.online.shop/CancelledPayment.aspx?token=[transactiontoken]
NotificationURL The complete URL where POLi will deliver the Nudge POST to POLi will POST a ‘Nudge’ to this location when the transaction reaches a terminal state.
Ensure your endpoint supports HTTP POST.
1000 characters max
String No http://my.online.shop/nudge.aspx
Timeout The timeout for the transaction in seconds, which defaults to 900 (15 minutes) Number of seconds before transaction times out Number No 900
SelectedFICode Used for pre-selecting banks in order to skip the POLi Landing page String representing the FI the customer will pay with String No

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 2 different scenarios where this can occur:

  • User chooses to return to the merchant on POLi bank selection page,
  • User chooses to cancel the payment,

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 Response


Name Description Type & Length/ Usage JSON Data Type Examples
Success A value indicating success Boolean Boolean true or false
TransactionRefNo The POLi ID is a reference to a POLi transaction.This is used in the reference field of the user bank transfer payment and should be used by the merchant to reconcile the payment. String 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. It contains a transaction token which is an encrypted form of the TransactionRefNo. String 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 Number See Error Codes
ErrorMessage A string containing details about the error String String See Error Codes


InitiateTransaction Example


This code example show you how to use the InitiateTransaction API.
Download our API collection to generate code snippets of your preferred language

                            
$json_builder = '{
    "Amount":"1.2",
    "CurrencyCode":"AUD",
    "MerchantReference":"CustomerRef12345",
    "MerchantHomepageURL":"https://www.mycompany.com",
    "SuccessURL":"https://www.mycompany.com/Success",
    "FailureURL":"https://www.mycompany.com/Failure",
    "CancellationURL":"https://www.mycompany.com/Cancelled",
    "NotificationURL":"https://www.mycompany.com/nudge" 
}';
 
$auth = base64_encode('S61xxxxx:AuthCode123');
$header = array();
$header[] = 'Content-Type: application/json';
$header[] = 'Authorization: Basic '.$auth;
 
$ch = curl_init("https://poliapi.apac.paywithpoli.com/api/v2/Transaction/Initiate");
//See the cURL documentation for more information: http://curl.haxx.se/docs/sslcerts.html
//We recommend using this bundle: https://raw.githubusercontent.com/bagder/ca-bundle/master/ca-bundle.crt
curl_setopt( $ch, CURLOPT_CAINFO, "ca-bundle.crt");
curl_setopt( $ch, CURLOPT_SSLVERSION, CURL_SSLVERSION_TLSv1_2);
curl_setopt( $ch, CURLOPT_HTTPHEADER, $header);
curl_setopt( $ch, CURLOPT_HEADER, 0);
curl_setopt( $ch, CURLOPT_POST, 1);
curl_setopt( $ch, CURLOPT_POSTFIELDS, $json_builder);
curl_setopt( $ch, CURLOPT_FOLLOWLOCATION, 0);
curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1);
$response = curl_exec( $ch );
curl_close ($ch);
 
$json = json_decode($response, true);
 
header('Location: '.$json["NavigateURL"]);
                        
                            
var json = System.Text.Encoding.UTF8.GetBytes(@"{
    'Amount':'1.2',
    'CurrencyCode':'AUD',
    'MerchantReference':'CustomerRef12345',
    'MerchantHomepageURL':'https://www.mycompany.com',
    'SuccessURL':'https://www.mycompany.com/Success',
    'FailureURL':'https://www.mycompany.com/Failure',
    'CancellationURL':'https://www.mycompany.com/Cancelled',
    'NotificationURL':'https://www.mycompany.com/nudge'
}");
var auth = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("S61xxxxx:AuthCode12345"));
 
var myRequest = System.Net.WebRequest.Create("https://poliapi.apac.paywithpoli.com/api/v2/Transaction/Initiate");
myRequest.Method = "POST";
myRequest.ContentType = "application/json";
myRequest.Headers.Add("Authorization", "Basic "+auth);
myRequest.ContentLength = json.Length;
 
System.IO.Stream dataStream = myRequest.GetRequestStream();
dataStream.Write(json, 0, json.Length);
dataStream.Close();
 
var response = (System.Net.HttpWebResponse)myRequest.GetResponse();
var data = response.GetResponseStream();
var streamRead = new StreamReader(data);
Char[] readBuff = new Char[response.ContentLength];
int count = streamRead.Read(readBuff, 0, (int)response.ContentLength);
while (count > 0)
{
    var outputData = new String(readBuff, 0, count);
    Console.Write(outputData);
    count = streamRead.Read(readBuff, 0, (int)response.ContentLength);
    dynamic latest = Newtonsoft.Json.JsonConvert.DeserializeObject(outputData);
    Response.Redirect(latest["NavigateURL"].Value);
}
response.Close();
data.Close();
streamRead.Close();
                            
                        
                            
import java.io.*;
import java.net.*;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.util.Base64;


public class POLiTransaction 
{ 
    public static void main(String[] args) {
        SendPoliInitiateRequest();
    }

    
    public static void SendPoliInitiateRequest()
    {
    	try{
    		
            String query = "https://poliapi.apac.paywithpoli.com/api/v2/Transaction/Initiate";


//Use Your Own JSON builder (example like GSON), Or make sure this string is in one line
            String json = "{ 'Amount':'1.2',
                             'CurrencyCode':'AUD',
                             'MerchantReference':'CustomerRef12345',
                             'MerchantHomepageURL':'https://www.mycompany.com',
                              'SuccessURL':'https://www.mycompany.com/Success', 
                              'FailureURL':'https://www.mycompany.com/Failure',
                              'CancellationURL':'https://www.mycompany.com/Cancelled',
                              'NotificationURL':'https://www.mycompany.com/nudge'}"; 	

               
            URL url = new URL(query);
            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setConnectTimeout(5000);
            
            String accesscode  = "S61xxxxx:AuthCode12345"; //ADD YOUR CREDENTIALS 
            String encodedAuthString = Base64.getEncoder().encodeToString(accesscode.getBytes());
            
            conn.setRequestProperty("authorization", "Basic " + encodedAuthString); 
            conn.setRequestProperty("Content-Type", "application/json; charset=UTF-8");
            
            conn.setDoOutput(true);
            conn.setDoInput(true);
            conn.setRequestMethod("POST");

            OutputStream os = conn.getOutputStream();
            os.write(json.getBytes("UTF-8"));
            os.close();

            // read the response
           InputStream in = new BufferedInputStream(conn.getInputStream());
           
           byte[] contents = new byte[1024];
           int bytesRead = 0;
           
           String poliResponse = ""; 
           
            while((bytesRead = in.read(contents)) != -1)
            { 
              poliResponse += new String(contents, 0, bytesRead);              
            }
            
            System.out.print(poliResponse);//Process the JSON Response and Redirect to NavigateURL
    
           in.close();
           conn.disconnect();
     
        }
        catch(IOException ex)
        {
        	System.out.print(ex);
        }     	
    }   
} 
                                

InitiateTransaction Response Example



{
    "Success": true,
    "NavigateURL": "https://txn.apac.paywithpoli.com/?Token=uo3K8YA7vCojXjA1yuQ3txqX4s26gQSh",
    "ErrorCode": 0,
    "ErrorMessage": null,
    "TransactionRefNo": "996117408041"
}