Appture Pay API Documentation

Using this Doc

Getting Started

To get started:

  1. Create an Appture Pay account
  2. Complete the Getting Started steps in your dashboard

Once you are done, you should have an API Client ID and Client Secret. Now you can continue with our tutorials.


API URL

All API calls are made to the following URL:

https://www.appturepay.com/api

For further details, see each Endpoint's document below.


Code Samples

In this document, code samples are included with each endpoint and method. We have placed all these samples together in a Bitbucket repo.

The PHP code samples make use of 2 classes to make integration much easier. These are available in the Bitbucket repo.

Samples on Bitbucket


Sandbox Mode

To enable Sandbox mode

  1. create a new Client, or edit an existing Client,
  2. tick its Sandbox Mode checkbox and
  3. set the Client's Sandbox URLs as needed.

There is no need to use a different server to make the calls too. All calls made, when authenticated as a Sandbox Client, will be made in Sandbox mode.


API Testing

You can run tests and preview the response via this documentation. To make use of this feature you will need to authenticate by entering your Client ID and Secret, in the Auth Access Token Endpoint's API Testing section, and authenticating. The access token is saved to the session so you can test each endpoint after authenticating.


Need Help?

Having trouble using this Doc, or found bugs/errors? Please get in touch:

admin@appturepay.com

Tutorials

Payment Gateway

Follow these steps to make use of the Payment Gateway from an eCommerce type website:

  1. Get an access token by authenticating your Client using the auth/access_token endpoint
  2. Create a transaction via the transaction endpoint
  3. Redirect the user to the Payment Gateway with the transaction id as parameter
  4. Appture Pay's API will do a server-to-server call to your set callback URL with the result of the transaction
  5. The Payment Gateway then redirects the user to your set redirect URL
include_once "includes/WebRequest.php";
include_once "includes/AppturePayAPI.php";

// 1. In order to authenticate as a Client, simply instantiate the AppturePayAPI 
// class with your client details. The constructor will automatically check if
// we have authenticated previously, and access token details were saved to the
// session, or if it should authenticate. If not authenticated it will do so and 
// save the access token to the PHP session.

$clientId = "{your client id}";
$clientSecret = "{your client secret}";

// get an instance of the AppturePayAPI class
$api = new ApptureLab\AppturePayAPI($clientId, $clientSecret);

// make sure we are successfully authenticated
if( $api->getSession() !== null ) {

    // 2. After authenticating we can create the transaction. 
    
    // variable for keeping the response
    $transactionPostResponse = null;

    // values to pass as request body
    $data = array(
        "client_id" => $clientId,
        "transaction_type" => "DB",
        "recurring_term" => "1",
        "reference" => "TRANS01",
        "description" => "Test transaction",
        "total" => "999.99"
    );
    
    // then make the call to the transaction/{id} endpoint using the POST method
    $transactionPostResponse = $api->transactionPost($data);

    // make sure it was a success
    if($transactionPostResponse !== null && $transactionPostResponse["success"]) {

        // 3. Now we can redirect the user to the Payment Gateway.
    
        header("Location: https://www.appturepay.com/gateway/?id={$transactionPostResponse['data']['identifier']}");

    }
    
}

...

// 4. Receiving the server-to-server callback request from Appture Pay, after successful payment.

$transactionId = filter_input(INPUT_GET, "id");
$transactionReference = filter_input(INPUT_GET, "reference");

if($transactionId && $transactionReference) {

    // Get your local order against which to check the transaction.
    $order = array();
    
    // Get the transaction from AppturePay.

    // get an instance of the AppturePayAPI class
    $api = new ApptureLab\AppturePayAPI($clientId, $clientSecret);

    // make sure we are successfully authenticated
    if( $api->getSession() !== null ) {
        
        // then make the call to the transaction/{id} endpoint using the GET method
        $transactionGetResponse = $api->transactionGetSpecific($transactionId);
        
        // make sure it was a success
        if($transactionGetResponse !== null && $transactionGetResponse["success"]) {

            // Check the transaction's status and also that its total matches
            // with your local order.
            
            if($transactionGetResponse["data"]["status"] === "SUCCESS") {

                // Do something specific on success, ie update redeemed voucher
                // codes, send success email etc.

            }

            // Update your local order to indicate the status of the payment.
            
        }
        
    }

}

Courier Quote

Before requesting a delivery quotation, you will need to add an Address, for the pickup point, to your Appture Pay account.

Follow these steps in order to get a delivery quotation:

  1. Get the delivery address and check it's postal code using the delivery/check_postal_code endpoint
  2. Create a delivery via the delivery endpoint and keep it's id
  3. Request a delivery quote via the delivery/{id}/quote endpoint using the id received previously
  4. Allow your buyer to select a service option returned by the previous request
  5. Update the delivery with the selected service option using the delivery/{id} endpoint
include_once "includes/WebRequest.php";
include_once "includes/AppturePayAPI.php";

$clientId = "{your client id}";
$clientSecret = "{your client secret}";

// get an instance of the AppturePayAPI class
$api = new ApptureLab\AppturePayAPI($clientId, $clientSecret);

// First, create a delivery.

// variable for keeping the response
$deliveryPostResponse = null;

// values to pass as request body
$data = array(
    "delivery_courier_checked" => 0,
    "delivery_contact_name" => "Test",
    "delivery_contact_number_1" => "1231231234",
    "delivery_street" => "Street Ave",
    "delivery_suburb" => "Suburb",
    "delivery_city" => "City",
    "delivery_province" => "Gauteng",
    "delivery_country" => "South Africa",
    "delivery_postal_code" => "1234"
);

// make sure we are successfully authenticated
if( $api->getSession() !== null ) {
    // then make the call to the delivery/{id} endpoint using the GET method
    $deliveryPostResponse = $api->deliveryPost($data);
    
    // make sure the post succeeded
    if($deliveryPostResponse !== null && $deliveryPostResponse["success"]) {
        
        // Next we can call the quote endpoint for this delivery.
        
        // variable for keeping the response
        $deliveryPostQuoteResponse = null;
        
        // delivery id
        $id = $deliveryPostResponse["data"]["id"];

        // values to pass as request body
        $data = array(
            "value" => "199",
            "products" => array(
                array(
                    "quantity" => 1, // integer		  Y	number of pieces
                    "description" => "String with max length of 30", // string[30]	  N	freight description
                    "height" => 100, // integer		  Y	dimension 1 in millimeters
                    "width" => 250, // integer		  Y	dimension 2 in millimeters
                    "length" => 100, // integer		  Y	dimension 3 in millimeters
                    "weight" => 1.0 // float		  Y	mass in kilograms
                )
            ),
            "insurance" => 1
        );

        // then make the call to the delivery/{id}/quote endpoint using the POST method
        $deliveryPostQuoteResponse = $api->deliveryPostQuote($id, $data);
        
        // make sure the post succeeded
        if($deliveryPostQuoteResponse !== null && $deliveryPostQuoteResponse["success"]) {
            
            /* 
             Here you may give the user a list of rates/services, as quoted, in 
             order for them to select their own preferred service.
             */
            
            // Finally we can select the preferred service for the delivery quote.
            
            // variable for keeping the response
            $deliveryPutQuoteResponse = null;
            
            // values to pass as request body
            $data = array(
                // we will select the first service in the list of services/rates received
                "service" => $deliveryPostQuoteResponse["data"]["rates"][0]["service"]
            );

            // then make the call to the delivery/{id}/quote endpoint using the PUT method
            $deliveryPutQuoteResponse = $api->deliveryPutQuote($id, $data);
            var_dump($deliveryPutQuoteResponse);
            
        }
        
    }
}

Courier Dispatch

After completing the steps for creating a quotation and selecting a service option, the delivery can be dispatched. On success, the quoted amount for the selected service option will be deducted from your wallet.

  • To dispatch the courier call the delivery/{id}/dispatch endpoint
include_once "includes/WebRequest.php";
include_once "includes/AppturePayAPI.php";

$clientId = "{your client id}";
$clientSecret = "{your client secret}";

// get an instance of the AppturePayAPI class
$api = new ApptureLab\AppturePayAPI($clientId, $clientSecret);

// variable for keeping the response
$deliveryPutDispatchResponse = null;

// delivery id
$id = "{delivery id}";

// make sure we are successfully authenticated
if( $api->getSession() !== null ) {
    // make the call to the delivery/{id}/dispatch endpoint using the PUT method
    $deliveryPutDispatchResponse = $api->deliveryPutDispatch($id, null);
    var_dump($deliveryPutDispatchResponse);
}

Get Waybill and Label(s)

After dispatching the delivery, its waybill and label(s) can be downloaded and printed. There is a separate endpoint for each and the waybill or label will be sent back as an inline PDF file which should be saved locally and printed to present it to the courier's official on arrival. In case multiple products were quoted for delivery, multiple labels will exist within the label PDF.

  • To download the waybill call the delivery/{id}/waybill endpoint
  • To download the label(s) call the delivery/{id}/label endpoint
include_once "includes/WebRequest.php";
include_once "includes/AppturePayAPI.php";

$clientId = "{your client id}";
$clientSecret = "{your client secret}";

// get an instance of the AppturePayAPI class
$api = new ApptureLab\AppturePayAPI($clientId, $clientSecret);

// variable for keeping the response
$deliveryGetWaybillResponse = null;
$deliveryGetLabelResponse = null;

// delivery id
$id = "{delivery id}";

// make sure we are successfully authenticated
if( $api->getSession() !== null ) {
    // make the call to the delivery/{id}/waybill endpoint using the GET method
    $deliveryGetWaybillResponse = $api->deliveryGetWaybill($id);
    var_dump($deliveryGetWaybillResponse);

    // make the call to the delivery/{id}/label endpoint using the GET method
    $deliveryGetLabelResponse = $api->deliveryGetLabel($id);
    var_dump($deliveryGetLabelResponse);
}

Delivery Tracking

After the courier has picked up the item(s), tracking details will become available.

  • To get tracking info for a delivery call the delivery/{id}/track endpoint
include_once "includes/WebRequest.php";
include_once "includes/AppturePayAPI.php";

$clientId = "{your client id}";
$clientSecret = "{your client secret}";

// get an instance of the AppturePayAPI class
$api = new ApptureLab\AppturePayAPI($clientId, $clientSecret);

// variable for keeping the response
$deliveryGetTrackResponse = null;

// delivery id
$id = "{delivery id}";

// make sure we are successfully authenticated
if( $api->getSession() !== null ) {
    // then make the call to the delivery/{id}/track endpoint using the GET method
    $deliveryGetTrackResponse = $api->deliveryGetTrack($id);
    var_dump($deliveryGetTrackResponse);
}