Commerce Web Services Overview

Overview

Commerce Web Services (CWS) is a single API payments integration method utilizing a language-neutral path to quickly and seamlessly integrate host or terminal capture transaction processing and value-added services. Support multiple electronic payment options including Bankcard Processing (BCP Credit/Debit) and Automated Clearing House (ACH) as a lightweight component of virtually any software application.

This site provides documentation and integration support for Developers using SOAP or REST JSON implementations.

Benefits of using CWS include:

  • Single API for Credit, PinDebit, Stored Value, and ACH transactions
  • Comprehensive transaction options (such as Line Item Data, Level 2 Data, and 3-D Secure) ensure that you are able to deliver a solution with the lowest qualifying transaction fees
  • Complete EMV Capabilities, including Point-to-Point Encryption, and support for both chip and contactless payments
  • Fully PCI-compliant platform ensures customer data is protected during processing, database storage, and internal logging
  • Connect to all of EVO’s payment processors throughout the world with one API
  • Easily support various industry types (Restaurant, Retail, Ecommerce, MOTO) in various ways (Online, POS, and Mobile applications)

Component Architecture

Commerce Web Services supports SOAP and REST implementations. The architecture is separated into four areas of functionality:

  1. Service Information Service (SIS) – Provides methods for viewing the current capabilities configured for your application, such as Service IDs, workflows, operations supported, and other informationrelated to your application’s configured processing capabilities.
  2. Transaction Processing Service (TPS) – Contains all transaction processing calls to the platform and allows you to email a receipt to your customer.
  3. Transaction Management Service (TMS) – Allows you to query for either a single transaction or a group of transactions with many parameter options. View a transaction’s complete history (Authorization, Void, Return,
    etc.) quickly and easily.
  4. Customer Management Service (CMS) – Allows you to create and manage customers, as well as create single invoices or recurring subscription payments.
If you are using REST to integrate to the platform, you will be required to include the $type attribute for all calls to the transaction processing (TPS) endpoint. Example JSON requests for all transaction types are provided in the REST Implementation section.
If you are using SOAP to integrate to the platform, the base class of all payment requests is Transaction. Code samples are provided in the SOAP Implementation section.

There are four classes that inherit from Transaction:

  1. {{BankcardTransaction}}
  2. {{BankcardTransactionPro}}(contains additional Bankcard data)
  3. {{ElectronicCheckingTransaction}}
  4. {{StoredValueTransaction}}

The base Transaction class contains five members, some of which are inherited in sub-classes:

  1. {{TransactionData}}
  2. {{TransactionTenderData}}
  3. {{TransactionCustomerData}}
  4. {{TransactionReportingData}}
  5. {{IsOffline}}
{{TransactionData}} is inherited in {{BankcardTransactionData}}, {{ElectronicCheckingTransactionData}}, and {{StoredValueTransactionData}}.
{{TransactionCustomerData}} and {{TransactionReportingData}} are not inherited by any sub-classes, as there are no payment-specific data members in these objects.

Web Service Endpoints

Each service is accessed through versioned service endpoints. The four endpoints are:

  1. Service Information (SIS)
  2. Transaction Processing (TPS)
  3. Transaction Management (TMS)
  4. Customer Management (CMS)

Accessing Endpoints

Applications communicate with each web service endpoint using endpoint URLs. Administrative users must be allowed to modify the connection(s) as needed. Therefore, all URLs should be in a configuration file.

The SIS endpoints provide the following functionality:

  • Authentication of an Identity Token or Username/Password through SignOn methods
  • Returns the current service capabilities configured for your application: Service IDs, workflows, supported

Operations and other information related to your application’s configured processing capabilities:

  • Returns information about the application and merchant data associated with your Service Key
Service Information Endpoint URLs
SOAP Certification Environment: https://api.cipcert.goevo.com/x.x.x/SvcInfo
REST Certification Environment: https://api.cipcert.goevo.com/REST/x.x.x/SvcInfo
For detailed information regarding Service Information operations, please refer to Service Information.

 

The TPS endpoints provide the following functionality:

  • Transaction processing
  • End-of-day transaction settlement processing
  • Account verification and inquiry
Transaction Processing Endpoint URLs
SOAP Certification Environment: https://api.cipcert.goevo.com/x.x.x/Txn
REST Certification Environment: https://api.cipcert.goevo.com/REST/x.x.x/Txn
For detailed information regarding TPS operations, please refer to Transaction Processing.

 

The TMS endpoints provide the following functionality:

  • Query transactions and see a summary or detailed information
  • Query for transaction families, where you will see all associated transaction (authorization, void, return, etc.)
TMS URLs
SOAP Certification Environment: https://api.cipcert.goevo.com/x.x.x/DataServices/TMS.svc
REST Certification Environment: https://api.cipcert.goevo.com/x.x.x/REST/DataServices/TMS.svc
For detailed information regarding TMS operations, please refer to Transaction Management.

 

The CMS endpoints provide the following functionality:

  • Create, update, and query invoices and subscriptions
  • Create, update, and query customers
  • View transaction statistics by customer
CMS URLS
SOAP Certification Environment: https://api.cipcert.goevo.com/x.x.x/DataServices/CMS.svc
REST Certification Environment: https://api.cipcert.goevo.com/x.x.x/REST/DataServices/CMS.svc

Analyzing the WSDL

Implementing CWS

All web service endpoints provide metadata exchange via a standard Web Service Description Language (WSDL) format. The WSDL defines namespaces, data types and operations. The WSDL and XML formatted metadata is used by Integrated Development Environments (IDE) and proxy generation utilities to generate the proxy.

The following proxy generation utilities are available for Microsoft, Java, and PHP developers:

Please Contact EVO Snap* Support for sample applications for each of the development environments.

When generating proxies from the CWS WSDL for the Service Information and Transaction Processing endpoints, proxy generation tools may interpret lists (<>) as arrays ([ ]) by default, (e.g.: List GetMerchantProfiles is generated as MerchantProfile[] GetMerchantProfiles). To generate lists, configure your proxy generator accordingly.

To generate proxies, please refer to the URLs below:

If you are not using a proxy generation tool, you can still build SOAP messages in the absence of a proxy. Please contact EVO Snap* Support for examples of the SOAP messages.

To view the Service Information and Transaction Processing WSDLs, refer to the URLs provided below.

Service Information Endpoint URLs
https://api.cipcert.evosnap.com/x.x.x/SvcInfo/?wsdl=wsdl0 (Index 0 only)
https://api.cipcert.evosnap.com/x.x.x/SvcInfo/?xsd=xsd0 (Index from 0 to 2)
Transaction Processing Endpoint URLs
https://api.cipcert.evosnap.com/x.x.x/Txn/?wsdl=wsdl0 (Index 0 only)
https://api.cipcert.evosnap.com/x.x.x/Txn/?xsd=xsd0 (Index from 0 to 5)
Note: xsd=xsd0 is the set of rules the WSDL must follow. The WSDL defines the structure and format of the message, while the XSD defines the rules of the data types/values within the message.

Type Names

There are specific type names used in two different namespaces that may cause confusion during development. Because the type names are shared across namespaces, one cannot be assigned to the other directly or used interchangeably. As a result, you may be required to qualify the type name with the proper namespace.

The following type names exist in both the Service Information and Transaction Processing namespaces:

  • ApplicationLocation
  • CustomerPresent
  • EntryMode
  • HardwareType
  • IndustryType
  • PINCapability
  • ReadCapability
  • RequestACI
  • RequestAdvice
  • TypeISOCountryCodeA3
  • TypeISOCurrencyCodeA3
  • TypeISOLanguageCodeA3