NAV Navbar

Logo

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

DateAuthorDoc VersionChange 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 calls

Parameter NameDescription
MerchantID Merchant ID assigned by USIO Systems
Login API Username
Password API Password

Parameter Values for Sandbox

Parameter NameTest 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:

  1. Meta tag (<meta name="viewport" content="user-scalable=no,width=device-width,initial-scale=1" />)
  2. Checkout.js script
  3. 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
  4. A div on your page with an ID of "USIOCheckout"
  5. 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: ''
        };
NameRequiredDescription
paymentTypesRequiredPayment Types available in pre-built UI separated by pipes (valid types listed in table below)
submitButtonTextOptionalText Displayed on Submit Button (Pay Now by default)
pageTextOptionalText displayed on Checkout window near logo
logoURLRequiredFull URL to desired image on Checkout window
themeOptionalTheme of Checkout window (light by default; valid theme names and examples listed below)
emailOptionalPre-populate Email Address field(s) of the Checkout form

Accepted Payment Types

Payment TypeDescription
ACH E-Check
RCC Remote Check Creation
CreditCard Credit or Debit Cards
PinlessDebit Debit Cards only
PinlessCredit Send money to Debit Cards only

Themes

NameLight Theme SampleDark 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

NameTypeRequiredLengthDescription
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
ExpDatestring Conditional 6 Expiration Date of Card (MMYYYY)
CVVstring Conditional 3-4 CVV/CVC code
RoutingNumberstring Conditional 9 Routing number of customer
AccountNumberstring Conditional max 17 Account number of customer
ACHAccountTypestring Conditional 7-8 Savings/Checking account

Response

NameTypeDescription
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 TypeDescription
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:

  1. Intercepts the form's POST event and stops it from posting back to your server.
  2. Reads the values from the client side form.
  3. Performs basic validation to make sure there is data available
    • You may wish to do additional validation here
  4. 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.
  5. 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

NameTypeRequiredLengthDescription
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
DisableDuplicateCheckbool Optional Disables check for duplicate payments.

Response

NameTypeDescription
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

CodeDescription
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
5151 Invalid ACH Account Type
5152 Invalid Token