NAV Navbar

Logo

Introduction

USIO - Hosted Payment Pages 2.0 Documentation

USIO Hosted Payment Pages allows you to easily set up payment options without having to handle sensitive information.
This API allows you to simply generate prefilled pages, such as invoices.
These pages support all of our payment options and allow features such as custom fields and designations.

Last updated on, 02/10/2025 © USIO.

Change Log

DateAuthorDoc VersionChange Summary
07/15/2021 Brianna Keck & Connor Birch 2.0 Initial web release
08/24/2021 Connor Birch 2.1 Improved documentation for Prefill Page, added Demo sites
08/31/2021 Connor Birch 2.2 Updated Prefill Page Documentation
10/12/2021 Brianna Keck 2.3 Updated Query String Prefill Page Documentation
01/18/2022 Brianna Keck 2.4 Updated Documentation to include Account Code information
05/17/2022 Brianna Keck 2.5 Added documentation for new Disable Prefill Page endpoint
10/16/2024 Kenneth Syailendra 2.6 Added documentation for new Webhook
02/10/2025 Kenneth Syailendra 2.7 Added sandbox environment credentials

Environment

PRODUCTION https://hosted.usiopay.com/

Production

https://hosted.usiopay.com/

Sandbox

https://devhosted.usiopay.com/

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 12345
Login API12345
Password Temp1234!

Demo Hosted Payment Pages

Page TitlePage IDDescription
USIO Demo Page C1BB61B3-46D1-4723-829D-43FDC3FD45FF USIO HPP with invoice and scheduled payment options.
Basic Demo Page1610F4B2-16D1-4AF7-9CDA-619939600401 Basic HPP with only a single payment option.
Church Demo PageE74CE343-5D88-4DD1-8810-DD085B9497A3Fully customized HPP with scheduled payment options and custom fields.

Please click the Page ID of the demo page you wish to test. Pages are on the test account and can be used to test payments. The test credentials above can be used to access the transaction details via API 2.0.

If you require additional support, please contact us at integrations@usio.com

Hosted Payment Page Calls

Prefill Page

POST https://hosted.usiopay.com/api/PrefillPage

			
{
	"merchantID": "string",
	"login": "string",
	"password": "string",
	"guid": "string",	
	"amount": "string",
	"lockAmount": false,	
	"firstName": "string",
	"lastName": "string",
	"emailAddress": "string",
	"addressLine1": "string",
	"addressLine2": "string",
	"city": "string",
	"state": "string",
	"zip": "string",		
	"custom1": "string",
	"custom2": "string",
	"custom3": "string",
	"custom4": "string",
	"custom5": "string",
	"designation1Purpose": "string",
	"designation1Amount": "string",
	"designation2Purpose": "string",
	"designation2Amount": "string",
	"designation3Purpose": "string",
	"designation3Amount": "string",		
	"accountCode1": "string",		
	"accountCode2": "string",		
	"accountCode3": "string"
}

The above command returns the following JSON structure:

			
{
	"Status": "string",
	"Message": "string",
	"URL": "string"
}

This method is used to prepare a Hosted Payment Page. (Example: Invoice)

HTTP Request

POST https://hosted.usiopay.com/api/PrefillPage

Parameters

NameTypeRequiredLengthDescription
merchantID string Required 6-10 Merchant Identification Number
login string Required 6-12 API Username
password string Required max 25 API Password
guid string Required 36 Site GUID (Site ID)
amountstring Optional max 5 This prefills the amount field (#0.00).
lockAmountbool Optional max 8 This locks the amount field.("true"/"false")
firstNamestring Optional max 19 This prefills the first name field.
lastNamestring Optional max 19 This prefills the last name field.
emailAddressstring Optional max 39 This prefills the email address field.
addressLine1string Optional max 39 This prefills the address line 1 field.
addressLine2string Optional max 39 This prefills the address line 2 field.
citystring Optional max 39 This prefills the city field.
statestring Optional max 2 This prefills the state field.
zipstring Optional max 10 This prefills the zip code field.
custom1string Optional max 39 This prefills the first custom field value.
custom2string Optional max 39 This prefills the second custom field value.
custom3string Optional max 39 This prefills the third custom field value.
custom4string Optional max 39 This prefills the fourth custom field value.
custom5string Optional max 39 This prefills the fifth custom field value.
designation1Purposestring Optional max 39 This prefills the first designation purpose field.
designation1Amountstring Optional max 8 This prefills the first designation amount field.
designation2Purposestring Optional max 39 This prefills the second designation purpose field.
designation2Amountstring Optional max 8 This prefills the second designation amount field.
designation3Purposestring Optional max 39 This prefills the third designation purpose field.
designation3Amountstring Optional max 8 This prefills the third designation amount field.
accountCode1string Optional max 20 This prefills the first account code field.
accountCode2string Optional max 20 This prefills the second account code field.
accountCode3string Optional max 20 This prefills the third account code field.

Response

NameTypeDescription
Status string "success" or "failure"
Message string On failure will contain the error description
URL string Link to prefilled page

Disable Prefill Page

POST https://hosted.usiopay.com/api/DisablePrefillPage

			
{
	"merchantID": "string",
	"login": "string",
	"password": "string",
	"guid": "string"
}

The above command returns the following JSON structure:

			
{
	"Status": "string",
	"Message": "string",
}

This method is used to disable an existing Prefill Page that has NOT been utilized yet.

HTTP Request

POST https://hosted.usiopay.com/api/DisablePrefillPage

Parameters

NameTypeRequiredLengthDescription
merchantID string Required 6-10 Merchant Identification Number
login string Required 6-12 API Username
password string Required max 25 API Password
guid string Required 36 ID from the prefill page, not the Site ID

Response

NameTypeDescription
Status string "success" or "failure"
Message string On failure will contain the error description

HPP Query Strings

If you do not want to prefill a page, these query strings are available for these fields.
Below are the fields you can fill with a query string; if it is not on this list, it cannot be filled with a query string.

FieldDescription
FirstName This prefills the first name field.
LastName This prefills the last name field.
Email This prefills the email address field.
Addr1 This prefills the address line 1 field.
Addr2 This prefills the address line 2 field.
City This prefills the city field.
State This prefills the state field.
Zip This prefills the zip code field.
Amount This prefills the amount field.
Custom1 This prefills the first custom field value.
Custom2 This prefills the second custom field value.
Custom3 This prefills the third custom field value.
Custom4 This prefills the fourth custom field value.
Custom5 This prefills the fifth custom field value.
AccountCode1This sets the first account code value.
AccountCode2This sets the second account code value.
AccountCode3This sets the third account code value.

To begin a query string, type a '?' after the site ID, followed by the field you want to set. Fields are separated by '&'.
  EX: /{siteID}?firstname=Jane&lastname=Doe&amount=12.34

Webhooks

Information will be POSTed to the webhook URL in the following JSON structure: 

			
	{
		"guid": "string",
		"siteName": "string",
		"confirmation": "string",
		"amount": 0.00,	
		"convFee": 0.00,
		"netAmount": 0.00,	
		"paymentMethod": "string",
		"paymentFrequency": "string",
		"paymentDate": "string",
		"firstName": "string",
		"lastName": "string",
		"emailAddress": "string",
		"addressLine1": "string",
		"addressLine2": "string",
		"city": "string",
		"state": "string",
		"zip": "string",		
		"custom1": "string",
		"custom2": "string",
		"custom3": "string",
		"custom4": "string",
		"custom5": "string",
		"designation1Purpose": "string",
		"designation1Amount": 0.00,
		"designation2Purpose": "string",
		"designation2Amount": 0.00,
		"designation3Purpose": "string",
		"designation3Amount": 0.00,		
		"accountCode1": "string",		
		"accountCode2": "string",		
		"accountCode3": "string"
	}

If you have provided a webhook URL in your HPP Configuration, a payload containing transaction details will be sent to that address whenever a transaction is successfully completed. Details of the payload are described below:

FieldTypeDescription
guid string This returns the Site GUID (Site ID).
siteName string This returns the Site Name.
confirmation string This returns the Transaction Confirmation ID.
amount decimal This returns the Transaction Amount.
convFee decimal This returns the Transaction Convenience Fee.
netAmount decimal This returns the Transaction Net Amount.
paymentMethod string This returns the Payment Method.
cc = Credit Card, ach = ACH,
pinless = Pinless Debit, rcc = Remotely Created Checks
paymentFrequency string This returns the Payment Frequency.
paymentDate string This returns the First Payment Date.
firstName string This returns the Customer First Name.
lastName string This returns the Customer Last Name.
emailAddress string This returns the Customer Email Address.
addressLine1 string This returns the Customer Address Line 1.
addressLine2 string This returns the Customer Address Line 2.
city string This returns the Customer City.
state string This returns the Customer State.
zip string This returns the Customer Zip.
custom1 string This returns the first custom field value.
custom2 string This returns the second custom field value.
custom3 string This returns the third custom field value.
custom4 string This returns the fourth custom field value.
custom5 string This returns the fifth custom field value.
designation1Purpose string This returns the first designation purpose field.
designation1Amount decimal This returns the first designation amount field.
designation2Purpose string This returns the second designation purpose field.
designation2Amount decimal This returns the second designation amount field.
designation3Purpose string This returns the third designation purpose field.
designation3Amount decimal This returns the third designation amount field.
accountCode1 string This returns the first account code value.
accountCode2 string This returns the second account code value.
accountCode3 string This returns the third account code value.

API 2.0

Please click here for access to our API 2.0 documentation.

Code Samples

			
curl -X POST \
https://payments.usiopay.com/2.0/payments.svc/json/endpoint \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{
   "MerchantID": "12345",
   "Login": "API12345",
   "Password": "Temp1234!",
   "additionalData": "1221"
   }'
			
		
			
WebRequest request = WebRequest.Create("https://payments.usiopay.com/2.0/payments.svc/json/endpoint");
request.Method = "POST";
request.ContentType = "application/json; charset=utf-8";
request.Timeout = 600000;
string input = "{\"MerchantID\":\"12345\",\"login\":\"API12345\",
	\"password\":\"Temp1234!\",\"additionalData\":\"values\"}";
//Get the request stream
Stream POSTstream = request.GetRequestStream();
//Write the data bytes in the request stream
byte[] dataByte = Encoding.UTF8.GetBytes(sJSON.ToString());
POSTstream.Write(dataByte, 0, dataByte.Length);
POSTstream.Close();
//Get response from server
WebResponse POSTResponse = request.GetResponse();
StreamReader reader = new StreamReader(POSTResponse.GetResponseStream(), Encoding.UTF8);
string responseJSON = reader.ReadToEnd();
			
		
			
URL url = new URL("https://payments.usiopay.com/2.0/payments.svc/json/endpoint");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setDoOutput(true);
conn.setRequestMethod("POST");
conn.setRequestProperty("Content-Type", "application/json");

String input = "{\"MerchantID\":\"12345\",\"login\":\"API12345\",
	\"password\":\"Temp1234!\",\"additionalData\":\"values\"}";

OutputStream os = conn.getOutputStream();
os.write(input.getBytes());
os.flush();

if (conn.getResponseCode() != HttpURLConnection.HTTP_CREATED) {
			throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
}

BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream())));

String output;
System.out.println("Output from Server .... \n");
while ((output = br.readLine()) != null) {
   System.out.println(output);
}

conn.disconnect();
			
		
			
function CallSingularBillPayAPI() {
			var xhttp = new XMLHttpRequest();
   xhttp.onreadystatechange = function () {
			if (this.readyState == 4 && this.status == 200) {
           alert(this.responseText);
       }
   };
   xhttp.open("POST", "https://payments.usiopay.com/2.0/payments.svc/json/endpointName", true);
   xhttp.setRequestHeader("Content-type", "application/json");
			var obj = '{"MerchantID":"12345","Login":"API12345","Password":"Temp1234!","additionalData":""}';
   xhttp.send(obj);
}
			
		
			
let json: [String: Any] =
["MerchantID": "12345",
"Login": "API12345",
"Password": "Temp1234!",
"additionalData": ""]

let jsonData = try? JSONSerialization.data(withJSONObject: json)

let url = URL(string: "https://payments.usiopay.com/2.0/payments.svc/json/endpoint")!
var request = URLRequest(url: url)
request.httpMethod = "POST"
request.httpBody = jsonData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
   guard let data = data, error == nil else {
      print(error?.localizedDescription ?? "No data")
			return
   }
			let responseJSON = try? JSONSerialization.jsonObject(with: data, options: [])
			if let responseJSON = responseJSON as? [String: Any] {
      print(responseJSON)
   }
}

task.resume()
			
		
			
function callAPI($method, $url, $data){
			$curl = curl_init();
   curl_setopt($curl, CURLOPT_POST, 1);
   curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
   // OPTIONS:
   curl_setopt($curl, CURLOPT_URL, $url);
   curl_setopt($curl, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
   curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
   curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);

   // EXECUTE:
			$result = curl_exec($curl);
   if(!$result){die("Connection Failure");}
   curl_close($curl);
   return $result;
}

$data_array =  array(
			"merchantID" => "12345",
			"login" => "API12345",
			"password" => "Temp1234!",
			"additionalData" => "values"
   ),
);

$make_call = callAPI('POST', 'https://payments.usiopay.com/2.0/payments.svc/json/enpoint', json_encode($data_array));
$response = json_decode($make_call, true);
$errors   = $response['response']['errors'];
$data     = $response['response']['data'][0];

			
		
			
use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Content-Type', 'application/json');
$client->addHeader('charset', 'UTF-8');
$client->addHeader('Accept', 'application/json');

$req = '{
	"MerchantID" : "12345",
	"Login" : "API12345",
	"Password" : "Temp1234!",
	"additionalData" : "",
	}';

$url="https://payments.usiopay.com/2.0/payments.svc/json/endpoint";

$client->POST($url, $req);
print $client->responseContent();
			
		
			
require 'net/http'

url = 'https://payments.usiopay.com/2.0/payments.svc/json/endpoint'
params = {
  merchantID => '12345',
  login => 'API12345',
  password => 'Temp1234!',
  additionalData => 'values'
}

resp = Net::HTTP.post_form(url, params)

resp_text = resp.body
			
		
			
import requests
import json

def main():
   data = {}
   data[MerchantID] = '12345'
   data[Login] = 'API12345'
   data[Password] = 'Temp1234!'
   data[additionalData] = ''
   json = json.dumps(data)

   req = requests.post('https://payments.usiopay.com/2.0/payments.svc/json/endpoint', data=None, json=None)
			print("HTTP Status Code: " + str(req.status_code))
			print(req.headers)
   json_response = json.loads(req.content)
			print(json_response)

if __name__ == '__main__':
   main()
			
		
			
package main

import (
			"bytes"
			"encoding/json"
			"fmt"
			"io/ioutil"
			"net/http"
)

func main() {
    jsonData := map[string]string{
			"MerchantID": "12345",
			"Login": "API12345",
			"password": "Temp234!",
			"additionalData": "values"}
    jsonValue, _ := json.Marshal(jsonData)
    response, err := http.Post("https://payments.usiopay.com/2.0/payments.svc/json/endpoint",
			"application/json",
	   bytes.NewBuffer(jsonValue))
    if err == nil {
        data, _ := ioutil.ReadAll(response.Body)
		fmt.Println(data)
    }
}

In the right hand panel we have provided code samples in several of the most popular programming languages.
You will find code for cURL, C#, JAVA, Javascript, Swift, PHP, Perl, Ruby, Python, and Go.
In addition to REST/JSON, we also support REST/XML, SOAP, and WCF calls.

For additional help and support during your integration please contact us at integrations@usio.com

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
5006 Transaction Limits Exceeded
5011 Operation Not Valid On This Card
5012 Operation Not Available On This Transaction Type
5050 Invalid Amount
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
5071 Invalid Account Code 1
5072 Invalid Account Code 2
5073 Invalid Account Code 3
5074 Invalid Convenience Fee Amount
5076 Invalid Payment Date
5078 Invalid Account Number
5079 Invalid Routing Number
5086 Card Brand is not supported
5102 Invalid Payment Frequency
5122 Invalid Data Format
5129 Credit Cards not supported
5134 Prefill Page Cannot Be Empty
5135 Prefilled Amount cannot exceed limit
5136 No Site Found
5137 Invalid Custom Field 1
5138 Invalid Custom Field 2
5139 Invalid Custom Field 3
5140 Invalid Custom Field 4
5141 Invalid Custom Field 5
5142 Invalid Designation 1 Purpose
5143 Invalid Designation 1 Amount
5144 Invalid Designation 2 Purpose
5145 Invalid Designation 2 Amount
5146 Invalid Designation 3 Purpose
5147 Invalid Designation 3 Amount































































cURL C# Java Javascript Swift Php Perl Ruby Python Go Lang