Documentation

Getting Started

The OpenGateway Billing Engine is multi-gateway single payment and recurring billing payment engine built for integration by web developers. Through it's simple API and control panel (used optionally, depending on how heavily you rely on the API), OpenGateway handles every aspect of accepting payments online from subscription plans to billing records and billing-related emails.

Intended Audience

This API documentation is intended for web developers who have access to an OpenGateway billing server. With your API Identifier and API Secret Key, you have permission to submit requests.

Developers should have knowledge in a programming language such as PHP, .NET, Python, Perl, or Ruby and have knowledge of web service usage and how to create simple XML requests.

What is the API for?

With the API, you can access every functional aspect of the billing platform. For those who want to use only certain elements of the API (e.g., to charge credit cards, setup recurring charges, or create new customer records), the OpenGateway control panel (located at your root installation folder) can handle the less common administrative aspects of your billing setup such as payment gateways, email triggers, and recurring plans.

An example usage of the API would be to:

Documentation Legend

All request parameters will be highlighted like this: request_parameter.

All response variables will be highlighted like this: response_variable.

Example code will appear in similar boxes colour-coded as either requests or responses.

Authentication

All API requests are authenticated with an API Identifier and API Secret Key passed in the request.

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<request>
	<authentication>
		<api_id>FAKE000API000ID</api_id>
	        <secret_key>FAKE000API000SECRET000KEY</secret_key>
	</authentication>
	<type>GetCustomers</type>
	<limit>50</limit>
</request>

Request Format

Requests must be made in XML format and sent via an HTTP POST call to the OpenGateway platform server. A secure (https://) connection is required (as per the recommended configuration) for requests that contain credit card information. Requests should be posted to the API URL. This located at your root installation folder/api. So, if you have OpenGateway installed at http://opengateway.example.com, you would use the following URL's: 

http://opengateway.example.com/api // URL for non-credit card requests
https://opengateway.example.com/api // URL for credit card requests

Each request must be accompanied by an authentication node with an api_id and secret_key as well as a type value which specifies the API method to be called (e.g. "NewCustomer", "Charge", or "GetPlan"). All other request parameters vary depending on the API method.

In the "Method Reference" section of this documentation, you will find an example of each type of API request, required and optional parameters, as well as the response format with examples.

Using PHP, an API request might look like this:

<?php

$post_url = 'https://opengateway.example.com/api';

$poststring = '<?xml version="1.0" encoding="UTF-8"?>
<request>
	<authentication>
		<api_id>FAKE000API000ID</api_id>
		<secret_key>FAKE000API000SECRET000KEY</secret_key>
	</authentication>
	<type>Charge</type>
	<gateway_id>594082</gateway_id>
	<credit_card>
		<card_num>0000123412341234</card_num>
		<exp_month>12</exp_month>
		<exp_year>2015</exp_year>
		<cvv>123</cvv>
	</credit_card>
	<amount>95.00</amount>
</request>';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$post_url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_TIMEOUT, 10);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $poststring); 

$response = curl_exec($ch); 

if(curl_errno($ch))
{
    echo curl_error($ch);
    curl_close($ch);
    die();
} else {
    curl_close($ch);

    /**
    * deal with the $response
    * because this was a charge, we'll look for "response_code" == 1
    * to indicate success
    */
}

Response Format

Responses can be in XML, JSON, or serialized PHP format. The default response format is XML. To request another format, send a format parameter with a value of either "json" or "php".

Example response in XML format (for a GetCustomer call):

<?xml version="1.0" encoding="utf-8"?>
<response>
  <customer>
    <id>140</id>
    <internal_id/>
    <first_name>Joe</first_name>
    <last_name>Customer</last_name>
    <company/>
    <address_1>12345 Ontario St.</address_1>
    <address_2/>
    <city>Toronto</city>
    <state>ON</state>
    <postal_code>A1B2C3</postal_code>
    <country>CA</country>
    <email>joe@example.com</email>
    <phone/>
    <plans>
      <plan>
        <id>123456789</id>
        <type>paid</type>
        <name>Fake Plan</name>
        <amount>14.95</amount>
        <interval>30</interval>
        <notification_url>http://www.example.com/post.php</notification_url>
        <status>active</status>
      </plan>
    </plans>
  </customer>
</response>