AddPay PHP SDK by Stephen Lake
A PHP package to assist in developing applications communicating with the AddPay API.

Documentation

• Getting Started
  • Requirements
  • Running the Examples
  • Download Latest Release
  • Configuration
  • Before Diving Into Code
  • SDK Repository Reference
  • SDK Methods Reference
• Bug Reporting
• Contributing & Suggestions
• Disclaimer

Getting Started

Please have the AddPay API Documentation open and closeby when referencing fields, this will improve your productivity and hopefully answer many questions you may have on field definitions and requirements. All fields are described within the AddPay API Documentation.

Requirements

For clarification sake to less experienced developers, this package does NOT require composer - it was merely built using composer, do not let the additional files scare you off, the package is dead simple to use. The only requirements are:

• PHP5.3+ (PHP7.1+ Recommended)
• PHP-CURL Extension
• PHP-OPENSSL Extension
• A little bit of patience (Reading Highly Recommended)

Running/Using Examples

The following guides assume you have PHP installed on the system running the code. If PHP is not installed, please view the PHP Installation documentation. PHP5.3+ is supported, but PHP7.1+ is recommended for optimal performance.

• Getting Started: Windows (Animated GIF's Included)
• Getting Started: Linux/Mac (Animated GIF's Included)

More Advanced Developers

Developers using composer and/or developers who prefer OOP code can simply import the required services from the AddPay\Foundation\Protocol\API namespace and use the package you would any other:

<?php

use AddPay\Foundation\Protocol\API\OpenAPI;
use AddPay\Foundation\Protocol\API\PublicAPI;
use AddPay\Foundation\Protocol\API\PrivateAPI;

$openAPI = new OpenAPI();
$pubAPI  = new PublicAPI();
$pvtAPI  = new PrivateAPI();

// Quick start example:
$openAPI->transactions()->find('SOME_TRANSACTION_ID_HERE');

// If you wish to load a config file from a custom directory,
// copy the config/config.json to the directory of your choice
// and pass through the DIRECTORY as an argument in the instantiation
//
// Note: The file name must be config.json and the argument must be the 
// DIRECTORY excluding the file name

$openAPI = new OpenAPI('path/to/your/config/');
$pubAPI  = new PublicAPI('path/to/your/config/');
$pvtAPI  = new PrivateAPI('path/to/your/config/');

// Alternatively, pass through the entire config array:
$openAPI = new OpenAPI([
    'live'     => false,
    'open_api' => [
        'client_id'     => 'your_client_id',
        'client_secret' => 'your_client_secret',
        'public_key'    => 'your_optional_public_key_here'
    ]
]);

Download Latest Release

More advanced users or users that are familiar with composer may download the package through composer if they wish:

composer require stephenlake/addpay-php-sdk

Alternatively, download the master archive directly: AddPay-PHP-SDK-Master.zip

Configuration

• Head to your developer portal or merchant console developer settings if your integration is live, find the section providing your client_id and client_secret, keep these credentials closeby.
• Open the configuration file in this package located at path/to/this/package/config/config.json
• Replace your_client_id with your actual client_id
• Replace your_client_secret with your actual client_secret
• If your integration is live, set live to true
• It is important to ensure the structure of the file is unchanged, the quotes are important!

Before Diving Into Code

Magic Getter: get

The get() function is my own custom magic method that allows you to call any string after the word 'get' and it will return the value of the string provided within the object it is being called on, this means that even if there are changes to an object, the magic method can still retrieve the added fields without any changes to this SDK.

Example: $call->getFirstname('John')

The getFirstname() function does not exist, but will succeed and will return the value of firstname if it the field firstname exists in the data object it is being called on. For nested attributes, the call is simply camel-cased, for example: $call->getCurrencyName() will look for the following object:

{
 "currency": {
   "name": "South African Rand"
 }
}

If it does not find the attribute, it returns null. The level of nesting using camel-casing is infinite, for example calling getFooBarsRealLastNameAndLoremIpsum() will also return a value if the nested attributes exist, otherwise it will return null.

Magic Setter: with

The magic with setter is my own custom magic method that allows you to set any string after the word 'with' and it will set the value of the string provided within the object it is being called on. This works in exactly the same way as the magic getter except it sets field and nested field values and returns the object so that you can chain setters, for example:

$object->withFirstname('John')
       ->withLastname('Doe')
       ->withAddressStreet('1337 Awesome Street')
       ->withAddressPostal('123456');

This wil result in the following object being built:

{
  "firstname": "John",
  "lastname": "Doe",
  "address": {
    "street": "1337 Awesome Street",
    "postal": "123456"
  }
}

Please note that there are some fallback methods in place to prevent unexpected results, for example, with the above information in mind, you'd expect withAmountCurrencyCode('USD') to set the following object:

{
   "amount": {
     "currency": {
        "code": "USD"
     }
   }
}

However, the AddPay API expects the request payload of a currency code to be a single field of currency_code and not an object - therefore a primary function has been defined specifically for setAmountCurrencyCode() to prevent such scenarios. You can view the full list of primary defined functions as well as how the magic methods functions were written within the JSONObject class.

SDK Repository Reference

SDK Method Reference

Bug Reporting

Please use the GitHub Issues tab to report any problems you are having with the package. I am fully aware that there are code lines that can be optimized using PHP7's new functionality, but I have deliberately avoided this to keep the package compatible with older version of PHP, please do not report performance improvements unless they are backward compatible.

Contributing & Suggestions

Create a pull request at any point. Do not suggest an addition or make a request for change in writing, just write the code and submit a pull request, if it improves the package without generating any breaking changes and adds efficiency, then it will be merged. I will ignore any demands/requests for changes without any suggested code replacement and/or additions.

Disclaimer

This package and all documentation was developed by Stephen Lake as a personal project to assist developers unfamiliar with the AddPay API in getting started quickly and efficiently. This is an unofficial package and therefore support is limited and provided as a courtesy.