Payment Gateway JavaScript Client Library
Introduction
NPM package used to interface your website with Source Allies Payment Gateway. The developer documentation for this package can be found here. A tutorial of how to integrate Payment Gateway with your website can be found here.
Getting Started
In HTML File
Add a
<script>tag in the head of your html file that references the published JavaScript bundle.<html> <head> <script src="https://unpkg.com/@sourceallies/payment-gateway@latest/dist/payment-gateway.umd.js" ></script> </head> </html>You should replace
@latestwith the current version of the NPM package that can be found in the badge above that saysNPM Package(e.g. the badge says 0.3.2, then replace@latestwith@0.3.2).You can then start calling the functions in the form of
paymentGateway.FUNCTION_NAME(). Here is an example of usage:<html> <head> <script src="https://unpkg.com/@sourceallies/payment-gateway@latest/dist/payment-gateway.umd.js" ></script> <script> const encryptedPaymentData = paymentGateway.encryptPaymentData( response, authorizeNetApiKey, paymentData ); </script> </head> </html>
Node Modules
Run
npm install @sourceallies/payment-gatewayto install. You can use any package manager you prefer.Import the package using the following statement:
import * as paymentGateway from '@sourceallies/payment-gateway';Start calling functions in the package. Here is an example of usage:
import * as paymentGateway from '@sourceallies/payment-gateway'; const encryptedPaymentData = paymentGateway.encryptPaymentData( response, authorizeNetApiKey, paymentData );
This package can also be used with TypeScript. The typings are included in the package. This package is bundled using ES module format. We highly recommend you pass in every parameter and property to the functions. Not including parameters or properties can cause unexpected behavior
Extended Usage
After you follow the Getting Started section, you can begin using the functions included in the package. Here are examples of more extended usages.
Single Transaction
<form action="javascript:handleSubmit()">
<label for="invoice_number">Invoice Number</label>
<input id="invoice_number" type="text" value="1">
<label for="amount">Amount</label>
<input id="amount" type="text" value="1.00">
<label for="email_address">Email</label>
<input type="email" id="email_address" value="email@email.com"></label>
<label for="cardholder-name">Cardholder Name</label>
<input id="cardholder-name" type="text" value="FirstName LastName">
<label for="card-number">Card Number</label>
<input id="card-number" type="text" maxlength="16" minlength="16" value="4111111111111111">
<label for="card-expiration">Card Expiration (eg: 01/21)</label>
<input id="card-expiration" type="text" maxlength="5" minlength="4" value="01/23">
<label for="card-code">Card Code</label>
<input id="card-code" type="text" maxlength="4" minlength="3" value="123">
<label for="street-address">Street Address</label>
<input id="street-address" type="text" value="104 First Street">
<label for="city">City</label>
<input id="city" type="text" value="Urbandale">
<label for="state">State</label>
<input id="state" type="text" value="IA">
<label for="zipcode">Zip Code</label>
<input id="zipcode" type="text" minlength="5" value="12345">
<button type="submit">Submit</button>
</form>
<script
src="https://jstest.authorize.net/v1/Accept.js">
</script>
<script
src="https://unpkg.com/@sourceallies/payment-gateway@latest/dist/payment-gateway.umd.js">
</script>
<script>
// Your information to link the payments to your Payment Gateway account.
const gatewayData = {
partnerName: "YOUR PARTNER NAME",
gatewayName: "YOUR GATEWAY NAME"
};
// Specifies the environment to be used when Payment Gateway makes requests.
// This can be set to "DEV" or "PROD".
const environment = "DEV";
// Your key to access Authorize.Net's API.
const authorizeNetAPIKey = "YOUR AUTHORIZE.NET API KEY";
/**
* Handles the result from submitting the transaction with Payment Gateway.
*/
function handlePaymentGatewayProcessTransactionResponse(xmlHttpRequest) {
if (xmlHttpRequest && xmlHttpRequest.status === 200) {
const responseBody = JSON.parse(xmlHttp.response);
// Replace this with custom response handling that checks for an "OK"
// responseCode.
console.log(responseBody);
} else {
// You would end up in this error block if the response from Payment
// Gateway does not have a status of "200". You will want to handle
// this case with custom error handling for your website.
console.error("Error when processing the transaction.");
}
}
/**
* Submits the transaction request to Payment Gateway.
*/
function submitTransactionRequest(response) {
if (response.messages.resultCode === "Error") {
console.error(response.messages.message);
return;
}
const amount = document.getElementById("amount").value
const billTo = {
firstName: document.getElementById("first_name").value,
lastName: document.getElementById("last_name").value,
address: document.getElementById("address").value,
city: document.getElementById("city").value,
state: document.getElementById("state").value,
zip: document.getElementById("zip_code").value,
country: document.getElementById("country").value
};
const customer = {
email: document.getElementById("email").value
};
const order = {
description: "Description",
// This is not required. If you would like to include it, you can
// randomly generate it.
invoiceNumber: "SOME INVOICE NUMBER"
};
const requestData = paymentGateway.buildRequestData(
response,
amount,
billTo,
customer,
order
);
paymentGateway.processTransactionRequest(
handlePaymentGatewayProcessTransactionResponse,
requestData,
gatewayData,
environment.toUpperCase() /*,
optionally pass in lineItems */
);
};
/**
* Handles the response of the HTTP request to obtain an Authorize.Net
* cipher key.
*/
function handleGetMerchantDetails(xmlHttpRequest) {
if (xmlHttpRequest && xmlHttpRequest.status && xmlHttpRequest.status === 200) {
const responseBody = JSON.parse(xmlHttpRequest.response);
if (responseBody.messages.resultCode !== "OK") {
// Replace this with custom error handling for your website.
console.error("Bad response.");
// This breaks out of the current function so the code below is not ran.
return;
}
// This can be either cardData or bankData. This paymentData object
// is the cardData type.
const paymentData = {
cardNumber: document.getElementById("card-number").value,
cardExpiration: document.getElementById("card-expiration").value,
cardCode: document.getElementById("card-code").value,
fullName: document.getElementById("cardholder-name").value,
zip: document.getElementById("zipcode").value
};
// Encrypts the payment data so it is secure when sending it to Payment Gateway.
const secureData = paymentGateway.encryptPaymentData(
responseBody,
authorizeNetAPIKey,
paymentData
);
Accept.dispatchData(secureData, submitTransactionRequest);
} else {
// You would end up in this error block if the response from Payment
// Gateway does not have a status of "200". You will want to handle
// this case with custom error handling for your website.
console.error("Bad response.");
}
}
function handleSubmit() {
paymentGateway.getMerchantDetails(
handleGetMerchantDetails,
gatewayData,
environment
);
}
</script>Recurring Transacion (Subscription)
<form action="javascript:handleSubmit()">
<label for="invoice_number">Invoice Number</label>
<input id="invoice_number" type="text" value="1">
<label for="amount">Amount</label>
<input id="amount" type="text" value="1.00">
<label for="email_address">Email</label>
<input type="email" id="email_address" value="email@email.com"></label>
<label for="cardholder-name">Cardholder Name</label>
<input id="cardholder-name" type="text" value="FirstName LastName">
<label for="card-number">Card Number</label>
<input id="card-number" type="text" maxlength="16" minlength="16" value="4111111111111111">
<label for="card-expiration">Card Expiration (eg: 01/21)</label>
<input id="card-expiration" type="text" maxlength="5" minlength="4" value="01/23">
<label for="card-code">Card Code</label>
<input id="card-code" type="text" maxlength="4" minlength="3" value="123">
<label for="street-address">Street Address</label>
<input id="street-address" type="text" value="104 First Street">
<label for="city">City</label>
<input id="city" type="text" value="Urbandale">
<label for="state">State</label>
<input id="state" type="text" value="IA">
<label for="zipcode">Zip Code</label>
<input id="zipcode" type="text" minlength="5" value="12345">
<label id="frequency_label" for="frequency">Frequency</label>
<select type="text" id="frequency" value="1">
<option value="1">Monthly</option>
<option value="3">Quarterly</option>
<option value="6">Every Six Months</option>
<option value="12">Annually</option>
</select>
<label id="payment_number_label" for="payment_number">Number of Payments</label>
<input type="text" id="payment_number" value="1">
<label id="first_payment_date_label" for="first_payment_date">Start Date (mm/dd/yyyy)</label>
<!-- Please note that an input of type date has a date picker in Chrome and Firefox, not in Safari or IE -->
<!-- Also, Chrome and Firefox will store the value as yyyy-mm-dd, where as Safari and IE will store the value as typed by the user -->
<input type="date" id="first_payment_date" title="Pick a date for payments to start." placeholder="mm/dd/yyyy" pattern="^(((0?[1-9]|1[012])\/(0?[1-9]|1\d|2[0-8])|(0?[13456789]|1[012])\/(29|30)|(0?[13578]|1[02])\/31)\/(19|[2-9]\d)\d{2}|0?2\/29\/((19|[2-9]\d)(0[48]|[2468][048]|[13579][26])|(([2468][048]|[3579][26])00)))$" class="s" value="06/04/2020">
<button type="submit">Submit</button>
</form>
<script
src="https://jstest.authorize.net/v1/Accept.js">
</script>
<script
src="https://unpkg.com/@sourceallies/payment-gateway@latest/dist/payment-gateway.umd.js">
</script>
<script>
// Your information to link the payments to your Payment Gateway account.
const gatewayData = {
partnerName: "YOUR PARTNER NAME",
gatewayName: "YOUR GATEWAY NAME"
};
// Specifies the environment to be used when Payment Gateway makes requests.
// This can be set to "DEV" or "PROD".
const environment = "DEV";
// Your key to access Authorize.Net's API.
const authorizeNetAPIKey = "YOUR AUTHORIZE.NET API KEY";
/**
* Handles the result from submitting the subscription with Payment Gateway.
*/
function handlePaymentGatewayProcessSubscriptionResponse(xmlHttpRequest) {
if (xmlHttpRequest && xmlHttpRequest.status && xmlHttpRequest.status === 200) {
const responseBody = JSON.parse(xmlHttp.response);
// Replace this with custom response handling that checks for an "OK"
// responseCode.
console.log(responseBody);
} else {
// You would end up in this error block if the response from Payment
// Gateway does not have a status of "200". You will want to handle
// this case with custom error handling for your website.
console.error("Error when processing the subscription.");
}
}
/**
* Submits the subscription request to Payment Gateway.
*/
function submitSubscriptionRequest(response) {
if (response.messages.resultCode === "Error") {
console.error(response.messages.message);
return;
}
const amount = document.getElementById("amount").value;
const billTo = {
firstName: document.getElementById("first_name").value,
lastName: document.getElementById("last_name").value,
address: document.getElementById("address").value,
city: document.getElementById("city").value,
state: document.getElementById("state").value,
zip: document.getElementById("zip_code").value,
country: document.getElementById("country").value
};
const customer = {
email: document.getElementById("email").value
};
const order = {
description: "Description",
// This is not required. If you would like to include it, you can
// randomly generate it.
invoiceNumber: "SOME INVOICE NUMBER"
};
const paymentSchedule = {
interval: {
length: document.getElementById("frequency").value,
unit: "MONTHS"
},
startDate: document.getElementById("first_payment_date").value,
totalOccurrences: document.getElementById("payment_number").value
};
const requestData = paymentGateway.buildRequestData(
response,
amount,
billTo,
customer,
order
);
paymentGateway.processSubscriptionRequest(
handlePaymentGatewayProcessSubscriptionResponse,
requestData,
gatewayData,
paymentSchedule,
environment.toUpperCase() /*,
optionally pass in lineItems */
);
};
/**
* Handles the response of the HTTP request to obtain an Authorize.Net
* cipher key.
*/
function handleGetMerchantDetails(xmlHttpRequest) {
if (xmlHttpRequest && xmlHttpRequest.status === 200) {
const responseBody = JSON.parse(xmlHttpRequest.response);
if (responseBody.messages.resultCode !== "OK") {
// Replace this with custom error handling for your website.
console.error("Bad response.");
// This breaks out of the current function so the code below is not ran.
return;
}
// This can be either cardData or bankData. This paymentData object
// is the cardData type.
const paymentData = {
cardNumber: document.getElementById("card-number").value,
cardExpiration: document.getElementById("card-expiration").value,
cardCode: document.getElementById("card-code").value,
fullName: document.getElementById("cardholder-name").value,
zip: document.getElementById("zipcode").value
};
// Encrypts the payment data so it is secure when sending it to Payment Gateway.
const secureData = paymentGateway.encryptPaymentData(
responseBody,
authorizeNetAPIKey,
paymentData
);
Accept.dispatchData(secureData, submitSubscriptionRequest);
} else {
// You would end up in this error block if the response from Payment
// Gateway does not have a status of "200". You will want to handle
// this case with custom error handling for your website.
console.error("Bad response.");
}
}
function handleSubmit() {
paymentGateway.getMerchantDetails(
handleGetMerchantDetails,
gatewayData,
environment
);
}
</script>