DonorPerfect is a well known platform to accept donations and payments. The site also offer API so we can integrate their services to our site. In this article we will be seeing how to use DonorPerfect API with PHP to get data and communicate with their site.

For this purpose they have offered a very detailed PDF document which talks about how to connect to their server. You can find it here.

What the documentation does not show is examples on how to make connection using various server languages. Recently I had worked on a project http://waamart.woodstockart.org/ and this project extensively used the API. I would like to share my knowledge on how to connect to DonorPerfect API using PHP.

Get the API key

At the time of writing this post to get the API key according to the documentation, you need to contact the customer support. Upon request they will mail the API key to the registered email id.

Since I cannot share my API key lets imagine the following string is the API key.

Construct the URL

DonorPerfect API follows the GET request URLs to access the server. This means that after constructing the URL if you paste it on the browser then you can get an XML result. The following URL is only a GET type because you can only ‘get’ information and not ‘post’. If the URL is able to post information then it will be called as POST Url.

The first line is the ID of the donor whose information you want to request from the server. The ID of the donor can be requested from your client.

The second line is the URL that we will be passing. Let’s break it down.

https://www.donorperfect.net/prod/xmlrequest.asp? – Is the API request URL.

apikey=".$apikey." – Here, from the previous code we will be passing in the API key

&action=Select * from dp where donor_id = '".$donorId."'" – Here the action is an very common SQL query. In this case the SQL query is requesting to get all information denoted by '*' from the table 'dp' with a condition. And that condition is to search for donor_id and provide all information related to it.

$newUrl = str_replace(' ', '%20', $curDonorIDUrl); – If you copy the above url after replacing the$apikey  and paste it in a browser then it will work. But its not suitable to run inside a PHP code and that because the SQL query has spaces. We cannot eliminate the spaces because a SQL query requires proper space for the computer to understand. So to solve this problem we are replacing all the spaces in the URL to %20. This way the $newUrl is  php ready which we can use in the next step.

You may ask “Well how do you know which query to pass?” I know it because its given in the documentation.

Without a user id you can still request information but  for that you have run a different SQL query. For example: search for last_name or first_name and get details related to it. Like so.

In the above example I am sending the string 'Prasadh' as last_name. This will return result of all the users whose last name is 'Prasadh'.

Run Curl script

In PHP curl is the best way to access other servers and get information. To run curl we have to first initialise it and it very mandatory that after curl process is done we close it. Lets take a look at the code and then I will explain it.

In the first line we are initialising curl. The second and third line using CURLOPT we are setting the curl options. In the first option we pass the url and in the second option we mention it to return information. In the fourth line we execute the curl and store it in $result variable. Please note that we are passing in the corrected $newUrl. We also check if there is any error in the fifth line and echo it. Finally we can close the curl which I have stress here again that it is mandatory.

Parse the result

If there are no errors then we can start accessing the $result variable. First we convert the XML result into and XML OBJECT using simplexml_load_string. This will covert the simple xml into key value pairs. Then using json_encode function we can convert the XML OBJECT to JSON. Then the JSON is decoded to an PHP ARRAY using the json_decode function. Once we have the array then we can do a var_dump($initialUsersDatas) to see all the values returned.

Final Solution

If you have reached this far then it means you have successfully connected to the DonorPerfect API using PHP. Now use your creativity and play with array to solve your requirement. In order to make copy pasting easier I have given the entire solution below.

Just copy paste this and enjoy. Make sure to change the API KEY. Have fun.