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, 04/22/2025 © 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.
2/10/2025	Kenneth Syailendra	1.4	Added sandbox environment credentials.
4/22/2025	Randy Baldwin	1.5	Updated Pre-built UI layout and Options object.

Environment

PRODUCTION https://checkout.usiopay.com/2.0/

Production

https://checkout.usiopay.com/2.0/

Sandbox

https://devcheckout.usiopay.com/2.0/

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.

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	12345
Login	API12345
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="loadOptions()"/>
                    <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 loadOptions = function () {
                        var options = {
                                uiVersion: 2,
                                uiMode: 'popup',
                                headerColor: '002d62',
                                buttonColor: '002d62',
                                buttonText: 'Pay Now',
                                logoURL: '/img/logoipsum-logo.svg',
                                productTitle: 'Product Title',
                                productAmount: 10.00,
                                productUnit: 'Qty 1',
                                productDescription: 'Product information',
                                email: '',
                                paymentType1: 'creditcard',
                                paymentType2: 'ach',
                                footerText: 'Terms and Conditions',
                                iframeHeight: 500 //For Embedded UI Mode
                                };
                        LoadCheckout('AEAE82F9-5A34-47C3-A61E-1E8EE37BE3AD', options);
                        };

                        document.addEventListener("DOMContentLoaded", function () {
                        //window.onload = loadOptions(); //For Embedded UI Mode
                        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.

Checkout Pre-Built Demo Pages:

Popup Demo

Embedded Demo

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. A single payment type is required in either paymentType1 or paymentType2, but not in both.

            
        var options = {
            uiVersion: 2,
            uiMode: 'popup',
            headerColor: '#002d62',
            buttonColor: '002d62',
            buttonText: 'Pay Now',
            logoURL: '/img/logoipsum-logo.svg',
            productTitle: 'Product Title',
            productAmount: 10.00,
            productUnit: 'Qty 1',
            productDescription: 'Product information',
            email: '',
            paymentType1: 'creditcard',
            paymentType2: 'ach',
            footerText: 'Terms and Conditions',
            iframeHeight: 500
        };

Name	Required	Description
uiVersion	Required	Numeric version of the user-interface release. Default: 2
uiMode	Required	String value of the user-interface mode. Default: popup Options: popup (default), embedded
headerColor	Optional	Hexidecimal string value of the color used in the top banner. May contain prefixed # sign. Default: #ffffff00
buttonColor	Optional	Hexidecimal string value of the color used in the payment button. May contain prefixed # sign. Default: #000000
logoURL	Optional	String value of full URL to the logo used in the top banner. Image will be sized to fit, but smaller images will load faster. If this option is empty or excluded, the top banner will collapse.
productTitle	Optional	String value of product title.
productAmount	Optional	Decimal amount of product.
productUnit	Optional	String value of product unit.
productDescription	Optional	String value of product description.
email	Optional	String value of email address to pre-populate the field.
paymentType1	Required	String value of payment type. Options: creditcard, pinlesscredit, pinlessdebit
paymentType2	Required	String value of payment type. Options: ach, rcc
footerText	Optional	String value of footer text below payment button. If the option is empty or excluded, our default text will be used. To show no footer text, use the value of none.
iframeHeight	Optional	Numeric value of the iframe height preferred for Embedded UI Mode.

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