Commerce Web Services
Transaction Reporting Implementation
The Transaction Management API provides a simple set of operations that allow you to retrieve two levels of transaction data – summary and detail.
- Summary– Sufficient to perform subsequent transaction processing (Adjust, Undo, ReturnById, etc.) Summary data is returned in the context of the transaction family.
- Detail– Summary data in addition to all data collected and stored about the transaction. Detail data is a complete set of CWS Bankcard transaction request, response, merchant and application data, and additional metadata. This data can be formatted as either a serialized string or as a data record.
HTTP Authorization Headers
Transaction Management implementations require the HTTP Authorization Header to pass the following variables and values associated with the relevant REST operation.
The following variables can be specified in the HTTP Authorization Header:
| Placeholder | Example Value | Description |
|---|---|---|
{identityToken} |
PHNhbWw...zc+2VydGlvbj4=… Note:The example value has been shortened for brevity. | Long-lived token provided to the client after application certification. An identity token is valid for up to 3 years, but can be refreshed at any time. Software companies should provide a way to refresh the identity token as needed. |
{sessionToken} |
PHNhbWw...zc+2VydGlvbj4=… Note: The example value has been shortened for brevity. | Short-life token retrieved by calling SignOn. A session token is valid for up to 30 minutes, at which time it must be replaced with a new session token by calling SignOn or RenewToken. |
sessionToken and identityToken are passed as the username. You must also pass a value for the password (which is required by HTTP), but CWS does not validate or utilize this password. As a result, the sessionToken will not be a URL segment or query parameter and will not be included in the body of the message.
REST Information
HTTP Response Codes are set based on the success or failure of a transaction. Generally, a 200-level response code indicates that the processing of the transaction completed successfully, but it doesn't necessarily mean that the transaction was successfully authorized. A declined authorization will also return a 200-level response code. The response body must be inspected to find out how the service provider handled the transaction.
A 400-level response code indicates a user error, such as problems with data syntax, missing required fields, etc. The response body will contain an XML (or JSON) object which provides the details of the error. There could be more than one error in the response. These types of errors can usually be resolved by the user resubmitting the transaction with the corrected data.
ErrorResponse object in ValidationError.The 500-level response codes indicate a system error. These errors will vary by service, and therefore, proper resubmission protocols should be followed. 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 could not be understood by the server due to bad data syntax. The response body will contain a list of error messages. | Serialized ErrorResponse instance. |
| 404 | Not Found | The server has not found any resources matching the request URI. | |
| 500 | The server encountered an unexpected condition which prevented it from fulfilling the request. Thrown whenever our service must raise an exception or when we get a fault 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." |
The QueryBatch operation queries the batch summary and returns Batch Status, DateTime, and a list of transactionIds in the batch.
QueryBatch operation is only supported in Terminal Capture environments.The Query Batch operations are listed below:
Query Transactions Detail
The QueryTransactionsDetail operation queries the specified transactions and returns both summary details and full transaction details as a serialized object. QueryTransactionsDetail contains the same search criteria and includeRelated functionality as QueryTransactionsSummary.
Query Transaction Familes
The QueryTransactionFamilies operation returns family summary information and a list of TransactionIds that can be used to query for full transaction details.
Query Transactions Summary
The QueryTransactionsSummary operation queries the specified transactions and returns summary details related to one or more transactions matching specific search criteria. You can indicate if the response will include all related transactions (includeRelated = 'true'). This returns all transactions matching specific search criteria and all transactions that have parent/child relationships with those matches.
Query Rejected Detail
The QueryRejectedDetail operation is used to collect transaction detail information from the service provider (post-settlement), in the event that a captured transaction was rejected during settlement by the service provider. The QueryRejectedDetail operation is supported by both the Bankcard Processing (BCP) and Electronic Checking (ECK) service classes.
For example, an ACH transaction is approved by the service provider and subsequently captured by the merchant for settlement processing. During funds processing of the transaction by the service provider, an "insufficient funds" condition occurs and the transaction is not processed. The merchant can use QueryRejectedDetail to discover this information, typically as a function of end-of-day reporting from the payment application, by reconciling actual dollars deposited in the merchant's account.
Whether or not QueryRejectedDetail is available to the merchant depends on their service configuration returned in the ServiceInformation response to GetServiceInformation.
Query Rejected Summary
The QueryRejectedSummary operation is used to collect transaction summary information from the service provider (post-settlement), in the event that a captured transaction was rejected during settlement by the service provider. The QueryRejectedSummary operation is supported by both the Bankcard Processing (BCP) and Electronic Checking (ECK) service classes.
For example, an ACH transaction is approved by the service provider and subsequently captured by the merchant for settlement processing. During funds processing of the transaction by the service provider, an "insufficient funds" condition occurs and the transaction is not processed. The merchant can use QueryRejectedSummary to discover this information, typically as a function of end-of-day reporting from the payment application, by reconciling actual dollars deposited in the merchant's account.
Whether or not QueryRejectedSummary is available to the merchant depends on their service configuration returned in the ServiceInformation response to GetServiceInformation.
API Reference
- For Implementation API reference information, click on the links below: