apvanlaan / usaepay
Allows easy connection with and use of USAePay's REST API with Laravel
Requires
- illuminate/support: ~5|~6|~7|~8|~9
- usaepay/usaepay-php: ^2.0
Requires (Dev)
- mockery/mockery: ^1.1
- orchestra/testbench: ~3|~4
- phpunit/phpunit: ^8.0
- sempro/phpunit-pretty-print: ^1.0
- dev-master
- v1.1
- v1.0.10
- v1.0.9
- v1.0.8
- v1.0.7
- v1.0.6
- v1.0.5
- v1.0.4
- v1.0.3
- v1.0.2
- v1.0.1
- 1.0
- dev-dependabot/npm_and_yarn/minimist-1.2.8
- dev-dependabot/composer/symfony/http-kernel-4.4.50
- dev-dependabot/npm_and_yarn/json5-1.0.2
- dev-dependabot/npm_and_yarn/express-4.18.2
- dev-dependabot/npm_and_yarn/qs-and-express-6.11.0
- dev-dependabot/npm_and_yarn/decode-uri-component-0.2.2
- dev-dependabot/npm_and_yarn/loader-utils-and-resolve-url-loader-1.4.2
- dev-dependabot/npm_and_yarn/color-string-1.9.1
- dev-dependabot/npm_and_yarn/axios-0.21.2
- dev-dependabot/npm_and_yarn/eventsource-1.1.1
- dev-dependabot/npm_and_yarn/async-2.6.4
- dev-dependabot/npm_and_yarn/url-parse-1.5.10
- dev-dependabot/npm_and_yarn/follow-redirects-1.14.8
- dev-dependabot/npm_and_yarn/ajv-6.12.6
- dev-dependabot/npm_and_yarn/path-parse-1.0.7
- dev-dependabot/composer/league/flysystem-1.1.4
- dev-dependabot/npm_and_yarn/ws-6.2.2
- dev-dependabot/npm_and_yarn/dns-packet-1.3.4
- dev-dependabot/npm_and_yarn/browserslist-4.16.6
This package is auto-updated.
Last update: 2025-03-05 09:06:23 UTC
README
Project was created by, and is maintained by Aaron VanLaan.
Usage
Table Of Content
- Requirements
- Installation
- EpayCustomer Class
- EpayTransaction Class
- EpayBatch Class
- EpayProduct Class
- EpayCategory Class
- EpayInventory Class (COMING SOON)
- Examples
Requirements
This library uses PHP 7.4+ and Laravel 6+
You can find the USAePay Rest API docs here : https://help.usaepay.info/api/rest/
Installation
Require via Composer
$ composer require apvanlaan/usaepay
Publish Assets
$ php artisan vendor:publish --provider="Apvanlaan\UsaEpay\UsaEpayServiceProvider"
Add required ENV variables to .env
EPAYAPI=
#EPAYPIN= (optional, only include if pin is utilized)
EPAYPUBLIC=
EPAY_SUB=sandbox (change to secure for production)
#EPAY_ENDPOINT= (optional, use if using a custom endpoint, otherwise defaults to v2)
Note: In the following sections, the included routes relate to the controllers I have included in the package. If you end up rolling your own then obviously you can ignore those. The required fields, however, are required via the USAePay API, so those must remain.
EpayCustomer Class
The EpayCustomer Class handles the creation of the Customer object and the associated api calls.
Parameters
EpayCustomer parameters are: (note: all listed required are the minimum required by the USAePay API)
company
Stringfirst_name
Stringlast_name
Stringcustomerid
Stringstreet
Stringstreet2
city
Stringstate
Stringpostalcode
Stringcountry
Stringphone
Stringfax
Stringemail
Stringurl
Stringnotes
Stringdescription
Stringcustkey
String
EpayCustomer Methods w/ default required params and Examples
(note: there are two ways to instantiate the epay classes, you can pass an array/object with the paramters or you can instantiate an empty class and manually set the parameters as needed.)
getCustomer()
- Route :
GET epay/customer/get/{custkey}
- Required :
custkey
$customer = new EpayCustomer(); $customer->custkey = $custkey; return $customer->getCustomer();
listCustomers()
- Route :
GET epay/customer/list
- Required :
none
$customer = new EpayCustomer(); return $customer->listCustomers();
addCustomer()
- Route :
POST epay/customer/create
- Required :
company (if no first_name && last_name), first_name (if no company), last_name (if no company)
$customer = new EpayCustomer(); $params = ['first_name' =>"John",'last_name' =>"Doe",'street' =>"123 House Rd",'city' =>"Beverly Hills",'state' =>"CA",'postalcode' =>"90210",'country' =>"USA",'phone' =>"5558675309",'email' =>"john.doe@email.com",'description' =>"Fake customer information for testing."]; return $customer->addCustomer($params);
updateCustomer()
- Route :
POST epay/customer/update
- Required :
custkey
$customerUpdate = new \StdClass(); $customerUpdate->custkey = "asdf"; $customerUpdate->description = 'Still a fake customer used for testing'; $customer = new EpayCustomer($params); return $customer->updateCustomer();
deleteCustomer()
- Route :
POST epay/customer/delete
- Required :
custkey
$params = ['custkey'=>$request->custkey]; $customer = new EpayCustomer($params); return $customer->deleteCustomer();
EpayTransaction Class
The EpayTransaction Class handles the creation of the Transaction object and the associated api calls.
Parameters
EpayTransaction parameters are:
trankey
Stringrefnum
Stringinvoice
Stringponum
Stringorderid
Stringdescription
Stringcomments
Stringemail
Stringmerchemailaddr
Stringamount
Floatamount_detail
Transactions\EpayAmountDetailcreditcard
Transactions\EpayCreditCardsave_card
Booltraits
Transactions\EpayTraitcustkey
Stringsave_customer
Boolsave_customer_paymethod
Boolbilling_address
Transactions\EpayCustomerAddressshipping_address
Transactions\EpayCustomerAddresslineitmes
Transactions\EpayLineItemcustom_fields
Transactions\EpayCustomFieldcurrency
Stringterminal
Stringclerk
Stringclientip
Stringsoftware
String
EpayTransaction Methods w/ default required params
listAuthorized()
- Route :
GET epay/transaction/list
- Required :
none
listAuthorized()
- Route :
GET epay/transaction/list
- Required :
trankey
createSale()
- Route :
POST epay/transaction/sale
- Required :
amount, payment_key (if no creditcard), creditcard (if no payment_key)
createRefund()
- Required :
amount, creditcard
createVoid()
- Route :
POST epay/transaction/void
- Required :
trankey (if no refnum), refnum (if no trankey)
authorizeTransaction()
- Route :
POST epay/transaction/auth
- Required :
amount, payment_key (if no creditcard), creditcard (if no payment_key)
captureTransaction()
- Route :
POST epay/transaction/capture
- Required :
trankey (if no refnum), refnum (if no trankey)
EpayTransaction Child Classes
EpayAmountDetail Class & Parameters
subtotal
Doubletax
Doublenontaxable
Booltip
Doublediscount
Doubleshipping
Doubleduty
Doubleenable_partialauth
Bool
EpayCreditCard Class & Parameters
cardholder
Stringnumber
Stringexpiration
Stringcvc
Intavs_street
Stringavs_postalcode
String
EpayCustomerAddress Class & Parameters
company
Stringfirstname
Stringlastname
Stringstreet
Stringstreet2
Stringcity
Stringstate
Stringpostalcode
Stringcountry
Stringphone
Stringfax;
String
EpayLineItem Class & Parameters
product_key
Stringname
Stringcost
Doubleqty
Intdescription
Stringsku
Stringtaxable
Booltax_amount
Doubletax_rate
Stringdiscount_rate
Stringdiscount_amount
Doublelocation_key
Stringcommodity_code
String
EpayTrait Class & Parameters
is_debt
Boolis_bill_pay
Boolis_recurring
Boolis_healthcare
Boolis_cash_advance
Boolsecure_collection
Int
EpayBatch Class
The EpayBatch Class handles the creation of the Batch object and the associated api calls.
Parameters
EpayBatch parameters are:
limit
Intoffset
Intopenedlt
Stringopenedgt
Stringclosedlt
Stringclosedgt
Stringopenedle
Stringopenedge
Stringclosedle
Stringclosedge
Stringbatch_key
String
EpayBatch Methods w/ default required params
listBatches()
- Route :
GET epay/batch/list
- Required :
none
currentBatch()
- Route :
GET epay/batch/current
- Required :
none
retrieveBatch()
- Route :
POST epay/batch/retrieve
- Required :
batch_key
getCurrentBatchTransactions()
- Route :
GET epay/batch/currentTransactions
- Required :
none
getTransactionsByBatch()
- Route :
GET epay/batch/transactionsByBatch
- Required :
trankey (if no refnum), refnum (if no trankey)
closeBatch()
- Route :
POST epay/batch/close
- Required :
batch_key
EpayProduct Class
The EpayProduct Class handles the creation of the Product object and the associated api calls.
Parameters
name
Stringprice
Floatenabled
Booltaxable
Boolavailable_all
Boolavailable_all_date
Stringcategoryid
Intcommodity_code
Stringdate_available
Stringdescription
Stringlist_price
Floatwholesale_price
Floatmanufacturer
Stringmerch_productid
Stringmin_quantity
Intmodel
Stringphysicalgood
Boolweight
Intship_weight
Intsku
Stringtaxclass
Stringum
Stringupc
Stringurl
Stringallow_override
Boolproduct_key
Stringlimit
Intoffset
Intinventory
Arraymodifiers
Array
EpayProduct Methods w/ default required params
listProducts()
- Route :
GET epay/product/list
- Required :
none
createProduct()
- Route :
POST epay/product/create
- Required :
name
getProduct()
- Route :
GET epay/product/get
- Required :
product_key
updateProduct()
- Route :
POST epay/product/update
- Required :
product_key
deleteProduct()
- Route :
POST epay/product/delete
- Required :
product_key
EpayCategory Class
The EpayCategory Class handles the creation of the Category object and the associated api calls.
Parameters
name
Stringcategorykey
Stringlimit
Intoffset
Intmodifiers
Array
EpayCategory Methods w/ default required params
listCategories()
- Route :
GET epay/category/list
- Required :
none
createCategory()
- Route :
POST epay/category/create
- Required :
name
getCategory()
- Route :
GET epay/category/get
- Required :
category_key
updateCategory()
- Route :
POST epay/category/update
- Required :
category_key
deleteCategory()
- Route :
POST epay/category/delete
- Required :
category_key
EpayInventory Class
(COMING SOON)
Parameters (COMING SOON)
EpayInventory Methods w/ default required params (COMING SOON)
Examples
The following is an example of creating a View in Laravel that utilizes a Vue Component
Example View
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://www.usaepay.com/js/v1/pay.js"></script>
</head>
<body>
<div id='app'>
<div class='col'>
<h2>Payment/Auth Form</h2>
<paymentform publickey={{config('usaepay.publickey')}}></paymentform>
</div>
<div class='col'>
<h2>Transaction List</h2>
<transactionlist></transactionlist>
</div>
</div>
</body>
<script src="{{ asset('js/app.js') }}"></script>
</html>
Example Vue Component
<template>
<div>
<form class='paymentForm' @submit.prevent='submitForm'>
<div class='form-group'>
<label for='saveCust'>Save Customer?</label>
<input type='checkbox' name='saveCust' v-model='saveCust' />
</div>
<div class='form-group'>
<label for='type'>Transaction Type</label>
<div class='form-group'>
<label>Authorization <input type='radio' value='auth' name='type' v-model='transaction.type' /></label>
</div>
<div class='form-group'>
<label>Sale <input type='radio' value='sale' name='type' v-model='transaction.type' /></label>
</div>
</div>
<div class='form-group'>
<label for='amount'>Amount : ${{transaction.amount}}</label>
</div>
<div class='form-group'>
<label for="email">Email</label>
<input type="email" v-model="transaction.email" required/>
</div>
<div id='shipping_address'>
<div class='form-group'>
<label class='label' for="company">Company</label>
<input type="text" name="company" v-model='transaction.shipping_address.company' />
</div>
<div class='form-group'>
<label class='label' for="firstname">First Name</label>
<input type="text" name="firstname" v-model='transaction.shipping_address.firstname' />
</div>
<div class='form-group'>
<label class='label' for="lastname">Last Name</label>
<input type="text" name="lastname" v-model='transaction.shipping_address.lastname' />
</div>
<div class='form-group'>
<label class='label' for="street">Address</label>
<input type="text" name="street" v-model='transaction.shipping_address.street' required/>
</div>
<div class='form-group'>
<label class='label' for="street2">Apt / Building</label>
<input type="text" name="street2" v-model='transaction.shipping_address.street2' />
</div>
<div class='form-group'>
<label class='label' for="city">City</label>
<input type='text' name='city' v-model='transaction.shipping_address.city' required/>
</div>
<div class='form-group'>
<label class='label' for="state">State</label>
<input type="text" name="state" v-model='transaction.shipping_address.state' required/>
</div>
<div class='form-group'>
<label class='label' for="postalcode">Zip</label>
<input type="text" name="postalcode" v-model='transaction.shipping_address.postalcode' required/>
</div>
<div class='form-group'>
<label class='label' for="country">Country</label>
<select name="country" v-model='transaction.shipping_address.country' required>
<option value="Select Country">Select Country</option>
<option value="US">US</option>
<option value="CA">Canada</option>
</select>
</div>
<div class='form-group'>
<label class='label' for="phone">Phone#</label>
<input type="text" name="phone" v-model='transaction.shipping_address.phone' />
</div>
</div>
<div class='form-group'>
<label class='label' for='diffBilling'>Different Billing Address?</label>
<input type='checkbox' name='diffBilling' v-model='diffBilling'/>
</div>
<div v-if="diffBilling == true" id='billing_address'>
<div class='form-group'>
<label class='label' for="company">Company</label>
<input type="text" name="company" v-model='transaction.billing_address.company' /></div>
<div class='form-group'>
<label class='label' for="firstname">First Name</label>
<input type="text" name="firstname" v-model='transaction.billing_address.firstname' /></div>
<div class='form-group'>
<label class='label' for="lastname">Last Name</label>
<input type="text" name="lastname" v-model='transaction.billing_address.lastname' /></div>
<div class='form-group'>
<label class='label' for="street">Address</label>
<input type="text" name="street" v-model='transaction.billing_address.street' required/></div>
<div class='form-group'>
<label class='label' for="street2">Apt / Building</label>
<input type="text" name="street2" v-model='transaction.billing_address.street2' /></div>
<div class='form-group'>
<label class='label' for="city">City</label>
<input type='text' name='city' v-model='transaction.billing_address.city' required/></div>
<div class='form-group'>
<label class='label' for="state">State</label>
<input type="text" name="state" v-model='transaction.billing_address.state' required/></div>
<div class='form-group'>
<label class='label' for="postalcode">Zip</label>
<input type="text" name="postalcode" v-model='transaction.billing_address.postalcode' required/></div>
<div class='form-group'>
<label class='label' for="country">Country</label>
<select name="country" v-model='transaction.billing_address.country' required>
<option value="Select Country">Select Country</option>
<option value="US">US</option>
<option value="CA">Canada</option>
</select>
</div>
<div class='form-group'>
<label for="phone">Phone#</label>
<input type="text" name="phone" v-model='transaction.billing_address.phone' /></div>
</div>
<creditcard ref='cc' :publickey=publickey></creditcard>
<button type='submit'>Submit</button>
</form>
<div>Results : <pre>{{results}}</pre></div>
</div>
</template>
<script>
export default {
props: ['publickey'],
data() {
return {
transaction:{
billing_address:{
company:'',
firstname:'',
lastname:'',
street:'',
street2:'',
city:'',
state:'',
postalcode:'',
country:'',
phone:'',
},
shipping_address:{
company:'',
firstname:'',
lastname:'',
street:'',
street2:'',
city:'',
state:'',
postalcode:'',
country:'',
phone:'',
},
lineitems:[
{
name: "Test1",
cost: 3.50,
qty: 2,
description: "This is the first test item."
},
{
name: "Test2",
cost: 3.75,
qty: 1,
description: "This is the second test item."
}
],
email:'',
type:'auth',
amount:3.5,
},
diffBilling:false,
results:'',
results_output:'',
payment_key:'',
saveCust:false,
}
},
methods: {
submitForm(){
var self = this;
self.$refs.cc.errormsg = '';
var client = this.$refs.cc.client;
var paymentCard = this.$refs.cc.paymentCard;
if(!self.diffBilling){
self.transaction.billing_address = self.transaction.shipping_address;
}
client.getPaymentKey(paymentCard).then(result => {
if (result.error) {
self.$refs.cc.errormsg = result.error.message;
} else {
// do something with your payment key
self.payment_key = result;
}
self.transaction.payment_key = self.payment_key;
if(self.saveCust == true){
self.transaction.save_customer = 1;
}
axios.post('api/epay/transaction/' + self.transaction.type,self.transaction).then(function(response){
self.results = response.data;
if(self.saveCust == true){
axios.get('api/epay/customer/get/' + response.data.customer.custkey).then(function(customer){
self.results.customer = customer.data;
})
}
self.results_output = JSON.stringify(response.data,null,2);
})
.catch(function(error){
console.log(error.response.data.message);
self.$refs.cc.errormsg = "An error has occurred. Please check the form and try again.\r\n Error Message: " + error.response.data.message;
});
});
},
},
watch:{
},
computed: {
},
mounted: function(){
}
}
</script>
<style>
.paymentForm{width:300px;}
</style>
Change log
Please see the changelog for more information on what has changed recently.
Contributing
Please see contributing.md for details and a todolist.
Credits
License
The USAePay REST API Package for Laravel is open-sourced software licensed under the MIT license.