API Samples And Demo
Universal API
EXAMPLE
The Paymentsite Universal API is a server-side application (Web service) that provides access to transaction processing services. All communications take place over secure HTTPS links on the Internet. Requests are sent to the payment processing servers by “POSTing” XML or JSON data that has been formatted per the schema defined in this specification. The response is returned as XML or JSON data in the body of the HTTP reply.
Before You Begin
Before you can begin testing, you will need a test account with Paymentsite. Please contact us at support@paymentsite.com to set up your test account. Test accounts are not connected to the payment processor and even though you will receive a response from each request sent, transactions sent to a test account are not actually processed and no money is moved. Your test account information should include a merchant ID and a key that you will include in all requests you send to the Paymentsite system. This merchant ID and key is merchant specific.
Transaction Request
Posting URL
The posting URL to use for testing API transaction requests is as follows. This URL is strictly for posting transactions such as auth, capture, sale, return, etc.
Posting URL for test transaction requests: https://apiint.paymentsite.com/UniversalAPI/postXML
Note
When passing transactions through a test account a simulated payment gateway will be used. To pass a successful transaction to the engine that approves pass an even dollar amount such as $100.00. To simulate failed transactions and get a decline, pass an odd number such as $100.01. To simulate a partial payment pass a value between $300.00 to $399.99. Don't forget odd numbers will decline.
Credit Card Sale
XML Request
<transaction-request>
<version>3.1.1.1</version>
<verification>
<merchantId>your merchant id</merchantId>
<merchantKey>your key</merchantKey>
</verification>
<order>
<sale>
<referenceNum>846392232</referenceNum>
<ipAddress>123.123.123.123</ipAddress>
<invoiceNumber>123456</invoiceNumber>
<billing>
<name>Tom Customer</name>
<address>123 Main Street</address>
<address2>Apt 36</address2>
<city>Moorpark</city>
<state>CA</state>
<postalcode>91307</postalcode>
<country>US</country>
<phone>818-123-1234</phone>
<email>customer@example.com</email>
</billing>
<shipping>
<name>Tom Customer</name>
<address>123 Main Street</address>
<address2>Apt 36</address2>
<city>Moorpark</city>
<state>CA</state>
<postalcode>91307</postalcode>
<country>US</country>
<phone>818-123-1234</phone>
<email>customer@example.com</email>
</shipping>
<transactionDetail>
<payType>
<creditCard>
<number>4111111111111111</number>
<expMonth>12</expMonth>
<expYear>2028</expYear>
<cvvInd></cvvInd>
<cvvNumber>123</cvvNumber>
<track1Data></track1Data>
<track2Data></track2Data>
<eCommInd>eci</eCommInd>
<signatureImage></signatureImage>
</creditCard>
</payType>
</transactionDetail>
<payment>
<chargeTotal>32.00</chargeTotal>
<salesTaxTotal>1.23</salesTaxTotal>
<shippingTotal>3.00</shippingTotal>
<currencyCode>USD</currencyCode>
</payment>
</sale>
</order>
</transaction-request>
XML Response
<transaction-response>
<authCode>432582</authCode>
<orderID>C0A8C866:0119C7DF2702:E1D7:00E3FDA2</orderID>
<referenceNum>846392232</referenceNum>
<transactionID>32523465462</transactionID>
<transactionTimestamp>1210664602</transactionTimestamp>
<responseCode>0</responseCode>
<responseMessage>AUTHORIZED</responseMessage>
<avsResponseCode>YYY</avsResponseCode>
<cvvResponseCode>M<cvvResponseCode>
<processorCode>A</processorCode>
<processorMessage>APPROVED</processorMessage>
<processorTransactionID>262</processorTransactionID>
<processorReferenceNumber>111221266<processorReferenceNumber>
<partiallyApprovedAmount>12.99</partiallyApprovedAmount>
<accountBalance>35.99</accountBalance>
<errorMessage/>
</transaction-response>
JSON Request
{
"transaction-request": {
"version": "3.1.1.1",
"verification": {
"merchantId": your merchant id,
"merchantKey": "your key"
},
"order": {
"sale": {
"shipping": {
"name": "Susan Johnson",
"address": "123 Main Street",
"address2": "Apt 36",
"city": "Moorpark",
"state": "CA",
"country": "US",
"postalcode": 91307,
"phone": "818-123-1234",
"email": "customer@example.com"
},
"billing": {
"name": "Susan Johnson",
"address": "123 Main Street",
"address2": "Apt 36",
"city": "Moorpark",
"state": "CA",
"country": "US",
"postalcode": 91307,
"phone": "818-123-1234",
"email": "customer@example.com"
},
"payment": {
"chargeTotal": 32.0,
"shippingTotal": 3.0,
"salesTaxTotal": 1.23,
"currencyCode": "USD"
},
"transactionDetail": {
"payType": {
"creditCard": {
"number": 4111111111111111,
"expMonth": 12,
"expYear": 2028,
"cvvNumber": 123,
"cvvInd": "",
"track1Data": "",
"track2Data": "",
"signatureImage": "",
"eCommInd": "retail"
}
}
},
"referenceNum": 846392232,
"invoiceNumber": 123456,
"ipAddress": "123.123.123.123"
}
}
}
}
JSON Response
{
"transaction-response": {
"errorMessage": "",
"authCode": 123456,
"responseCode": 0,
"orderID": "C0A8631F:014EF47935EE:4959:2AB4B8ED",
"cvvResponseCode": "M",
"transactionID": 464380,
"processorMessage": "APPROVED",
"eCommInd": "retail",
"avsResponseCode": "YYY",
"referenceNum": 846392232,
"responseMessage": "CAPTURED",
"processorCode": "A",
"merchantId": your merchant id,
"transactionTimestamp": 1438620661
}
} Offline Sale (Using Token)
XML Request
<transaction-request>
<version>3.1.1.1</version>
<verification>
<merchantId>your merchant id</merchantId>
<merchantKey>your key</merchantKey>
</verification>
<order>
<sale>
<referenceNum>846392232</referenceNum>
<ipAddress>123.123.123.123</ipAddress>
<invoiceNumber>123456</invoiceNumber>
<shipping>
<name>Tom Customer</name>
<address>123 Main Street</address>
<address2>Apt 36</address2>
<city>Moorpark</city>
<state>CA</state>
<postalcode>91307</postalcode>
<country>US</country>
<phone>818-123-1234</phone>
<email>customer@example.com</email>
</shipping>
<transactionDetail>
<payType>
<onFile>
<consumerPrimaryId>61982</consumerPrimaryId>
<consumerExternalId></consumerExternalId>
<token>HNZEHK2tCPY=</token>
</onFile>
</payType>
</transactionDetail>
<payment>
<chargeTotal>32.00</chargeTotal>
<salesTaxTotal>1.23</salesTaxTotal>
<shippingTotal>3.00</shippingTotal>
<currencyCode>USD</currencyCode>
</payment>
</sale>
</order>
</transaction-request>
XML Response
<transaction-response>
<authCode>432582</authCode>
<orderID>C0A8C866:0119C7DF2702:E1D7:00E3FDA2</orderID>
<referenceNum>846392232</referenceNum>
<transactionID>32523465462</transactionID>
<transactionTimestamp>1210664602</transactionTimestamp>
<responseCode>0</responseCode>
<responseMessage>AUTHORIZED</responseMessage>
<avsResponseCode>YYY</avsResponseCode>
<cvvResponseCode>M<cvvResponseCode>
<processorCode>A</processorCode>
<processorMessage>APPROVED</processorMessage>
<processorTransactionID>262</processorTransactionID>
<processorReferenceNumber>111221266<processorReferenceNumber>
<partiallyApprovedAmount>12.99</partiallyApprovedAmount>
<accountBalance>35.99</accountBalance>
<errorMessage/>
</transaction-response>
JSON Request
{
"transaction-request": {
"version": "3.1.1.1",
"verification": {
"merchantId": your merchant id,
"merchantKey": "your key"
},
"order": {
"sale": {
"shipping": {
"name": "Susan Johnson",
"address": "123 Main Street",
"address2": "Apt 36",
"city": "Moorpark",
"state": "CA",
"country": "US",
"postalcode": 91307,
"phone": "818-123-1234",
"email": "customer@example.com"
},
"payment": {
"chargeTotal": 32.0,
"shippingTotal": 3.0,
"salesTaxTotal": 1.23,
"currencyCode": "USD"
},
"transactionDetail": {
"payType": {
"onFile": {
"consumerPrimaryId": "61982",
"consumerExternalId": "",
"token": "HNZEHK2tCPY="
}
}
},
"referenceNum": 846392232,
"invoiceNumber": 123456,
"ipAddress": "123.123.123.123"
}
}
}
}
JSON Response
{
"transaction-response": {
"errorMessage": "",
"authCode": 123456,
"responseCode": 0,
"orderID": "C0A8631F:014EF47935EE:4959:2AB4B8ED",
"cvvResponseCode": "M",
"transactionID": 464380,
"processorMessage": "APPROVED",
"eCommInd": "retail",
"avsResponseCode": "YYY",
"referenceNum": 846392232,
"responseMessage": "CAPTURED",
"processorCode": "A",
"merchantId": your merchant id,
"transactionTimestamp": 1438620661
}
} Setup Recurring
XML Request
<transaction-request>
<version>3.1.1.1</version>
<verification>
<merchantId>your merchant id</merchantId>
<merchantKey>your key</merchantKey>
</verification>
<order>
<recurringPayment>
<referenceNum>846392232</referenceNum>
<ipAddress>123.123.123.123</ipAddress>
<invoiceNumber>123456</invoiceNumber>
<billing>
<name>Tom Customer</name>
<address>123 Main Street</address>
<address2>Apt 36</address2>
<city>Moorpark</city>
<state>CA</state>
<postalcode>91307</postalcode>
<country>US</country>
<phone>818-123-1234</phone>
<email>customer@example.com</email>
</billing>
<shipping>
<name>Tom Customer</name>
<address>123 Main Street</address>
<address2>Apt 36</address2>
<city>Moorpark</city>
<state>CA</state>
<postalcode>91307</postalcode>
<country>US</country>
<phone>818-123-1234</phone>
<email>customer@example.com</email>
</shipping>
<transactionDetail>
<payType>
<creditCard>
<number>4111111111111111</number>
<expMonth>12</expMonth>
<expYear>2028</expYear>
<cvvInd></cvvInd>
<cvvNumber>123</cvvNumber>
<track1Data></track1Data>
<track2Data></track2Data>
<eCommInd>eci</eCommInd>
<signatureImage></signatureImage>
</creditCard>
</payType>
</transactionDetail>
<payment>
<chargeTotal>32.00</chargeTotal>
<salesTaxTotal>1.23</salesTaxTotal>
<shippingTotal>3.00</shippingTotal>
<currencyCode>USD</currencyCode>
</payment>
<!-- fields to specify parameters of the scheduled payment -->
<recurring>
<action>new</action>
<startDate>2016-11-30</startDate>
<period>monthly</period>
<frequency>1</frequency>
<installments>24</installments>
<failureThreshold>3</failureThreshold>
</recurring>
</recurringPayment>
</order>
</transaction-request>
XML Response
<transaction-response>
<authCode/>
<orderID>C0A8C866:0119C7DF2702:E1D7:00E3FDA2</orderID>
<referenceNum/>
<transactionID/>
<transactionTimestamp>1210664602</transactionTimestamp>
<responseCode>0</responseCode>
<responseMessage>APPROVED</responseMessage>
<avsResponseCode/>
<cvvResponseCode/>
<processorCode/>
<processorMessage/>
<errorMessage/>
</transaction-response>
JSON Request
{
"transaction-request": {
"version": "3.1.1.1",
"verification": {
"merchantId": your merchant id,
"merchantKey": "your key"
},
"order": {
"recurringPayment": {
"shipping": {
"name": "Susan Johnson",
"address": "123 Main Street",
"address2": "Apt 36",
"city": "Moorpark",
"state": "CA",
"country": "US",
"postalcode": 91307,
"phone": "818-123-1234",
"email": "customer@example.com"
},
"billing": {
"name": "Susan Johnson",
"address": "123 Main Street",
"address2": "Apt 36",
"city": "Moorpark",
"state": "CA",
"country": "US",
"postalcode": 91307,
"phone": "818-123-1234",
"email": "customer@example.com"
},
"payment": {
"chargeTotal": 32.0,
"shippingTotal": 3.0,
"salesTaxTotal": 1.23,
"currencyCode": "USD"
},
"transactionDetail": {
"payType": {
"creditCard": {
"number": 4111111111111111,
"expMonth": 12,
"expYear": 2028,
"cvvNumber": 123,
"cvvInd": "",
"track1Data": "",
"track2Data": "",
"signatureImage": "",
"eCommInd": "retail"
}
}
},
"recurring": {
"action": "new",
"period": "monthly",
"installments": 24,
"startDate": "2016-11-30",
"failureThreshold": 3,
"frequency": 1
},
"referenceNum": 846392232,
"invoiceNumber": 123456,
"ipAddress": "123.123.123.123"
}
}
}
}
JSON Response
{
"transaction-response": {
"errorMessage": "",
"authCode": "",
"responseCode": 0,
"orderID": "C0A8631F:014EF47935EE:4959:2AB4B8ED",
"cvvResponseCode": "",
"transactionID": "",
"eCommInd": "retail",
"avsResponseCode": "",
"referenceNum": 846392232,
"responseMessage": "APPROVED",
"processorCode": "",
"merchantId": your merchant id,
"transactionTimestamp": 1438620661
}
} Non Transaction Request
Testing URL
The posting URL to use for testing other API requests (requests such as add-consumer, which are not transactional in nature) is:
Posting URL for test requests which are NON-transactional: https://apiint.paymentsite.com/UniversalAPI/postAPI
Add Customer
XML Request
<api-request>
<verification>
<merchantId>your merchant id</merchantId>
<merchantKey>your key</merchantKey>
</verification>
<command>add-consumer</command>
<request>
<customerIdExt>123456</customerIdExt>
<firstName>John</firstName>
<middleName></middleName>
<lastName>Test</lastName>
<address1>123 Main St.</address1>
<address2></address2>
<city>Moorpark</city>
<state>CA</state>
<zip>91311</zip>
<phone>123-123-1234</phone>
<email>customer@example.com</email>
<dob>12/31/1970</dob>
<ssn>111-11-1111</ssn>
<sex>M</sex>
</request>
</api-request>
XML Response
<api-response>
<errorCode>0</errorCode>
<errorMessage />
<command>add-consumer</command>
<time>1262352122049</time>
<result>
<customerId>74</customerId>
</result>
</api-response>
Add Payment On File (New Customer)
XML Request
<api-request>
<verification>
<merchantId>your merchant id</merchantId>
<merchantKey>your key</merchantKey>
</verification>
<command>add-consumer-onfile</command>
<request>
<customerIdExt>123456</customerIdExt>
<firstName>John</firstName>
<middleName></middleName>
<lastName>Test</lastName>
<address1>123 Main St.</address1>
<address2></address2>
<city>Moorpark</city>
<state>CA</state>
<zip>91311</zip>
<phone>123-123-1234</phone>
<email>customer@example.com</email>
<dob>12/31/1970</dob>
<ssn>111-11-1111</ssn>
<sex>M</sex>
<onFileType>CREDIT</onFileType>
<creditCardNumber>4111111111111111</creditCardNumber>
<expirationMonth>09</expirationMonth>
<expirationYear>2028</expirationYear>
</request>
</api-request>
XML Response
<api-response>
<errorCode>0</errorCode>
<errorMessage />
<command>add-consumer-onfile</command>
<time>1262352122049</time>
<result>
<customerId>74</customerId>
<token>I28P65RNklg=</token>
</result>
</api-response>
Add Payment On File (Existing Customer)
XML Request
<api-request>
<verification>
<merchantId>your merchant id</merchantId>
<merchantKey>your key</merchantKey>
</verification>
<command>add-card-onfile</command>
<request>
<customerId>112</customerId>
<creditCardNumber>4111111111111111</creditCardNumber>
<expirationMonth>09</expirationMonth>
<expirationYear>2028</expirationYear>
<billingName>John Smith</billingName>
<billingAddress1>123 Main St.</billingAddress1>
<billingAddress2></billingAddress2>
<billingCity>Moorpark</billingCity>
<billingState>CA</billingState>
<billingZip>91311</billingZip>
<billingPhone>123-123-1234</billingPhone>
<billingEmail>customer@example.com</billingEmail>
</request>
</api-request>
XML Response
<api-response>
<errorCode>0</errorCode>
<errorMessage />
<command>add-card-onfile</command>
<time>1262352122049</time>
<result>
<token>I28P65RNklg=</token>
</result>
</api-response>
Code Sample
The XML can be posted using any of several different web languages, including:
- .Net
- C#
- Java
- Perl
- PHP
package test.cmd;
import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;
import javax.net.ssl.HttpsURLConnection;
/**
*
*/
public class sale {
private static final String APIXML_TESTURL = "https://apiint.paymentsite.com/UniversalAPI/postXML";
//private static final String APIXML_PRODURL = "https://api.paymentsite.com/UniversalAPI/postXML";
/*
*
*/
private String Post(String xml, String url) throws IOException {
boolean bHTTPS = false;
String sResponse = "";
if (url.startsWith("https:"))
bHTTPS = true;
HttpURLConnection httpConn = null;
HttpsURLConnection httpsConn = null;
DataOutputStream dos = null;
InputStream istr = null;
BufferedReader reader = null;
try {
URL ul = new URL(url);
if (bHTTPS) {
httpsConn = (HttpsURLConnection) ul.openConnection();
httpsConn.setDoOutput(true);
httpsConn.setDoInput(true);
httpsConn.setUseCaches(false);
httpsConn.setRequestMethod("POST");
httpsConn.setRequestProperty("Content-Type", "text/xml; charset=UTF-8");
httpsConn.setRequestProperty("Content-Length", Integer.toString(xml.getBytes("UTF-8").length));
dos = new DataOutputStream(httpsConn.getOutputStream());
} else {
httpConn = (HttpURLConnection) ul.openConnection();
httpConn.setDoOutput(true);
httpConn.setDoInput(true);
httpConn.setRequestMethod("POST");
httpConn.setRequestProperty("Content-Type", "text/xml; charset=UTF-8");
httpConn.setRequestProperty("Content-Length", Integer.toString(xml.getBytes("UTF-8").length));
dos = new DataOutputStream(httpConn.getOutputStream());
}
dos.write(xml.getBytes("UTF-8"), 0, xml.getBytes("UTF-8").length);
dos.flush();
if (bHTTPS)
istr = httpsConn.getInputStream();
else
istr = httpConn.getInputStream();
reader = new BufferedReader(new InputStreamReader(istr, "UTF-8"));
String line;
StringBuffer sb = new StringBuffer();
while ((line = reader.readLine()) != null) {
sb.append(line);
}
sResponse = sb.toString();
} catch (Exception e) {
throw e;
} finally {
if (istr != null) istr.close();
if (reader != null) reader.close();
if (dos != null) dos.close();
if (httpsConn != null) httpsConn.disconnect();
else if (httpConn != null) httpConn.disconnect();
}
return sResponse;
}
public String runTxn(){
String sResponse = "";
try{
/************ please build your request XML here ***********/
//Build API XML
String sample_xml = buildRequestXML();
sResponse = Post(sample_xml, APIXML_TESTURL);
}catch(Exception e){
e.printStackTrace();
System.out.println(e.getMessage());
}
return sResponse;
}
public static void main(String[] args) {
try{
String sResponse = runTxn();
System.out.println("response content:\n" + sResponse);
}catch(Exception e){
e.printStackTrace();
System.out.println(e.getMessage());
}
}
}
