REST API Reference

REST Information

 

Accessing the REST endpoints requires the Basic HTTP Authorization Header for all operations.

 

When passing HTTP Authorization header values with a token, either {{identityToken}}, {{sessionToken}}, or {{userAccessToken}} must be set as the {{username}}. As {{password}} is required by HTTP, you will need to set this value as well. CWS will not validate or utilize this password.

 

If you are signing on to the platform with a {{username}} and {{password}}, you will set the basic authorization data in the corresponding {{username}} and {{password}} fields.

 

Signing On With A Token

 

There are two types of tokens available for signing on to the platform:

 

Identity Token

 

The {{identityToken}} is a long-life token in the form of a base64 encoded string that is assigned to a client application after certification. The {{identityToken}} is valid for up to three years, and may be refreshed at any time. Therefore, this should never be hard-coded within you application.

 

User Access Token

 

The {{userAccessToken}} is a limited-life token in the form of a base64 encoded string that is returned along-with a session token when you sign on to the platform with a username and password.  User Access Tokens allow you to easily refresh your session.  Should the session token expire during the time a user is logged on to your application (session tokens are valid for 30 minutes), you can call sign on with this token and receive a refreshed session token.  This allows the current user to continue work without having to re-enter their username and password every 30 minutes.

HTTP Response Codes are set based on the success or failure of a transaction. Generally, a 200-level response code indicates the processing of the transaction completed successfully, but that may not mean that the transaction was authorized. A declined authorization also returns a 200-level response code. The response body must be inspected to determine how the service provider handled the transaction.

 

A 400-level response code indicates user error, (e.g.: Issues with data syntax, missing required fields, etc.). The response body contains an XML (or JSON) object with the details of the error. There may be more than one error in the response. These errors can usually be resolved by the user resubmitting the transaction with corrected data.

Note: The ErrorResponse object contains the specifics of the 400-level HTTP Response Codes as well as the associated CWS fault code (ErrorId). Data rule validation errors are also listed within the ErrorResponse object in ValidationError.
  

The 500-level response codes indicate a system error. These errors vary by service so please follow proper resubmission protocols. The typical protocol is to submit an Undo transaction, followed by the resubmission of the original transaction.

 

The HTTP Response Codes are listed below:

Code Status Message Description Body
200 OK The request was successful. Serialized Response instance.
400 Bad Request The request was not understood by the server due to bad data syntax. The response body contains a list of error messages. Serialized ErrorResponse instance.
404 Not Found The server cannot find any resources matching the requested URI.
500 The server encountered an unexpected condition preventing the fulfilling of the request. Thrown whenever our service must raise an exception or when a fault is received from the CWS-internal services. The ‘status message’ is the error message from the exception or fault. HTML: ‘Error Status Code: 'InternalServerError' Details: The is currently unavailable.’
503 Service Unavailable The service has been shutdown and/or dependent services are not available. HTML: ‘Error Status Code: 'InternalServerError' Details: The is currently unavailable.’
504 Gateway Timeout The server, while acting as a gateway or proxy, did not receive a timely response from the downstream server or an unknown response was returned. HTML: ‘Error Status Code: 'InternalServerError' Details: The is currently unavailable.’

CWS REST (XML/JSON) implementations require the definition of the type attribute (i:type=) on the document element of all Transaction Processing requests. It is also required on elements where an object supplied is a child of the defined parameter type.

 

CWS REST (XML/JSON) implementations require the definition of the type attribute (i:type=) on the document element of all Transaction Processing requests. It is also required on elements where an object supplied is a child of the defined parameter type.

 

Examples of message body type attribute in a CWS Bankcard Authorize transaction requests:

 
 ]<SubmitTransaction xmlns:i='http://www.w3.org/2001/XMLSchema-instance' i:type='AuthorizeTransaction' xmlns='http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest'>
  <ApplicationProfileId>APP_ID</ApplicationProfileId>
  <MerchantProfileId>MERCH_ID</MerchantProfileId>
  <Transaction xmlns:d2p1='http://schemas.evosnap.com/CWS/v2.0/Transactions' xmlns:d2p2='http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard' i:type='d2p2:BankcardTransaction'>
    <d2p1:CustomerData i:nil='true'/>
    <d2p1:ReportingData i:nil='true'/>
    <d2p1:Addendum i:nil='true'/>
    <d2p2:ApplicationConfigurationData i:nil='true'/>
    <d2p2:TenderData>TENDER_DATA</d2p2:TenderData> // child elements removed for brevity
    <d2p2:TransactionData>TXN_DATA</d2p2:TransactionData> // child elements removed for brevity
  </Transaction>
</SubmitTransaction>
{"$type":"AuthorizeTransaction,http://schemas.evosnap.com/CWS/v2.0/Transactions/Rest",
   "ApplicationProfileId":"APP_ID",
   "MerchantProfileId":"MERCH_ID",
   "Transaction":{
      "$type":"BankcardTransaction,http://schemas.evosnap.com/CWS/v2.0/Transactions/Bankcard",
      "CustomerData":null,
      "ReportingData":null,
      "Addendum":{
         "Unmanaged":{
            "Any":[
               "<Username>USERNAME</Username>",
               "<Password>PASSWORD</Password>"
            ]
         }
      },
      "ApplicationConfigurationData":null,
      "TenderData":{}, // child elements removed for brevity
      "TransactionData":{} // child elements removed for brevity
}
 

The table below lists the valid message body type attributes required for each Transaction Processing operation:

REST API Operation Type Attribute
Acknowledge $type=”Acknowledge”
Adjust $type=”Adjust”
Authorize $type=”AuthorizeTransaction”
AuthorizeAndCapture $type=’"AuthorizeAndCaptureTransaction"
Capture $type="Capture"
CaptureAll $type="CaptureAll"
CaptureAllAsync $type="CaptureAllAsync"
ManageAccount $type="ManageAccount"
ManageAccountById $type="ManageAccountById"
QueryAccount $type="AuthorizeTransaction"
RequestTransaction $type="TransactionRequest"
ReturnById $type="ReturnById"
ReturnUnlinked $type="ReturnTransaction"
Undo $type="Undo"
Verify $type="AuthorizeTransaction"