Generate a Transaction Request on Express

Developers can generate either an XML or SOAP request when using the Express API, though note that XML is the preferred interface option, as new functionality and enhancements are no longer being implemented on the SOAP interface. When you register for a test account you will receive an email with the credentials necessary to populate these fields.

The examples below are for illustrative purposes, and only demonstrate a Credit Card Sale. A complete list of transactions is available in the Express Interface Specification. Additional examples can be found on the Express API GitHub Site.

Sample XML request for a Credit Card Sale transaction

The XML fragment below shows how a credit card sale transaction is structured. This example shows sending credit card information over an encrypted channel. Developers who want to reduce scope for their payment application and avoid storing or processing card data should consider solutions offering increased security compatible with the Express processing platform, including triPOS or TransForm Hosted Payments, or Point-to-Point encryption and tokenization.

You will need to Create a Test 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.

<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 above response data. One method is to use the DocumentBuilder method as shown. This will result 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);