How Express works

Developers can either generate XML POST or SOAP requests when using the Express API.

When you register for a sandbox account  you will receive an email with the credentials necessary to run test payment transactions. Sample code for common transactions is available here.

Additional details about Express are available in the Express Interface Specification.

Additional examples including full code implementations in various languages are available at the Express GitHub Site .

Sample XML request for a Credit Card Sale transaction

The XML fragment below shows how a credit card sale transaction is structured. For simplicity, this example shows sending credit card information directly over an encrypted channel. In practice, a token would be sent to avoid the application needing to be in possession of cardholder data.

Developers who want to reduce scope for the PCI application and avoid storing or processing card data should consider using the Express API with triPOS .

You will need to create a sandbox account in order to obtain your API credentials. While not required for testing transactions, when certifying applications, developers will be asked to provide the additional <ReferenceNumber> and <TicketNumber> tags as a part of the transaction as shown. While not required for testing transactions, when certifying applications, developers will be asked to provide the additional <ReferenceNumber> and <TicketNumber> tags as a part of the transaction as shown.

<CreditCardSale xmlns="https://transaction.elementexpress.com">
<Credentials>
          <AccountID>INSERT HERE</AccountID>
          <AccountToken>INSERT HERE</AccountToken>
          <AcceptorID>INSERT HERE</AcceptorID>
</Credentials>
<Application>
          <ApplicationID>INSERT HERE</ApplicationID>
          <ApplicationVersion>1.0</ApplicationVersion> 
          <ApplicationName>Express.CSharp</ApplicationName>
</Application>
<Terminal>
          <TerminalID>01</TerminalID>
          <CardholderPresentCode>2</CardholderPresentCode>
          <CardInputCode>5</CardInputCode>
          <TerminalCapabilityCode>3</TerminalCapabilityCode>
          <TerminalEnvironmentCode>2</TerminalEnvironmentCode>
          <CardPresentCode>2</CardPresentCode>
          <MotoECICode>1</MotoECICode>
          <CVVPresenceCode>1</CVVPresenceCode>
</Terminal>
<Card>
          <CardNumber>5499990123456781</CardNumber>
          <ExpirationMonth>12</ExpirationMonth>
          <ExpirationYear>19</ExpirationYear>
</Card>
<Transaction>
          <TransactionAmount>6.55</TransactionAmount>
          <MarketCode>7</MarketCode>
  <ReferenceNumber>1234567890000000</ReferenceNumber>
  <TicketNumber>1234567</TicketNumber> 
</Transaction>
</CreditCardSale>

Sample SOAP request for a Credit Card Sale transaction

For developers that prefer to use the web-services interface, the format for the payment transaction is similar except that the transaction is wrapped in a SOAP envelope.

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<CreditCardSale xmlns="https://transaction.elementexpress.com">
    <credentials>
        <AccountID>INSERT HERE</AccountID>
        <AccountToken>INSERT HERE</AccountToken>
        <AcceptorID>INSERT HERE</AcceptorID>
    </credentials>
    <application>
        <ApplicationID>INSERT HERE</ApplicationID>
        <ApplicationVersion>1.0</ApplicationVersion>
        <ApplicationName>Express.CSharp</ApplicationName>
    </application>
    <terminal>
        <TerminalID>01</TerminalID>
        <CardholderPresentCode>Present</CardholderPresentCode>
        <CardInputCode>ManualKeyed</CardInputCode>
        <TerminalCapabilityCode>MagstripeReader</TerminalCapabilityCode>
        <TerminalEnvironmentCode>LocalAttended</TerminalEnvironmentCode>
        <CardPresentCode>Present</CardPresentCode>
        <MotoECICode>NotUsed</MotoECICode>
        <CVVPresenceCode>NotProvided</CVVPresenceCode>
    </terminal>
    <card>
        <CardNumber>5499990123456781</CardNumber>
        <ExpirationMonth>12</ExpirationMonth>
        <ExpirationYear>19</ExpirationYear>
    </card>
    <transaction>
        <TransactionAmount>6.55</TransactionAmount>
        <MarketCode>Retail</MarketCode>
        <ReferenceNumber>1234567890000000</ReferenceNumber>
        <TicketNumber>1234567</TicketNumber>
    </transaction>


</CreditCardSale>
</soap:Body>
</soap:Envelope>

Send a request to the Express API

The HttpSender class is used to send both the XML and SOAP requests. The only difference is the endpoint the data is sent to and the SOAPAction header that is added when sending SOAP requests.

URL url = new URL(urlToSend);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();


conn.setRequestMethod("POST"); 


conn.setRequestProperty("content-type", "text/xml;charset=\"utf-8\"");
conn.setRequestProperty("accept", "text/xml");


if (soapAction != null) {
    conn.setRequestProperty("SOAPAction", soapAction);
}


conn.setRequestProperty("Content-Length", Integer.toString(data.getBytes().length)); 
conn.setConnectTimeout(10000); 
conn.setReadTimeout(30000); 
conn.setDoInput(true); 
conn.setDoOutput(true); 
OutputStreamWriter writer = new OutputStreamWriter(conn.getOutputStream()); 
writer.write(data); 
writer.close(); 

Receive the response from the Express API

The response will be in an XML format regardless of sending XML or SOAP, but the actual data returned will be slightly different. This is the response to an XML request:

<?xml version="1.0" encoding="UTF-8"?><CreditCardSaleResponse xmlns="https://transaction.elementexpress.com">
  <Response>
    <ExpressResponseCode>0</ExpressResponseCode>
    <ExpressResponseMessage>Approved</ExpressResponseMessage>
    <HostResponseCode>000</HostResponseCode>
    <HostResponseMessage>AP</HostResponseMessage>
    <ExpressTransactionDate>20150519</ExpressTransactionDate>
    <ExpressTransactionTime>182506</ExpressTransactionTime>
    <ExpressTransactionTimezone>UTC-05:00:00</ExpressTransactionTimezone>
    <Batch>
      <HostBatchID>1</HostBatchID>
      <HostItemID>15</HostItemID>
      <HostBatchAmount>98.25</HostBatchAmount>
    </Batch>
    <Card>
      <AVSResponseCode>N</AVSResponseCode>
      <CardLogo>Mastercard</CardLogo>
    </Card>
    <Transaction>
      <TransactionID>2005025701</TransactionID>
      <ApprovalNumber>000025</ApprovalNumber>
      <AcquirerData>bMCC1440300714</AcquirerData>
      <ProcessorName>NULL_PROCESSOR_TEST</ProcessorName>
      <TransactionStatus>Approved</TransactionStatus>
      <TransactionStatusCode>1</TransactionStatusCode>
      <ApprovedAmount>6.55</ApprovedAmount>
    </Transaction>
  </Response>
</CreditCardSaleResponse>

Parse the response

Developers can choose how they would prefer to parse the response data above. One method is to use the DocumentBuilder method as shown. This results in a Document object that can be traversed to extract needed information from the XML or SOAP formatted response.

DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
DocumentBuilder builder = factory.newDocumentBuilder();
InputSource is = new InputSource(new StringReader(response));
Document doc = builder.parse(is);

Resources

Some of the resources below require a Vantiv O.N.E. account.

• Express Interface API v2.7.7 (XML specification)
• Express certification details
• For developer resources and coding examples, visit http://github.com/ElementPS
• Create a Sandbox Account