Integrating with Ezypay’s Direct Debit API Using C#

21 12 2015

As a Tech Support and Pre-Sales representative in Ezypay, one of the most common question that comes from  our clients and 3rd party developers would be on integrating with Ezypay via the Direct Debit API (Application Programming Interface). The direct debit API that is provided by Ezypay is useful as it allows businesses to integrate their existing systems with us and bill their customers as required. With our Direct Debit API, developers would be able to:

  • Create customers for billing with Ezypay (on demand or via pre-created Payment Plans)
  • Create debits so that Ezypay will help you bill your customers
  • Retrieve details on a customer and their debits
  • Get a report on the daily transactions in your Ezypay account

*Please note that this article only works for Ezypay billing customers only and not for iconnect360. The iconnect360 API is almost completed and will be released pretty soon. Please move along this article if you are already signed up with Ezypay and are interested to learn how to integrate with us via our API. 

Before going any further, kindly open up the following document to get the methods available on our API: http://www.ezypay.com/help/Content/Resources/PDF/Ezypay_Direct_Debit_API.pdf

To use our API, you will need to have some understanding on HTTP Methods and REST services. If you don’t really know, the 3 HTTP methods that we have are:

  • GET – to retrieve data
  • POST – to insert new data
  • PUT – to update existing data

Our REST service conforms to web standards, and thus can be called via any software development language ranging from .NET (C#, Visual Basic), PHP, Ruby on Rails, Java and many more. The example I will be showing here is going to be written in C#. By grasping the concepts that I am about to explain below, you should be able to port it over to your development tool pretty easily.

To start using our API, you must first obtain a token from our Secure Site Service at http://hello.ezypay.com. Please ensure that you have authenticated login details from the authorized vendor or get them to create a login for you to use to retrieve the authentication token.

After logging in, head over to the Developer Centre as shown below and get the key from the Token Generation Section under the Authentication Token field:

integrating with Ezypay

integrating with Ezypay

Now that you have the authentication part resolved, we will now see what is required to call our service. First, let’s look at what we should pass to the HTTP header.

The 3 things which are required on the HTTP header when making a request are:

  • The Authorization field (Type would be Basic)
  • The Content-Type field
  • The Accept field

Therefore, when properly composed, your header should look something like below

Authorization: Basic aZj1zkAivrnZiiWpiM71O3hBUAAN6S:a
Content-Type: application/json
Accept: application/json

The authorization username will be the token that you have obtained from our Secure Site at http://hello.ezypay.com. In the above snippet, I have set the password to just ‘a’. No passwords are required and will be validated when calling our APIs so you may enter any character or string that you wish. Please ensure that you also set the Content-Type and Accept as application/json as shown above

When it comes to composing the Body of the HTTP request, please ensure that the content is in JSON format only.

Now I will be showing you how we can make a basic call to the Get Customer Detail API using C#. In the following example, I will be making a call to the Retrieve Single Customer method found in our API documentation.

WebRequest req = WebRequest.Create(@"https://api.ezypay.com/api/v1/customers/11111111-1111-1111-1111-1111"); 
req.Method = "GET"; 
req.Headers["Authorization"] = "Basic " + Convert.ToBase64String(Encoding.Default.GetBytes("aZj1zkAivrnZiiWpiM71O3hBUAAN6S:a")); 
req.ContentType = "application/json"; 
HttpWebResponse resp = req.GetResponse() as HttpWebResponse; 
if (resp.StatusCode != HttpStatusCode.OK) { 
    var message = String.Format("Request failed. Received HTTP {0}", resp.StatusCode); 
    throw new ApplicationException(message); 
} 

var responseValue = string.Empty; // grab the response using (var responseStream = resp.GetResponseStream()) { 
if (responseStream != null) 
    using (var reader = new StreamReader(responseStream)) { 
        responseValue = reader.ReadToEnd(); 
    } 
} 
Console.WriteLine(responseValue);

In the above example, I am attempting to retrieve a customer using HTTP GET with the id, 11111111-1111-1111-1111-1111. I have basically setup the service by passing in the URL to the WebRequest object, and then ensuring that the headers complies to the Authorization as well as the Content-Type. The Accept section needs not require any love when it comes to developing on C# so that could be ignored. Once the service is properly initialized, I am able to recover the details by reading the stream from the HTTPWebResponse object.

Now let’s do something a little more challenging and perform an insert instead. This would require an additional section (which is the HTTP Body) to allow us to send these details to Ezypay for processing. This time, I will be using the Create a debit method found in the API Documentation.

WebRequest req = WebRequest.Create(@"https://api.ezypay.com/api/v1/debits");
req.Method = "POST"; req.Headers["Authorization"] = "Basic " + Convert.ToBase64String(Encoding.Default.GetBytes("aZj1zkAivrnZiiWpiM71O3hBUAAN6S:a")); 
req.ContentType = "application/json"; 
using (var streamWriter = new StreamWriter(req.GetRequestStream())) 
{ 
    string json = "{\"customerId\":\"11111111-1111-1111-1111-1111\", \"amount\":55, \"date\":\"2014-12-29\"}"; 
    streamWriter.Write(json); streamWriter.Flush(); streamWriter.Close(); 
} 
HttpWebResponse resp = req.GetResponse() as HttpWebResponse; 

if (resp.StatusCode != HttpStatusCode.OK) { 
    var message = String.Format("Request failed. Received HTTP {0}", resp.StatusCode); 
    throw new ApplicationException(message); 
} 

var responseValue = string.Empty; // grab the response using (var responseStream = resp.GetResponseStream()) { if (responseStream != null) 
    using (var reader = new StreamReader(responseStream)) { 
        responseValue = reader.ReadToEnd(); 
    } 
} 
Console.WriteLine(responseValue);

From the example above, there are a few differences when compared to the GET example prior to this. The obvious one would be the request method that has now been changed to POST instead of GET. At the same time, there is also a new section which has been added to pass in the JSON body (under the using block of the code). If successful, you should be able to get a HTTPStatusCode.OK and that would mean that the debit was successfully created for the customer onEzypay.

I certainly hope that this post has assisted you in understanding how our API can be integrated with your system. We also have many other exciting tools for developers such as the Web Hook which would help provide developers with notifications and details of triggered events in the organization such as customers being added and failed payments. As mentioned at the start of this article, we are also going to release an API for iconnect360 which would help developers to integrate iconnect360 to their existing systems as well.

If you have further questions, please feel free to e-mail me. Have a great day all!


Actions

Information

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s




%d bloggers like this: