To get started:
Once you are done, you should have an API Client ID and Client Secret. Now you can continue with our tutorials.
All API calls are made to the following URL:
https://www.appturepay.com/api
For further details, see each Endpoint's document below.
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.
To enable Sandbox mode
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.
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.
Having trouble using this Doc, or found bugs/errors? Please get in touch:
Follow these steps to make use of the Payment Gateway from an eCommerce type website:
auth/access_token
endpointtransaction
endpointinclude_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.
}
}
}
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:
delivery/check_postal_code
endpointdelivery
endpoint and keep it's iddelivery/{id}/quote
endpoint using the id received previouslydelivery/{id}
endpointinclude_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);
}
}
}
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.
delivery/{id}/dispatch
endpointinclude_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);
}
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.
delivery/{id}/waybill
endpointdelivery/{id}/label
endpointinclude_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);
}
After the courier has picked up the item(s), tracking details will become available.
delivery/{id}/track
endpointinclude_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);
}