Tutorial: Integrate the Authorize.Net ARB API with PHP

Just like Authorize.Net’s Advanced Integration Method (AIM) API and Customer Information Manager (CIM) API, working with their Automated Recurring Billing (ARB) API isn’t difficult if you have suitable code to work with. The sample code offered by Authorize.Net will demonstrate how to work with their API but is not production ready. As with their AIM API and CIM API I have created a class that abstracts their ARB API into something easier to use and maintain.

To follow this tutorial and integrate ARB API into your PHP website follow these steps:

1. If you don’t already have one sign up for a Authorize.Net Developer Account. This will allow you to test your code without having an actual Authorize.Net account or incurring any processing fees.
2. Download the ARB Integration Guide (for reference)
3. Download the PHP code for ARB

To begin you will need to include the class using PHP’s require() function:

1

require('AuthnetARB.class.php');

As with any class/object the first thing we need to do is instantiate it. Up to three parameters are accepted in the constructor with the first two being required. myapilogin is the API login for the account. mYtRaNsaCTiOnKEy is the transaction key generated in the Authorize.Net control panel (or assigned to you with your test account information). If you have an Authorize.Net developer account you can use it with this script by setting the third parameters to TRUE (you may omit the third parameter if you are using this with the live server):

1
2

// Set up the subscription. If you are using a live account remove the third parameter.
$subscription = new AuthnetARB('myapilogin', 'mYtRaNsaCTiOnKEy', AuthnetARB::USE_DEVELOPMENT_SERVER);

Creating a subscription is very straight forward. We only need to set a few parameters before placing our API call. You can see the full list of parameters in the ARB Guide mentioned above. Naturally you will change these to be specific to your subscription:

1
2
3
4
5
6
7
8
9
10
11
12
13

$subscription->setParameter('amount', 29.99);
$subscription->setParameter('cardNumber', '4111111111111111');
$subscription->setParameter('expirationDate', '2016-16');
$subscription->setParameter('firstName', 'John');
$subscription->setParameter('lastName', 'Conde');
$subscription->setParameter('address', '123 Main Street');
$subscription->setParameter('city', 'Townsville');
$subscription->setParameter('state', 'NJ');
$subscription->setParameter('zip', '12345');
$subscription->setParameter('email', 'fakemail@example.com');
 
// Create the subscription
$subscription->createAccount();

After making our API call we’ll want to verify it was successful and, if so, capture the subscription ID:

1
2
3
4
5
6
7
8
9
10

// Check the results of our API call
if ($subscription->isSuccessful())
{
    // Get the subscription ID
    $subscription_id = $subscription->getSubscriberID();
}
else
{
    // The subscription was not created!
}

Make sure you save the subscription ID as you will need to refer to it if you wish to update the subscription or delete it later.

By default the class assumes the subscription will be monthly. To change the frequency and length of the subscription you can use code similar to the following examples:

1
2
3
4
5
6
7
8
9

// Put this before $subscription->createAccount(); 
// if you want the subscription to be every three months.
$subscription->setParameter('interval_length', 3);
$subscription->setParameter('startDate', date("Y-m-d", strtotime("+ 3 months")));
 
// Put this before $subscription->createAccount();
// if you want the subscription to be every year.
$subscription->setParameter('interval_unit', 'years');
$subscription->setParameter('startDate', date("Y-m-d", strtotime("+ 1 year")));

interval_length is how many units (i.e. weeks, months, years) you wish the subscription to wait before processing another payment. In the first example we set it to three which means the payment will process every three months. interval_unit sets the unit (i.e. weeks, months, years) you wish to use. In the second we changed it to “years” which means this subscription will be charged annually. startDate sets the date of the first subscription payment. We use PHP’s built in functions strtotime() and date() to make creating the date very easy. All we need to do is pass strtotime() the start date relative to today’s date in plain English. In our first example we want to set the first subscription payment to start in three months so we pass “+ 3 months” to strtotime(). In our second example we want the subscription to start in one year so we pass “+1 year” to strtotime().

By default the class assumes no trial period will occur. To create your subscription with a trial period just use the following snippet of code:

1
2
3
4

// Put this before $subscription->createAccount(); 
// if you want a trial period of three months for $10.00.
$subscription->setParameter('trialOccurrences', 3);
$subscription->setParameter('trialAmount', 10.00);

A common question concerning subscriptions is how do you handle delayed subscriptions where no money is charged up front? How do you verify the credit card is valid before making the subscription? Naturally you want to make sure the credit card is valid before making the subscription but if you’re not actually charging the first subscription payment up front (i.e. immediately) you won’t know if the credit card is valid. Fortunately verifying the credit card is easy to do. Just use the AIM API to do an Authorization Only. This will verify that the credit card is indeed valid before you create your subscription.

1
2
3
4
5
6
7
8
9
10
11
12
13

$authorization = new AuthnetAIM('myapilogin', 'mYtRaNsaCTiOnKEy');
$authorization->setTransaction($creditcard, $expiration, 0.00);
$authorization->setTransactionType('AUTH_ONLY');
$authorization->process();
 
if ($authorization->isApproved())
{
    // Set up ARB subscription
}
else if ($authorization->isDeclined())
{
    // The card is not valid
}

The AuthnetARB class takes advantage of exceptions which are new in PHP5. These are only generated when an “exceptional” event occurs. The only exceptional event that might occur when using this class is cURL may fail. This may be due to server, network, or user errors. To catch these exceptions and handle them use code similar to this:

1
2
3
4
5
6
7
8
9
10

try
{
    $cim = new AuthnetARB('myapilogin', 'mYtRaNsaCTiOnKEy');
    // Do more ARB stuff here
}
catch (AuthnetARBException $e)
{
    echo 'There was an error processing the transaction. Here is the error message: ';
    echo $e->__toString();
}

Now that we have an idea of how to create subscriptions using the ARB API let’s see a practical example that sets the billing cycle to be every three months and has a trial subscription for three months:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

< ?php
// Include AuthnetCIM class. Nothing works without it!
require('AuthnetARB.class.php');
 
// Use try/catch so if an exception is thrown we can catch it and figure out what happened
try
{
    // Set up the subscription. Use the developer account for testing..
    $subscription = new AuthnetARB('myapilogin', 'mYtRaNsaCTiOnKEy', AuthnetARB::USE_DEVELOPMENT_SERVER);
 
    // Set subscription information
    $subscription->setParameter('amount', 29.99);
    $subscription->setParameter('cardNumber', '4111111111111111');
    $subscription->setParameter('expirationDate', '2016-16');
    $subscription->setParameter('firstName', 'John');
    $subscription->setParameter('lastName', 'Conde');
    $subscription->setParameter('address', '123 Main Street');
    $subscription->setParameter('city', 'Townsville');
    $subscription->setParameter('state', 'NJ');
    $subscription->setParameter('zip', '12345');
    $subscription->setParameter('email', 'fakemail@example.com');
 
    // Set the billing cycle for every three months
    $subscription->setParameter('interval_length', 3);
    $subscription->setParameter('startDate', date("Y-m-d", strtotime("+ 3 months")));
 
    // Set up a trial subscription for three months at a reduced price
    $subscription->setParameter('trialOccurrences', 3);
    $subscription->setParameter('trialAmount', 10.00);
 
    // Create the subscription
    $subscription->createAccount();
 
    // Check the results of our API call
    if ($subscription->isSuccessful())
    {
        // Get the subscription ID
        $subscription_id = $subscription->getSubscriberID();
    }
    else
    {
        // The subscription was not created!
    }
}
catch (AuthnetARBException $e)
{
    echo $e;
    echo $subscription;
}
?>

This class also supports updating and deleting subscriptions. Updating a subscription might look like this:

1
2
3
4
5
6
7
8
9
10
11
12

$subscription = new AuthnetARB('myapilogin', 'mYtRaNsaCTiOnKEy');
$subscription->setParameter('subscriptionId', $subscription_id);
$subscription->setParameter('cardNumber', '4111111111111111');
$subscription->setParameter('expirationDate', '2016-16');
$subscription->setParameter('firstName', 'John');
$subscription->setParameter('lastName', 'Conde');
$subscription->setParameter('address', '123 Main Street');
$subscription->setParameter('city', 'Townsville');
$subscription->setParameter('state', 'NJ');
$subscription->setParameter('zip', '12345');
$subscription->setParameter('email', 'fakemail@example.com');
$subscription->updateAccount();

Deleting a subscription would look like this:

1
2
3

$subscription = new AuthnetARB('myapilogin', 'mYtRaNsaCTiOnKEy');
$subscription->setParameter('subscriptionId', $subscription_id);
$subscription->deleteAccount();

There you have it. Working with Authorize.Net’s ARB API is pretty easy once you hide their API behind some easy to use code. Have fun creating subscriptions!

Related Posts:

• Tutorial: Integrate the Authorize.Net CIM API with PHP
• Handling Authorize.Net Silent Post with PHP
• Tutorial: Integrating the Authorize.Net AIM API with PHP
• All About Authorize.Net’s Silent Post
• Cropping An Image with PHP and the GD Library

Tags: Authorize.Net, PHP

February 8th, 2010 at 12:18 pm | Posted in Programming