Introduction
USIO - Checkout 2.0 Documentation
USIO Checkout is an embedded payment form for desktop, tablet and mobile devices. You can accept both Credit/Debit cards and ACH. Using USIO Checkout allows direct site integration and removes PCI concerns. The experience is customizable with two different themes to match your site. Web service calls support REST/JSON.
In order for the pre-built Checkout UI to scale correctly on mobile devices, a meta tag must be included on the host page:
<meta name="viewport" content="user-scalable=no,width=device-width,initial-scale=1"/>
We strongly recommend implementing a login or reCAPTCHA before allowing users to enter and submit information.
Last updated on, 02/26/2024 © USIO.
Change Log
| Date | Author | Doc Version | Change Summary |
|---|---|---|---|
| 1/26/2022 | Brianna Keck & Connor Birch | 1.0 | Initial web release |
| 4/12/2022 | Brianna Keck | 1.1 | Demo documentation bug fixes |
| 5/03/2022 | Brianna Keck | 1.1 | Documentation response code additions |
| 8/25/2022 | Daniel Jackson | 1.2 | Added disableDuplicateCheck parameter to SubmitTokenPayment endpoint. |
| 2/26/2024 | Randy Baldwin | 1.3 | Added email to Pre-built UI Options. |
Environment
SANDBOX & PRODUCTION
https://checkout.usiopay.com/2.0/
Sandbox & Production
https://checkout.usiopay.com/2.0/
Our sandbox and production servers share the same URL.
The correct systems will be chosen based on the credentials submitted.
The Demo page is connected to our sandbox credentials and can be used to test payments. The test credentials below can be used to access the transaction details via API 2.0.
Checkout Demo Page:
https://checkout.usiopay.com/2.0/demo
Required Parameters in all Server Side calls
| Parameter Name | Description |
|---|---|
| MerchantID | Merchant ID assigned by USIO Systems |
| Login | API Username |
| Password | API Password |
Required Paramters for all Client Side calls
| Parameter Name | Description |
|---|---|
| MerchantKey | The MerchantKey(not merchantID, login, or password) |
Parameter Values for Sandbox
| Parameter Name | Test Value |
|---|---|
| MerchantID | 0000000001 |
| Login | API0000000001 |
| Password | Temp1234! |
| ApiKey | AEAE82F9-5A34-47C3-A61E-1E8EE37BE3AD |
If you require additional support please contact us at integrations@usio.com
Checkout Integration Guide
Pre-built UI
<html>
<head>
<meta name="viewport" content="user-scalable=no,width=device-width,initial-scale=1"/>
</head>
<body>
<input type="button" value="Pay Now" ID="payNow" onclick="buttonClick1()"/>
<div ID="USIOCheckout"></div>
<div ID="status"></div>
<div ID="token"></div>
<script src="https://checkout.usiopay.com/2.0/javascript/Checkout.js"></script>
<script>
var buttonClick1 = function () {
var options = {
paymentTypes: 'creditcard|ach',
submitButtonText: 'Pay Now',
pageText: 'Please enter your payment information',
logoURL: 'logo_usio.png',
theme: 'light',
email: ''
};
LoadCheckout('AEAE82F9-5A34-47C3-A61E-1E8EE37BE3AD', options);
};
document.addEventListener("DOMContentLoaded", function () {
window.onmessage = (event) => {
if (event.origin !== "https://checkout.usiopay.com")
return;
//Close USIO Checkout window
document.getElementById('USIOCheckout').innerHTML = '';
//Display status and token on page ***FOR DEMO PURPOSE ONLY***
document.getElementById('status').innerHTML = JSON.parse(event.data).status;
document.getElementById('token').innerHTML = JSON.parse(event.data).token;
//TODO SEND TOKEN TO SERVERSIDE CODE HERE
};
});
</script>
</body>
</html>
The pre-built UI is used to collect and securely send sensitive payment information to USIO.
Once the information has been validated, the script will return a token*.
The Checkout screen does not charge the customer.
You will then need to use the token to call our SubmitTokenPayment endpoint to complete the transaction.
*Tokens received from USIO Checkout are single use and will expire after 5 minutes.
You must call SubmitTokenPayment from your server-side code. Do not embed your merchant credentials in client-side code.
Host Page Sample
Your page must include the following:
- Meta tag (
<meta name="viewport" content="user-scalable=no,width=device-width,initial-scale=1" />) - Checkout.js script
-
Event source (typically an input element) with onclick event of LoadCheckout
- The LoadCheckout call requires your Merchant API Key (not your merchant id, login, or password), and an options object as described below
- A div on your page with an ID of "USIOCheckout"
-
Include a receiving script and send to your server
- The response will match object returned by GenerateToken
- This snippet of javascript is required to retrieve the Checkout Token from the pre-built UI and close the window.
Pre-built UI Options
Options Object
You must provide an options object to our LoadCheckout method in order to set up the pre-built UI. The options object will set up available payment types, button text, pop up title, pop up text, hosted logo url, theme, and email.
var options = {
paymentTypes: 'creditcard|ach',
submitButtonText: 'Pay Now',
pageTitle: 'USIO Checkout 2.0',
pageText: 'Please enter your payment information',
logoURL: 'logo_usio.png',
theme: 'light',
email: ''
};
| Name | Required | Description |
|---|---|---|
| paymentTypes | Required | Payment Types available in pre-built UI separated by pipes (valid types listed in table below) |
| submitButtonText | Optional | Text Displayed on Submit Button (Pay Now by default) |
| pageText | Optional | Text displayed on Checkout window near logo |
| logoURL | Required | Full URL to desired image on Checkout window |
| theme | Optional | Theme of Checkout window (light by default; valid theme names and examples listed below) |
| Optional | Pre-populate Email Address field(s) of the Checkout form |
Accepted Payment Types
| Payment Type | Description |
|---|---|
| ACH | E-Check |
| RCC | Remote Check Creation |
| CreditCard | Credit or Debit Cards |
| PinlessDebit | Debit Cards only |
| PinlessCredit | Send money to Debit Cards only |
Themes
| Name | Light Theme Sample | Dark Theme Sample |
|---|---|---|
| mobile |  |  |
| desktop |  |  |
Generate Token (Custom UI)
POST https://checkout.usiopay.com/2.0/GenerateToken
{
"MerchantKey": "string",
"PaymentType": "string",
"EmailAddress": "string",
"CardNumber": "string",
"ExpDate": "string",
"CVV": "string",
"RoutingNumber": "string",
"AccountNumber": "string",
"ACHAccountType": "string"
}
This method can be called from javascript on a client web page to generate a payment token*.
The transmissions of sensitive data is sent directly to Usio rather than passing it through your server.
This removes many of the PCI requirements.
The card information MUST be cleared from your form elements before submitting back to your servers. Failure to do so will bring you into PCI scope.
*Tokens received from the API call are single use and will expire after 5 minutes.
The above command returns the following JSON structure:
{
"Status": "string",
"PaymentType": "string",
"Token": "string",
"Message": "string",
"Last4": "string",
"ExpDate": "string",
"CardBrand": "string",
"AccountType": "string",
"EmailAddress": "string"
}
HTTP Request
POST https://checkout.usiopay.com/2.0/GenerateToken
Parameters
| Name | Type | Required | Length | Description |
|---|---|---|---|---|
| MerchantKey | string | Required | 18 | Merchant API Key |
| PaymentType | string | Required | Type of transaction from below Payment Types table | |
| EmailAddress | string | Required | 2-39 | Email Address of customer |
| CardNumber | string | Conditional | 13-16 | Credit/Debit card number |
| ExpDate | string | Conditional | 6 | Expiration Date of Card (MMYYYY) |
| CVV | string | Conditional | 3-4 | CVV/CVC code |
| RoutingNumber | string | Conditional | 9 | Routing number of customer |
| AccountNumber | string | Conditional | max 17 | Account number of customer |
| ACHAccountType | string | Conditional | 7-8 | Savings/Checking account |
Response
| Name | Type | Description |
|---|---|---|
| Status | string | "success" or "failure". |
| PaymentType | string | Payment type mirrored from request. |
| Token | string | USIO token to be used with Checkout's SubmitTokenPayment endpoint. Tokens expire after 5 minutes. |
| Message | string | If failure, provides error response. |
| Last4 | string | Last four digits of Account/Card number. |
| ExpDate | string | Expiration date of card (MMYYYY). |
| CardBrand | string | Brand of Credit/Debit card. |
| AccountType | string | ACH Account Type mirrored from request. |
| EmailAddress | string | Email Address mirrored from request. |
Accepted Payment Types
| Payment Type | Description |
|---|---|
| ACH | E-Check |
| RCC | Remote Check Creation |
| CreditCard | Credit or Debit Cards |
| PinlessDebit | Debit Cards only |
| PinlessCredit | Send money to Debit Cards only |
Sample HTML
Sample HTML
<form id="payment_form">
<div>
Email Address: <input ID="email_address"><br />
Card Number: <input ID="card_number"><br />
CVV: <input ID="card_cvv"><br />
Expiration: <input ID="card_exp"><br />
<button>Submit</button><br />
<div id="card_errors" role="alert"></div>
</div>
</form>
For all transaction types, you will need to collect the user's email address.
If accepting Credit/Debit Card transactions, you will need to create input fields for Card Number, CVV & Expiration Date.
For ACH/RCC transactions, you will need to have input fields for Account Number, Routing Number and a selection for Account Type.
It is also recommended that you have an area to display error messages.
Sample Javascript
Sample Javascript
<script type="text/javascript">
var form = document.getElementById('payment_form');
form.addEventListener('submit', function (event) {
event.preventDefault();
var emailAddress = document.getElementById('email_address');
var cardNumber = document.getElementById('card_number');
var cardCVV = document.getElementById('card_cvv');
var cardExp = document.getElementById('card_exp');
var errorElement = document.getElementById('card_errors');
//TODO: Client Side Field Validation
if (emailAddress == null || emailAddress.value.trim() == "") {
errorElement.textContent = "Invalid Email Address";
}
if (cardNumber == null || cardNumber.value.trim() == "") {
errorElement.textContent = "Invalid Card Number";
}
else if (cardCVV == null || cardCVV.value.trim() == "") {
errorElement.textContent = "Invalid CVV";
}
else if (cardExp == null || cardExp.value.trim() == "") {
errorElement.textContent = "Invalid Expiration Date";
}
else {
var xhttp = new XMLHttpRequest();
xhttp.onreadystatechange = function () {
if (this.readyState == 4 && this.status == 200) {
var response = JSON.parse(this.responseText);
if (response.status == "success") {
//Clear out PCI values
cardNumber.value = "";
cardCVV.value = "";
cardExp.value = "";
//Process Token
HandleToken(response.token);
}
else {
errorElement.textContent = response.message;
//TODO: handle errors
}
}
else {
//TODO: handle communication errors
}
};
xhttp.open("POST", "https://checkout.usiopay.com/2.0/GenerateToken", true);
xhttp.setRequestHeader("Content-type", "application/json");
var obj = '{ "merchantKey": "AEAE82F9-5A34-47C3-A61E-1E8EE37BE3AD", "paymentType": "creditcard", "emailAddress": "test@test.com", "cardNumber": "' +
cardNumber.value.trim() + '", "expDate": "' +
cardExp.value.trim() + '", "cvv": "' +
cardCVV.value.trim() + '" }';
xhttp.send(obj);
}
});
function HandleToken(token) {
// Insert the token ID into the form so it gets submitted to the server
var form = document.getElementById('payment_form');
var hiddenInput = document.createElement('input');
hiddenInput.setAttribute('type', 'hidden');
hiddenInput.setAttribute('name', 'Token');
hiddenInput.setAttribute('value', token);
form.appendChild(hiddenInput);
// Submit the form
form.submit();
}
</script>
The Javascript performs several steps:
- Intercepts the form's POST event and stops it from posting back to your server.
- Reads the values from the client side form.
-
Performs basic validation to make sure there is data available
- You may wish to do additional validation here
-
Packages those fields into a JSON string and sends them to the API
- Remember to use the correct Credit/Debit Card or ACH/RCC fields.
-
Receives response from the API.
- If successful, then the token is stored in a hidden element, the sensitive data is cleared, and the form is submitted.
- If it is a failure, the error message can be handled by your code.
API Integration
Submit Token Payment
POST https://checkout.usiopay.com/2.0/SubmitTokenPayment
{
"MerchantID": "string",
"Login": "string",
"Password": "string",
"Token": "string",
"Amount": "string",
"SecondaryAmount": "string",
"FirstName": "string",
"LastName": "string",
"Address1": "string",
"Address2": "string",
"City": "string",
"State": "string",
"Zip": "string",
"AdditionalSearch": "string",
"AccountCode1": "string",
"AccountCode2": "string",
"AccountCode3": "string",
"CheckNegativeAccount": false,
"AuthOnly": false,
"DisableDuplicateCheck": false
}
The above command returns the following JSON structure:
{
"Status": "string",
"Message": "string",
"Confirmation": "string"
}
This method is used to make a payment using a USIO Checkout token from the pre-built or custom UI.
In order to generate a permanent token, call this method with a $0.00 amount.
For ACH payments, in order to avoid submitting transactions against known bad accounts, use the checkNegativeAccount flag.
If you are set up to use convenience fees or split settlement fees, you may call our GetConvenienceFee endpoint from Payments API 2.0 with your merchant credentials (merchantID, login, password) and your temporary USIO Checkout token to obtain the correct minimum secondaryAmount to pass in this call.
HTTP Request
POST https://checkout.usiopay.com/2.0/SubmitTokenPayment
Parameters
| Name | Type | Required | Length | Description |
|---|---|---|---|---|
| MerchantID | string | Required | 6-10 | Merchant Identification Number |
| Login | string | Required | 6-12 | API Username |
| Password | string | Required | max 25 | API Password |
| Token | string | Required | 36 | USIO Token ID |
| Amount | string | Required | max 8 | Total Amount of Transaction including fees (#0.00) |
| SecondaryAmount | string | Required | max 6 | Secondary Amount to denote what portion of the amount field should be applied as a convenience fee/split settlement fee. |
| FirstName | string | Required | 2-19 | Card holder first name |
| LastName | string | Required | 2-19 | Card holder last name |
| Address1 | string | Required | 2-39 | Card holder address 1 |
| Address2 | string | Optional | 2-39 | Card holder address 2 |
| City | string | Required | 2-39 | Card holder city |
| State | string | Required | 2 | Card holder state |
| Zip | string | Required | 4-10 | Card holder zip code |
| AdditionalSearch | string | Optional | max 20 | Optional reporting field |
| AccountCode1 | string | Optional | max 20 | Optional reporting field |
| AccountCode2 | string | Optional | max 20 | Optional reporting field |
| AccountCode3 | string | Optional | max 20 | Optional reporting field |
| CheckNegativeAccount | bool | Optional | Request or skip negative accounts database check | |
| AuthOnly | bool | Optional | false = Sale Transaction, true = Auth Only | |
| DisableDuplicateCheck | bool | Optional | Disables check for duplicate payments. |
Response
| Name | Type | Description |
|---|---|---|
| Status | string | "success" or "failure" |
| Message | string | On failure will contain error code |
| Confirmation | string | Confirmation ID of payment |
API 2.0
Please click here for access to our API 2.0 documentation.
References
USIO Response Codes
USIO will return 5000 series response codes for errors that occur within our system. Most of these errors are for improper formatting of data
| Code | Description |
|---|---|
| 5000 | Security Violation |
| 5001 | System Failure |
| 5011 | Operation Not Valid On This Card |
| 5012 | Operation Not Available On This Transaction Type |
| 5050 | Invalid Amount |
| 5051 | Invalid Bank Account Type |
| 5053 | Invalid Email Address |
| 5054 | Invalid First Name |
| 5055 | Invalid Last Name |
| 5056 | Invalid Address |
| 5057 | Invalid Address 2 |
| 5058 | Invalid City |
| 5059 | Invalid State |
| 5060 | Invalid Zip Code |
| 5063 | Invalid Card Number |
| 5064 | Invalid Credit Card Type |
| 5065 | Invalid Expiration Date |
| 5066 | Invalid CVV |
| 5070 | Invalid Additional Search |
| 5071 | Invalid Account Code 1 |
| 5072 | Invalid Account Code 2 |
| 5073 | Invalid Account Code 3 |
| 5078 | Invalid Account Number |
| 5079 | Invalid Routing Number |
| 5086 | Card Brand is Not Supported |
| 5087 | Invalid Payment Type |
| 5096 | Invalid SEC |
| 5150 | Error Generating Token |
| 5151 | Invalid ACH Account Type |
| 5152 | Invalid Token |