PHP Value Objects for Authorize.Net

The aim of this pacjage is to model, as value objects, all the data structures defined here: http://developer.authorize.net/api/reference/

The data structure for the API messages is defined in the XSD DTD. Although that is for the XSL API, the JSON API mirrors it closely. This DTD has been parsed into this documentation page using xs3p.xsl, which can be a little easier to read, and contains fewer errors than the official HTML documentation. Practically, use the two together.

General Project Stucture

The request messages are under Academe\AuthorizeNet\Request. All these requests take a Academe\AuthorizeNet\Auth\MerchantAuthentication object to provide authentication and one or more additional objects to carry the main message detail.

The Academe\AuthorizeNet\Request\CreateTransaction message takes a transaction object from under Academe\AuthorizeNet\Request\Transaction. The Transaction object is built mainly from scalar data and other objects under Academe\AuthorizeNet\Request\Model.

There are collections under Academe\AuthorizeNet\Collections used to group some of the Model objects, for example LineItems or UserFields. These Collections may be moved to Academe\AuthorizeNet\Request at some point, so be ready for that.

Note: this documentation is sparse at the moment, but the code covers much of the API.

Examples

One package that uses this package is the Authorize.Net API driver for the Omnipay project.

Further libraries can then wrap these objects into a gateway driver. Any request object, once constructed, can be serialised to JSON (json_encode()) to provide the body of the request that the API will expect.

The response from Authorize.Net will be a JSON structure, which can be parsed by the application. The intention is also to create a factory in this package that will parse the response into value objects and collections. Many of the response value objects have been created, but there is no factory yet to fill them up with data.

<?phpuseAcademe\AuthorizeNet;
useAcademe\AuthorizeNet\Auth;
useAcademe\AuthorizeNet\Amount;
useAcademe\AuthorizeNet\Payment;
useAcademe\AuthorizeNet\Request;
useAcademe\AuthorizeNet\Collections;
// Composer: moneyphp/moneyuseMoney\Money;
require'vendor/autoload.php';
echo"<pre>";
// Set up authorisation details.$auth = newAuth\MerchantAuthentication('xxx', 'yyy');
// Create a credit card.$credit_card = newPayment\CreditCard('4000123412341234', '1220', '123');
// Or create a magnetic stripe track (only one can be used).$track1 = newPayment\Track1('TTTTTTTTTTTTTTTT11111');
$track2 = newPayment\Track2('TTTTTTTT2222222222222222');
// Create order details.$order = newRequest\Model\Order('orderx', 'ordery');
// Create customer detals.$customer = newRequest\Model\Customer('business', 'Customer ID', 'customer@example.com');
// Create retail flags$retail = newRequest\Model\Retail(2, 3, 'HJSHDJSDJKSD');
// Create a billing name and address.$billTo = newRequest\Model\NameAddress('BFirstname', 'BLastname', null, 'Address Line');
$billTo = $billTo->withCompany('My Billing Company Ltd')->withZip('ZippyZipBill');
// Create a shipping name and address.$shipTo = newRequest\Model\NameAddress();
// A single with() can set multiple values at once.$shipTo = $shipTo->with([
'firstName' => 'Firstname',
'lastName' => 'Lastname',
'city' => 'My City',
'country' => 'United Kingdom',
]);
// Create a total amount of £24.99$amount = newAmount\Amount('GBP', 2499);
// Or maybe just £19.99$amount = $amount->withMajorUnit(19.99);
// Better still, use moneyphp/money to set the amount to £15.49$money_php_object = Money::GBP(1549);
$amount = newAmount\MoneyPhp($money_php_object);
// Create tax amount.// All parameters have a with*() method available.$tax = newRequest\Model\ExtendedAmount();
$tax = $tax->withName('Tax Name')->withDescription('Tax Description');
$tax = $tax->withAmount(newAmount\MoneyPhp(Money::GBP(99));
// Set up some line items.// Note these collections are not value objects. Should they be?$lineItems = newCollections\LineItems();
$lineItems->push(newRequest\Model\LineItem(1, 'Item Name 1', 'Item Desc 1', 1.5, newAmount\MoneyPhp(Money::GBP(49)), false));
$lineItems->push(newRequest\Model\LineItem(2, 'Item Name 2', 'Item Desc 2', 2, newAmount\MoneyPhp(Money::GBP(97)), true));
// Set up some transaction settings.$transactionSettings = newCollections\TransactionSettings();
$transactionSettings->push(newRequest\Model\Setting('Foo', 'Bar'));
// And add some user fields.$userFields = newCollections\UserFields();
$userFields->push(newRequest\Model\UserField('UserFoo', 'UserBar'));
// Now put most of these into an Auth Capture transaction.$auth_capture_transaction = newRequest\Transaction\AuthCapture($amount);
$auth_capture_transaction = $auth_capture_transaction->withPayment(/*$track1*/$credit_card);
$auth_capture_transaction = $auth_capture_transaction->withCreateProfile(false);
$auth_capture_transaction = $auth_capture_transaction->withTaxExempt(true);
$auth_capture_transaction = $auth_capture_transaction->withLineItems($lineItems);
$auth_capture_transaction = $auth_capture_transaction->withTransactionSettings($transactionSettings);
$auth_capture_transaction = $auth_capture_transaction->withUserFields($userFields);
$auth_capture_transaction = $auth_capture_transaction->withSolutionId('SOLLLL');
$auth_capture_transaction = $auth_capture_transaction->withTax($tax)->withDuty($tax)->withShipping($tax);
$auth_capture_transaction = $auth_capture_transaction->withPoNumber('myPoNumber');
$auth_capture_transaction = $auth_capture_transaction->withCustomer($customer);
$auth_capture_transaction = $auth_capture_transaction->withRetail($retail);
// You can set multiple items using an array:$auth_capture_transaction = $auth_capture_transaction->with([
'order' => $order,
'shipTo' => $shipTo,
'billTo' => $billTo,
'employeeId' => '1234',
'customerIp' => '1.2.3.4',
]);
// Add the auth capture transaction to the transaction request, along with the auth details.$transaction_request = newRequest\CreateTransaction($auth, $auth_capture_transaction);
// Display the resulting JSON request message.echo'<p>' . $transaction_request->getObjectName() . ': </p>';
echo"<textarea style='width:100%;height: 12em'>" . json_encode($transaction_request) . "</textarea>";
/*{ "createTransactionRequest":{ "merchantAuthentication":{ "name":"xxx", "transactionKey":"yyy" }, "refId":"REFREFREF", "transactionRequest":{ "transactionType":"authCaptureTransaction", "amount":"9.99", "currencyCode":"GBP", "payment":{ "creditCard":{ "cardNumber":"4000123412341234", "expirationDate":"1220", "cardCode":"123" } }, "profile":{ "createProfile":false }, "solution":{ "id":"SOLLLL" }, "order":{ "invoiceNumber":"orderx", "description":"ordery" }, "lineItems":{ "lineItem":[ { "itemId":1, "name":"Item Name 1", "description":"Item Desc 1", "quantity":1.5, "unitPrice":"0.49", "taxable":false }, { "itemId":2, "name":"Item Name 2", "description":"Item Desc 2", "quantity":2, "unitPrice":"0.97", "taxable":true } ] }, "tax":{ "amount":"9.99", "name":"Tax Name", "description":"Tax Description" }, "duty":{ "amount":"9.99", "name":"Tax Name", "description":"Tax Description" }, "shipping":{ "amount":"9.99", "name":"Tax Name", "description":"Tax Description" }, "taxExempt":true, "poNumber":"myPoNumber", "customer":{ "type":"business", "id":"Customer ID", "email":"customer@example.com" }, "billTo":{ "firstName":"BFirstname", "lastName":"BLastname", "company":"My Billing Company Ltd", "address":"Address Line", "zip":"ZippyZipBill" }, "shipTo":{ "firstName":"Firstname", "lastName":"Lastname", "city":"My City", "country":"United Kingdom" }, "customerIP":"1.2.3.4", "cardholderAuthentication":{ "authenticationIndicator":"AAAA" }, "retail":{ "marketType":2, "deviceType":3, "customerSignature":"HJSHDJSDJKSD" }, "employeeId":"1234", "transactionSettings":{ "setting":[ { "settingName":"Foo", "settingValue":"Bar" } ] }, "userFields":{ "userField":[ { "name":"UserFoo", "value":"UserBar" } ] } } }}*/

This can be sent to the gateway simply (and naively, just for demonstration) using Guzzle:

// "guzzlehttp/guzzle": "~6.0"useGuzzleHttp\Client;
$client = newGuzzleHttp\Client();
// sandbox endpoint$endpoint = 'https://apitest.authorize.net/xml/v1/request.api';
$response = $client->request('POST', $endpoint, [
// Just pass the object and Guzzle will cast it to JSON.'json' => $transaction_request,
]);
var_dump((string)$response->getBody());
/*{ "transactionResponse":{ "responseCode":"1", "authCode":"59WHY9", "avsResultCode":"Y", "cvvResultCode":"P", "transId":"60020301993", "refTransID":"", "transHash":"2EA6BB2D8D88C587EA16C77C44C7B8B2", "testRequest":"0", "accountNumber":"XXXX1234", "entryMode":"Keyed", "accountType":"Visa", "messages":[ { "code":"1", "description":"This transaction has been approved." } ], "userFields":[ { "name":"UserFoo", "value":"UserBar" } ], "transHashSha2":"" }, "refId":"5678917213", "messages":{ "resultCode":"Ok", "message":[ { "code":"I00001", "text":"Successful." } ] }}*/

This response data can then be parsed into nested objects:

$responseObject = new \Academe\AuthorizeNet\Response\Response(json_decode((string)$response->getBody(), true));