Basic Tutorial
This is a basic tutorial, designed to help you get started with the ICEPAY API.
Let us start by initiating a credit card payment of US$ 1.99 that will be handled by VISA. The user interface language will be in English.
We will be using a fictional API key which consists of the ID 10000 and secret code ABcdEFgHIJklmNOPQrSTUvwXyZ.
The following code will illustrate how to initiate a payment and redirect the end-user to the credit card payment screen.
PHP: default.php
<?php
if ( $_SERVER['REQUEST_METHOD'] == "POST" )
{
require_once( "icepay.php" );
$cc = new ICEPAY_CC( 10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ" );
$url = $cc->Pay( "VISA", "EN", "USD", 199 );
header( "location: " . $url );
}
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>ICEPAY Demo: Basic Tutorial</title>
</head>
<body>
<form action="default.php" method="post">
<h1>ICEPAY Demo: Basic Tutorial</h1>
<input type="submit" value="Initialize payment" />
</form>
</body>
</html>
C#: default.aspx
<%@ Page Language="C#" %>
<script runat="server">
protected void Page_Load(object sender, EventArgs e)
{
if (Page.IsPostBack)
{
ICEPAY.ICEPAY_CC ice = new ICEPAY.ICEPAY_CC(10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ");
Response.Redirect(ice.Pay("VISA", "EN", "USD", 199, "Demo payment"));
}
}
</script>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>ICEPAY Demo: Basic Tutorial</title>
</head>
<body>
<form id="form1" runat="server">
<h1>ICEPAY Demo: Basic Tutorial</h1>
<asp:Button ID="Button1" runat="server" Text="Initialize payment" />
</form>
</body>
</html>
VB.NET: default.aspx
<%@ Page Language="vb" %>
<script runat="server">
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs)
If Page.IsPostBack Then
Dim ice As New ICEPAY.ICEPAY_CC(10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ")
Response.Redirect(ice.Pay("VISA", "EN", "EUR", 199, "Demo payment"))
End If
End Sub
</script>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>ICEPAY Demo: Basic Tutorial</title>
</head>
<body>
<form id="form1" runat="server">
<h1>ICEPAY Demo: Basic Tutorial</h1>
<asp:Button id="Button1" runat="server" Text="Initialize payment" />
</form>
</body>
</html>
As you may have noticed, the amount needs to be defined in cents.
Successful payments
After end-users complete the credit card payment, they will be redirected to a so called Success URL. This is a web page on your website where you should tell your end-users that the payment has been handled successfully. You can set the Success URL in your ICEPAY account.
The following code explains how this works. Calling the OnSuccess method returns True if it is an authentic call from ICEPAY. If so, then you should display your "Thank You" message.
PHP: ok.php
<?php
require_once( "icepay.php" );
$icepay = new ICEPAY( 10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ" );
if ( !$icepay->OnSuccess() ) die();
$data = $icepay->GetData();
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>OK</title>
</head>
<body>
<?php if ( $data->status == "OK" ): ?>
<h1>Thank You! You have successfully completed the payment!</h1>
<?php endif ?>
</body>
</html>
C#: ok.aspx
<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
protected void Page_Load(object sender, EventArgs e)
{
ICEPAY.ICEPAY ice = new ICEPAY.ICEPAY(10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ");
if (ice.OnSuccess() && ice.GetData().status == "OK")
pnlThankYou.Visible = true;
}
</script>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
<title>OK</title>
</head>
<body>
<form id="form1" runat="server">
<asp:Panel runat="server" Visible="false" ID="pnlThankYou">
<h1>Thank You, your order is complete</h1>
</asp:Panel>
</form>
</body>
</html>
VB.NET: ok.aspx
<%@ Page Language="vb" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs)
Dim ice As New ICEPAY.ICEPAY(10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ")
If ice.OnSuccess AndAlso ice.GetData().status = "OK" Then
pnlThankYou.Visible = True
End If
End Sub
</script>
<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
<title>OK</title>
</head>
<body>
<form id="form1" runat="server">
<asp:Panel runat="server" Visible="false" ID="pnlThankYou">
<h1>Thank You, your order is complete</h1>
</asp:Panel>
</form>
</body>
</html>
Cancelled/failed payments
Similarly, if a payment did not succeed then end-users will be redirected to a so called Error URL. This is a web page on your website where you will tell your end-users that something went wrong. You can set the Error URL in your ICEPAY account.
PHP: error.php
<?php
require_once( "icepay.php" );
$icepay = new ICEPAY( 10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ" );
$data = $icepay->GetData();
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Error</title>
</head>
<body>
<h1>Oops, some error occured</h1>
<p>Error description: <?php echo $data->statusCode ?></p>
</body>
</html>
C#: error.aspx
<%@ Page Language="C#" %>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<script runat="server">
protected ICEPAY.ICEPAY ice;
protected void Page_Load(object sender, EventArgs e)
{
ICEPAY.ICEPAY ice = new ICEPAY.ICEPAY(10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ");
}
</script>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Error</title>
</head>
<body>
<h1>Oops, some error occured</h1>
<p>Error description: <%=ice.GetData().statusCode%></p>
</body>
</html>
VB.NET: error.aspx
<%@ Page Language="vb" %>
<script runat="server">
Protected ice As ICEPAY.ICEPAY
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs)
ice = New ICEPAY.ICEPAY(10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ")
End Sub
</script>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Error</title>
</head>
<body>
<h1>Oops, some error occured</h1>
<p>Error description: <%=ice.GetData().statusCode%></p>
</body>
</html>
Postback
If your website must act upon a payment status change, e.g. send an e-ticket to your customer if the payment is completed, or update your database, then you must put this business logic in the Postback script. You must never abuse the Success URL or Error URL for this purpose. The latter two are for presentation purposes only!
Many things can happen to a credit card payment. The end-user may initiate a charge back via the credit card company, the payment may be cancelled by the end-user, etc. You should take a look at the list of possible postbacks.
Your postback script must handle the different types of postback properly. The following code will illustrate this.
PHP: postback.php
<?php
require_once( "icepay.php" );
$icepay = new ICEPAY( 10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ" );
if ( $icepay->OnPostback() )
{
$data = $icepay->GetPostback();
switch ( strtoupper($data->status) )
{
case "OK": // Successful payment
break;
case "OPEN": // Payment is not yet completed
break;
case "ERR": // Error happened
break;
case "REFUND": // Merchant did a refund
break;
case "CBACK": // Charge back by end-user
break;
}
}
?>
C#: postback.aspx
<%@ Page Language="C#" %>
<script runat="server">
protected void Page_Load(object sender, EventArgs e)
{
ICEPAY.ICEPAY ice = new ICEPAY.ICEPAY(10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ");
if (ice.OnPostBack())
{
ICEPAY.ICEPAY.Postback data = ice.GetPostback();
switch (data.status.ToUpper())
{
case "OK": // Successful payment
break;
case "OPEN": // Payment is not yet completed
break;
case "ERR": // Error happened
break;
case "REFUND": // Merchant did a refund
break;
case "CBACK": // Charge back by end-user
break;
}
}
}
</script>
VB.NET: postback.aspx
<%@ Page Language="vb" %>
<script runat="server">
Protected Sub Page_Load(ByVal sender As Object, ByVal e As System.EventArgs)
Dim ice As New ICEPAY.ICEPAY(10000, "ABcdEFgHIJklmNOPQrSTUvwXyZ")
If ice.OnPostBack Then
Dim data As ICEPAY.ICEPAY.Postback = ice.GetPostback()
Select Case data.status.ToUpper()
Case "OK" ' Successful payment
Case "OPEN" ' Payment is not yet completed
Case "ERR" ' Error happened
Case "REFUND" ' Merchant did a refund
Case "CBACK" ' Charge back by end-user
End Select
End If
End Sub
</script>