Create POLiLink API

It is possible to create POLi Links through automation by integration with the POLi Link API.

When creating POLi Links in this way, there are a few characteristics to be aware of:

Type Characteristic
Validation When creating POLi Links via Console, the user interface covers all validation and helps the user identify errors in their data entry.
Through automation, you will be required to ensure that all data types and values fall within expected ranges and formats
Extended Features When creating POLi Links via Console, the user interface will only show extended features that the merchant has enabled. When setting features like partial payment and due date through POLi Link API, make sure these features are enabled by the merchant
Feature Combinations There are constraints which must be met when defining a POLi Link. These include requirements for the type of POLi Link and restrictions for extended features.

If care is taken with the above considerations, back-end validation will succeed and a POLi Link will be created.

Failure will return an error code and message.

Create POLi Link Request

Name Description Type & length/usage Mandatory Examples
LinkType Specifies the type of POLi Link to create Integer No 0 = Simple
1 = Variable
2 = Discounted
Amount Specifies the amount the customer pays. Must be zero for Variable LinkType.
Must be less than the merchant's individual transaction limit that is set in the console account.		 Decimal Yes 10.00
CurrencyCode The currency doe of the transaction String
Usually 3 characters		 No NZD
MerchantReference The merchant's reference for the new POLi Link. <100 characters Yes ORDER123ABC
MerchantReferenceFormat Used to specify a reconciliation format. Reconciliation information for more details String No Value between 1 and 4
MerchantData Merchant specific information for this POLi Link String No Maximum of 2000 characters
ConfirmationEmail Specifies if the merchant will receive an email when a POLi Link transaction is completed Boolean No true or false
AllowCustomerReference Specifies if the customer can enter information that uniquely identifies the customer or the payment during the transaction Boolean No true or false
LinkExpiry Specifies a future date where the POLi Link can no longer be used DateTime as String No Must be a date later than today's date. Format is as: “2023-12-24 16:00:00+11”
MultiPayment Specifies if the POLi Link can be used time-and-time again to make payments Boolean No true or false
DueDate Specifies a future date that a payment can be scheduled for (future payments) Date as String No 2023-05-24
AllowPartialPayment Specifies if the customer can pay the full amount over multiple transactions Boolean No true or false
AllowOverPayment Specifies if the customer can pay more than the amount specified Boolean No true or false
Schedule A pipe-delimited set of payment rules that specify a percentage discount if the customer pays before the specified date Supports multiple discount clauses String No 2023-03-28=14.00 | 2023-04-29=12.00

The example above means a 14% discount would be applied if it is paid on or before 28/3/23. After 28/3/23, the discount on offer would be only 12%.
ViaEmail Specifies if the customer receives an email, from POLi, on behalf of the merchant, outlining the details of the POLi Link payment RecipientName and RecipientEmail must be provided Boolean No true or false
RecipientName The display name of the customer receiving the POLiLink email String Yes true or false
RecipientEmail The email address of the recipient Email address format must be valid String Yes my.customer@customers.com

Create POLiLink Response

A string containing the short URL of the POLi Link payment. OR

A string containing a simple error message due to a failure in creating the POLi Link

Create POLi Link Example

This code example will show you how to generate a POLi Link.

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

PHP

$json_builder = '{
  "LinkType":"0",
  "Amount":"2.5",
  "CurrencyCode":"NZD",
  "MerchantData":"CustomerRef12345",
  "MerchantReference":"CustomerRef12345",
  "ConfirmationEmail":"false",
  "AllowCustomerReference":"false",
  "ViaEmail":"false",
  "RecipientName":"false",
  "LinkExpiry":"2023-10-24 16:00:00+11",
  "RecipientEmail":"false"
}';

 $auth = base64_encode("SS64xxxxx:AuthCode123"); //ENTER YOUR CREDENTIALS
 $header = array();
 $header[] = 'Content-Type: application/json';
 $header[] = 'Authorization: Basic '.$auth;

 $ch = curl_init("https://poliapi.apac.paywithpoli.com/api/POLiLink/Create");
 //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);

 print_r($json);

C Sharp

var json = System.Text.Encoding.UTF8.GetBytes(@"{
    'LinkType':'0',
    'Amount':'2.5',
    'CurrencyCode':'NZD',
    'MerchantData':'CustomerRef12345',
    'MerchantReference':'CustomerRef12345',
    'ConfirmationEmail':'false',
    'AllowCustomerReference':'false',
    'ViaEmail':'false',
    'RecipientName':'false',
    'LinkExpiry':'2023-10-24 16:00:00+11',
    'RecipientEmail':'false'
}");
var auth = System.Convert.ToBase64String(System.Text.Encoding.UTF8.GetBytes("SS64xxxxx:AuthCode12345")); //ENTER YOUR CREDENTIALS

var myRequest = System.Net.WebRequest.Create("https://poliapi.apac.paywithpoli.com/api/POLiLink/Create");
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();

Create POLi Link Response Example

https://poli.to/wsWnx