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


apiflow1

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 Reconcilliation
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 Example

This code example show you how to use the InitiateTransaction API.

Visit API Introduction to generate code snippets of your preferred language.

PHP

$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"]);

C

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();

JAVA

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"
}