REST Information

HTTP Authorization Headers

Commerce Web Services 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 identityToken is valid for up to 3 years, but can be refreshed at any time. Software companies should provide a way to refresh the identityToken as needed.
{sessionToken} PHNhbWw...zc+2VydGlvbj4=…

Note: The example value has been shortened for brevity.
Short-lived token retrieved by calling SignOn.

A sessionToken is valid for up to 30 minutes, at which time it must be replaced with a new sessionToken by calling SignOn or RenewToken.

HTTP Authorization Header Variables

Note: When passing HTTP Authorization Header values, the 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.

 


 

HTTP Response Codes

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.

Note: The ErrorResponse object will contain the specifics of the 400-level HTTP Response Codes as well as the associated CWS fault code (ErrorId). Data rule validation errors will also be listed within the 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 <error message> 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 <service> 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 <service> 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 <service> is currently unavailable."

REST HTTP Response Codes

 


 

REST API Variables

The following required data elements enclosed in brackets "{ }" are placeholders for actual merchant values that must be passed in with each Service Information and Transaction Processing request.

When the values for these placeholders contain characters that are not allowed in a URI they must be escaped. For example, the equals sign (=) should be represented as %3D, and the plus sign (+) should be represented as %2B.

Placeholder Example Value Description
{serviceId} BD9BD00001 The ID of the service the transaction should process against.
{applicationProfileId} 1234 The return value from the SaveApplicationData operation.
{merchantProfileId} AcmeInc The ID of a Merchant Profile that has been created using the SaveMerchantProfiles operation.
{transactionId} 006D57330165434E899CC9FE8B54E948 This value comes from the transactionId field in the response of a previous transaction.
{username} jsmith Username when implementing username/password authentication.
{serviceKey} 1234123412340001 The Service Key associated with the provided username.

REST API Variables

 


 

Specifying the Type Attribute

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 you are supplying an object that is a child of the type to which the parameter is defined.

XML Example

An XML example of the message body type attribute in a CWS Bankcard Authorize transaction request is shown below:

<SubmitTransaction xmlns:i='http://www.w3.org/2001/XMLSchema-instance' i:type='AuthorizeTransaction' xmlns='http://schemas.nabcommerce.com/CWS/v2.0/Transactions/Rest'>
	<ApplicationProfileId>APP_ID</ApplicationProfileId>
	<MerchantProfileId>MERCH_ID</MerchantProfileId>
	<Transaction xmlns:d2p1='http://schemas.nabcommerce.com/CWS/v2.0/Transactions' xmlns:d2p2='http://schemas.nabcommerce.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>

JSON Example

An JSON example of the message body type attribute in a CWS Bankcard Authorize transaction request is shown below:

{"$type":"AuthorizeTransaction,http://schemas.nabcommerce.com/CWS/v2.0/Transactions/Rest",
   "ApplicationProfileId":"APP_ID",
   "MerchantProfileId":"MERCH_ID",
   "Transaction":{
      "$type":"BankcardTransaction,http://schemas.nabcommerce.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 i:type="Acknowledge"
Adjust i:type="Adjust"
Authorize i:type="AuthorizeTransaction"

Unmanaged Merchant Profiles:
i:type="AuthorizeTransactionWithProfile"
AuthorizeAndCapture i:type="AuthorizeAndCaptureTransaction"

Unmanaged Merchant Profiles:
i:type="AuthorizeAndCaptureTransactionWithProfile"
Capture i:type="Capture"
CaptureAll i:type="CaptureAll"

Unmanaged Merchant Profiles:
i:type="CaptureAllWithProfile"
CaptureAllAsync i:type="CaptureAllAsync"

Unmanaged Merchant Profiles:
i:type="CaptureAllAsyncWithProfile"
CaptureSelective i:type="CaptureSelective"
CaptureSelectiveAsync i:type="CaptureSelectiveAsync"
ManageAccount i:type="ManageAccount"

Unmanaged Merchant Profiles:
i:type="ManageAccountWithProfile"
ManageAccountById i:type="ManageAccountById"
QueryAccount i:type="AuthorizeTransaction"

Unmanaged Merchant Profiles:
i:type="AuthorizeTransactionWithProfile"
RequestTransaction i:type="TransactionRequest"
ReturnById i:type="ReturnById"

Unmanaged Merchant Profiles:
i:type="ReturnByIdWithProfile"
ReturnUnlinked i:type="ReturnTransaction"

Unmanaged Merchant Profiles:
i:type="ReturnTransactionWithProfile"
Undo i:type="Undo"
Verify i:type="AuthorizeTransaction"

Unmanaged Merchant Profiles:
i:type="AuthorizeTransactionWithProfile"

Comments