Network Merchants NMI API Integration – PHP Class

Introduction

The Network Merchants API is a simple name value pair API that enables a website to process credit cards or electronic checks through the Network Merchants Gateway. Network Merchants offers 2 API’s, one for processing and another for secure customer storage.

The following is an implementation of both API’s using the PHP programming language.

Requirements

PHP5 web server
CURL installed with OpenSSL support

Authentication

You can enter your Network Merchants username and password by either hard coding them, or dynamically passing them when you instantiate the class.

Hard Coding Method
Change these values to your own username and password.

/*
     * Hard coded network merchants API username
     * This can be overridden when instantiating the class
     * Override using nmi_user in the options() array
     */
    private $nmi_user = 'myusername';
 
    /*
     * Hard coded network merchants API password
     * This can be overridden when instantiating the class
     * Override using nmi_password in the options() array
     */
    private $nmi_password = 'mypassword';

Dynamic Method

 
$transaction = new nmiDirectPost(array('nmi_user'=>'myusername','nmi_password'=>'mypassword'));

Response

The API response can be handled the same way no matter what api or method is being used. I recommend using something similar to the following for response handling.

switch($result['response'])
{
    case 1: //Success
 
        //Add order to database or whatever other internal action is needed
 
        break;
    default; //Error or fail, The fail response is actually 2, error is 3, but we fail regardless if it's not successful
 
        //You can redisplay your form here, or do something
 
}

Direct Post API

The direct post API is the standard credit card and ACH processing API for network merchants. We can create a sale, authorization, capture, void, refund, credit or update a transaction via the direct post API.

The following are the available function of the Direct Post API. Each function has a specific purpose although most sites will only need the Sale function.

Sale

A sale is a 2 part transaction where a credit card is authorized and then captured which sends it to the processor for settlement. A transaction must both be authorized and captured before it is completed. Most sites will only need to use the Sale function.

Sale Example:

$transaction = new nmiDirectPost;
 
$transaction->setOrderDescription('Some Item');
$transaction->setAmount('100.00');
$transaction->setTax('9.00');
$transaction->setShipping('12.00');
 
$transaction->setCcNumber('4111111111111111');
$transaction->setCcExp('1113');
$transaction->setCvv('999');
 
$transaction->setCompany('Some company');
$transaction->setFirstName('John');
$transaction->setLastName('Smith');
$transaction->setAddress1('888');
$transaction->setCity('Dallas');
$transaction->setState('TX');
$transaction->setZip('77777');
$transaction->setPhone('5555555555');
$transaction->setEmail('test@domain.com');
 
$transaction->sale();
 
$result = $transaction->execute();

Auth

An auth or authorization is used to secure a transaction amount from a cardholder, but the transaction will be completed later. A site would use this function if they expect a major delay before shipping, or if this is a preliminary price for the transaction. You must later perform a capture to finalize the transaction.

Auth Example:

 
//Identical to above except, replace $transaction->sale(); with $transaction->auth();
$transaction->auth();
 
$result = $transaction->execute();

Capture

A capture requires a transaction id, obtained using the Auth function. A capture will finalize the transaction and queue it to be sent to the processor for settlement. A capture can be for a lesser amount than the Auth. Check with your processor to see the maximum amount of time between an Auth and a Capture. Additionally, if the time between the auth and the capture is too great (again, talk to your processor for time limits) the transaction will downgrade and increased fees will be assessed.

Capture Example:

 
//Transaction ID from previous Auth
$transaction_id = '123456';
 
$transaction = new nmiDirectPost;
 
$transaction->setTransactionId($transaction_id);
$transaction->setAmount('100.00');
 
 
$transaction->capture();
 
$result = $transaction->execute();

Void

This is the quickest way to cancel a transaction, but it can be voided only before it is settled at the end of the day. Once settled, the transaction must be refunded.

Void Example:

 
//Transaction ID from previous Transaction
//Must not be settled yet
$transaction_id = '123456';
 
$transaction = new nmiDirectPost;
 
$transaction->setTransactionId($transaction_id);
 
$transaction->void();
 
$result = $transaction->execute();

Refund

Transactions that have been settled must be refunded. This will reverse the amount of the transaction, and it will be deposited in the customer’s bank account generally in 4 – 5 days.

Refund Example:

 
//Transaction ID from previous Transaction
$transaction_id = '123456';
 
$transaction = new nmiDirectPost;
 
$transaction->setTransactionId($transaction_id);
$transaction->setAmount('100.00');  //optional. Only needed if you are making a partial refund
 
$transaction->refund();
 
$result = $transaction->execute();

Credit

A credit is a direct transfer back to a customer’s account. Credit’s should be closely monitored as they are one of the most used methods for committing fraud. Visa/MC closely watch credits for malicious and unethical activity.

Credit Example:

 
//Identical to Sale and Auth except, replace $transaction->sale(); with $transaction->credit();
$transaction->credit();
 
$result = $transaction->execute();

Update

An update allows a customer’s transaction information to be updated with shipping information, tracking number, and shipping carrier. This is to be used for internal purposes, and will not affect any interaction with the customer.

Update Example:

 
//Transaction ID from previous Auth
$transaction_id = '123456';
 
//Tracking Number
$tracking_number = '1Z8905............';
 
//Custom Order Id
$order_id = '432543';
 
$transaction = new nmiDirectPost;
 
$transaction->setTransactionId($transaction_id);
$transaction->setOrderId($order_id);
$transaction->setTrackingNumber($tracking_number);
$transaction->setShippingCarrier('ups'); //Acceptable values are ups, fedex, dhl, or usps
 
$transaction->update();
 
$result = $transaction->execute();

Customer Vault API

The Customer Vault API allows adding a customer to the Network Merchants secure customer vault. This will give the ability to charge that customer’s credit card without storing their credit card number. Once a customer is added to the vault, they can be charged simply by referencing their unique customer vault id.

The Customer Vault API supports several functions: adding, adding and charging, charging an existing customer, updating, and deleting. Customers added to the vault are also available in the administration area of the gateway.

Add

We add a customer to the vault so that we can charge their card later, but not store the card our-self. We do not need to charge a customer to add them to the vault, but we must have their authorization and their card number and expiration date.

Add Example:

 
$vault = new nmiCustomerVault;
 
$vault->setCcNumber('4111111111111111');
$vault->setCcExp('1113');
$vault->setCvv('999'); //CVV is not stored by the vault but can be used if performing an add and charge
 
$vault->setCompany('Some company');
$vault->setFirstName('John');
$vault->setLastName('Smith');
$vault->setAddress1('888');
$vault->setCity('Dallas');
$vault->setState('TX');
$vault->setZip('77777');
$vault->setPhone('8008983436');
$vault->setEmail('test@domain.com');
 
$vault->add();
 
$result = $vault->execute();

Add and Charge

We can also charge a customer at the same time we add them to the vault. This is easier than charging the customer through the direct post and subsequently adding them to the vault with a second transaction.

Add and Charge Example:

$vault = new nmiCustomerVault;
 
$vault->setCcNumber('4111111111111111');
$vault->setCcExp('1113');
$vault->setCvv('999'); //CVV is not stored by the vault but can be used if performing an add and charge
 
$vault->setCompany('Some company');
$vault->setFirstName('John');
$vault->setLastName('Smith');
$vault->setAddress1('888');
$vault->setCity('Dallas');
$vault->setState('TX');
$vault->setZip('77777');
$vault->setPhone('8008983436');
$vault->setEmail('test@domain.com');
 
$vault->addAndCharge(150.00);
 
$result = $vault->execute();

Charge

Most importantly we need to be able to charge existing customers in our vault. We simply do this by specifying an amount and referencing the customer id that was returned to us when we added the customer to the vault.

Charge Example:

$customer_vault_id = '123456';
 
$vault = new nmiCustomerVault;
$vault->setCustomerVaultId($customer_vault_id);
$vault->charge(100.00);
 
$result = $vault->execute();

Update

Updating allows us to update the customer information stored in the vault. We can update any of the parameters including the credit card. This is useful if a website has a customer area that allows customers to update their payment information. Operation is identical to add except we only specify the fields we need to update, and we must provide customer id.

Update Example:

$customer_vault_id = '123456';
 
$vault = new nmiCustomerVault;
$vault->setCustomerVaultId($customer_vault_id);
 
$vault->update();
 
$result = $vault->execute();

Delete

Delete simply deletes a customer from our vault.

Delete Example:

$customer_vault_id = '123456';
 
$vault = new nmiCustomerVault;
$vault->setCustomerVaultId($customer_vault_id);
 
$vault->delete();
 
$result = $vault->execute();

Downloads

More complete examples are available in the downloaded class.

Download the full Network Merchant API Class Package
Download the Direct Post API Manual (Included in package)
Download the Customer Vault API Manual (Included in package)

Support

I do not provide direct support, however if you find any major bug please contact me, and I will get it fixed immediately.