Affirm PHP API Connector

This is a stand-alone PHP library that connects to the Affirm API. The intent is to be able to plug this library into the e-commerce platform of choice, provided it can use PHP. It can either be installed as a library to your PHP driven website or your commandline PHP scripting library.

Installation

Unpack or clone this git repository into a directory where you desire to place the files. When you use this for your library, all you need is a one line include to the affirm-api.php file in the root level of this directory. This file will include all the other ones needed to load the classes required for this API to work properly.

<?php

/* Choose a directory or path to your application */
define('DOC_ROOT', '/home/website/public_html/');

/* Include the main file (which will include all others needed) */
include(DOC_ROOT . '/affirm-php/affirm-api.php');

Dependencies

This library depends on PHP 5.5 or later. Most GNU/Linux distributions provide them in an easily downloaded and installed repository. The PHP cURL Library and the PHP JSON Library are also needed, and are often packaged separately. Installation instructions are shown below for each of the major GNU/Linux distribution types. These commands must all be run as root, or use sudo utility.

APT (Debian/Ubuntu based distributions)

# Update the apt cache
apt-get update

# Install the dependencies
apt-get install php5 php5-curl php5-json

YUM (Fedora/CentOS/Red Hat based distributions)

# No need to update cache, it's automatic

# Install the dependencies
yum install php5 php5-json php5-curl

Affirm Account

A current Affirm account is required for this library. You may sign up here. Once signed up for Affirm, a public/private key pair that serves as your username and password would be provided, along with a Financial Product Key and your API URL. In another area of your application that faces the web, you should follow the steps outlined in the Affirm Site Integration documentation. Your server should also be set up to receive the webhook that sends the checkout_token to your application as this checkout token is used for initializing your charge (see Usage below).

Configuration

One final step before starting to call objects in the application is to copy config.php.default to config.php and update the information for your credentials. This configuration file is used to create the AffirmConfig class which is required for the application. If you choose not to enter your details in this file because it is stored in a database, this file is still required because the AffirmConfig class provides the current API base URLs.

Usage

This library contains a few PHP classes that are used for interfacing with Affirm and your application. You may either hard-code your details in config.php or if stored in your application's database, you can enter your credentials into the arguments of the create_charge() method of the AffirmAPI class. The $live_baseurl and $sandbox_baseurl properties of the AffirmConfig class must be left as shown in the config.php.default The methods of the AffirmAPI class and how to instantiate the class is shown below. Unless you are doing testing, your code should only interface with instances of the AffirmAPI class.

Create an Instance of The AffirmAPI Class

Once the library is installed and properly linked as shown in Installation above, you may create an instance of the AffirmAPI class in two ways. The first way shows if you used the AffirmConfig class to store all of your API keys and other credentials:

// Create a new AffirmAPI with a fully configured AffirmConfig class
$affirm = new AffirmAPI();

The alternative is to add arguments so that it will construct the object with these credentials overriding the ones stored in the AffirmConfig class:

// These would really be in a database, but showing this for example
$public_key = 'secretkey'; /**< Public API key, also used on Site Integration */
$private_key = 'supersecretkey'; /**< Private API key, never share this! */
$product_key = 'financialkey'; /**< Financial product key */
$production = true; /**< Set this to false if in sandbox mode */

// Create a new AffirmAPI with the above information included
$affirm = new AffirmAPI($public_key, $private_key, $product_key, $production);

Error Handling

All methods (except the constructor) of the AffirmAPI class return a status code while updating the object with the reponse from Affirm. The method returns an integer status that corresponds with the Affirm status code if an error is returned from Affirm. It returns the integer 1 if the API catches an error before sending a request to Affirm. If a non-zero status is sent, the response object in the AffirmAPI object is an Error object as defined in the Affirm Documentation. If no error is observed, the status returned is 0 (instead of the HTTP status 200) to behave similar to other APIs where zero mean no error.

Create a new Charge

Your web-facing application would harvest a checkout_token which is required for creating a new charge. The information for the new charge is stored in the instance of the AffirmAPI class and the data can be used to do further operations with the charge. You should also store the charge_id in your application's database if you intend on updating information at any time in the future. Once you use your checkout_token it is safe to discard as it is a one-time use token and is no longer usable once a new charge is created.

$token = 'exampleaffirmtoken' /**< checkout_token from Affirm */
// Creating a charge, storing data in the $affirm object
$error = $affirm->create_charge($token);
if(!$error){
  $charge_object = $affirm->response;
  $charge_id = $affirm->response->id;
}
else{
  $error_object = $affirm->response;
}

Once you have a charge_id, you can use it to perform further actions to the charge as needed.

Read a Charge

When you read a charge, you retreive the information that Affirm has on your charge. The output that is registered in the instance of the AffirmAPI is the same as the output from the create_charge() method, except this uses the charge_id since you can only create a charge once.

// Given a $charge_id request a charge object from Affirm
$error = $affirm->read_charge($charge_id);
if(!$error){
  $charge_object = $affirm->response;
}
else{
  $error_object = $affirm->response;
}

Capture a Charge

To capture a charge, use the capture_charge() method with your charge_id in addition to a few optional parameters. These additional parameters are optional:

• order_id - A string field for your own reference
• shipping_carrier - A string that contains the shipping carrier
• shipping_confirmation - A string that contains the shipping confirmation

// Given a $charge_id and no optional fields desired
$error = $affirm->capture_charge($charge_id);
if(!$error){
  $charge_event = $affirm->response;
}
else{
  $error_object = $affirm->response;
}

// If adding the optional fields, include them as follows
$order_id = 'yourownappid'; /**< Order ID for your own records */
$shipping_carrier = 'USPS'; /**< Carrier shipping the goods */
$shipping_confirmation = 'someconfnumber'; /**< Shipping confirmation number */

$error = $affirm->capture_charge($charge_id, $order_id, $shipping_carrier, $shipping_confirmation);
if(!$error){
  $charge_event = $affirm->response;
}
else{
  $error_object = $affirm->response;
}

// If you provide only a few optional fields, set others to null
$order_id = 'yourownappid';
$shipping_carrier = 'USPS';
$shipping_confirmation = null; //Shipping confirmation was not supplied

$error = $affirm->capture_charge($charge_id, $order_id, $shipping_carrier, $shipping_confirmation);
if(!$error){
  $charge_event = $affirm->response;
}
else{
  $error_object = $affirm->response;
}

Void a Charge

To void a charge, use the void_charge() method with your charge_id. No other parameters are required.

// Given a $charge_id void a charge
$error = $affirm->void_charge($charge_id);
if(!$error){
  $charge_event = $affirm->response;
}
else{
  $error_object = $affirm->response;
}

Refund a Charge

To refund a charge, use the refund_charge() method with your charge_id and the amount to be refunded. This amount must either be in cents, or omitted. If the value is omitted or null, the Affirm side will attempt to refund the entire amount of the charge.

// Given a $charge_id refund a charge and an amount
$amount = 399; /**< refund amount MUST be in cents */
$error = $affirm->refund_charge($charge_id, $amount);
if(!$error){
  $charge_event = $affirm->response;
}
else{
  $error_object = $affirm->response;
}

// Omit amount to refund full amount
$error = $affirm->refund_charge($charge_id);
if(!$error){
  $charge_event = $affirm->response;
}
else{
  $error_object = $affirm->response;
}

Update Shipping Information

To update shipping information, use the updates_shipping() method with your charge_id and the optional fields mentioned in Capture a Charge:

• order_id - A string field for your own reference
• shipping_carrier - A string that contains the shipping carrier
• shipping_confirmation - A string that contains the shipping confirmation

// Given a $charge_id and the fields desired to be updated
$order_id = 'yourownappid'; /**< Order ID for your own records */
$shipping_carrier = 'USPS'; /**< Carrier shipping the goods */
$shipping_confirmation = 'someconfnumber'; /**< Shipping confirmation number */

$error = $affirm->update_shipping($charge_id, $order_id, $shipping_carrier, $shipping_confirmation);
if(!$error){
  $charge_event = $affirm->response;
}
else{
  $error_object = $affirm->response;
}

// If you provide only a few optional fields, set others to null
$order_id = null; //Was not changed
$shipping_carrier = 'UPS'; //Changed carrier
$shipping_confirmation = 'someconfnumber'; //Shipping confirmation changed

$error = $affirm->update_shipping($charge_id, $order_id, $shipping_carrier, $shipping_confirmation);
if(!$error){
  $charge_event = $affirm->response;
}
else{
  $error_object = $affirm->response;
}