Transaction Status

A TransactionStatusRequest is used by a vendor to inquire about the status of one or more transactions, for example to determine whether a transaction has been cancelled or is still open. The vendor will include a TransactionItem for each transaction whose status it requires. Each TransactionItem element must include the TransactionId.

The response will be in the form of a TransactionStatusResponse element and will include an ItemStatus element for each TransactionItem in the request. The ItemStatus element will contain the TransactionId of the transaction and the ParentTransactionId of the TransactionOpenRequest if there is more than one transaction request associated with that transaction.

The ItemStatus element will also contain the Quantity, Actualized, AssetId, OrderNumber, TransactionStatus, UnitPrice, TransactionDate, VendorId, StatusCode, StatusDescription, and OrderLineId elements.

The Quantity element specifies the total number of sheets that the customer has purchased. The Actualized element specifies the number of copies of the asset that the customer has already printed. Note that the Actualized element is not used by the Noteflight Viewer and it is only provded in the response for backward compatibility. The TransactionStatus specifies whether the transaction is OPEN, COMPLETE or CANCELLED. When a vendor creates a new transaction through a TransactionOpenRequest or TransactionRetryRequest, the status of the transaction is marked as "OPEN" usually until the customer prints all the copies for that transaction. The only exception to that occurs when the vendor has issued a TransactionCancelRequest for that transaction. A TransactionCancelRequest will change the transaction's status from "OPEN" to "CANCELLED", even if there are remaining prints for that transaction. If a transaction has not been cancelled and the customer prints all the copies of the asset, then the DAM system will change the status of the transaction to "COMPLETED".

If an error occurs while retrieving the transaction information, the ItemStatus element will return the TransactionId from the request, set the AssetId, OrderNumber, and OrderLineId to 'unknown' and specify the respective status code and status description for the error. The status codes and status descriptions are specified on the DAM Status Codes page.

Request / Response Examples

TransactionStatusRequest Example:

<?xml version="1.0"?>
<!DOCTYPE DAMRequest SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMRequestVersion5.dtd">
<DAMRequest>
    <RequestHdr>
        <DAMVersion>5.0</DAMVersion>
        <VendorId>123</VendorId>
        <VendorKey>theKey123</VendorKey>
    </RequestHdr>
    <TransactionStatusRequest>
        <TransactionItem>
            <TransactionId>1122444</TransactionId>
        </TransactionItem>
        <TransactionItem>
            <TransactionId>5555777</TransactionId>
        </TransactionItem>
    </TransactionStatusRequest>
</DAMRequest>

TransactionStatusResponse Example:

<?xml version="1.0"?>
<!DOCTYPE DAMResponse SYSTEM "https://haldms.halleonard.com/dam_dtd/DAMResponseVersion5.dtd">
<DAMResponse>
    <ResponseHdr>
        <DAMVersion>5.0</DAMVersion>
        <VendorId>123</VendorId>
    </ResponseHdr>
    <TransactionStatusResponse>
        <ItemStatus>
            <StatusCode>1</StatusCode>
            <StatusDescription>OK.</StatusDescription>
            <TransactionId>1122444</TransactionId>
            <ParentTransactionId>1122333</TransactionId>
            <Quantity>1</Quantity>
            <Actualized>1</Actualized>
            <AssetId>4000</AssetId>
            <OrderNumber>12345</OrderNumber>
            <TransactionStatus>CANCELLED</TransactionStatus>
            <UnitPrice>3.95</UnitPrice>
            <TransactionDate>2015-09-25</TransactionDate>
        </ItemStatus>
        <ItemStatus>
            <StatusCode>1</StatusCode>
            <StatusDescription>OK.</StatusDescription>
            <TransactionId>5555777</TransactionId>
            <ParentTransactionId>-1</ParentTransactionId>
            <Quantity>1</Quantity>
            <Actualized>0</Actualized>
            <AssetId>2555</AssetId>
            <OrderNumber>23456</OrderNumber>
            <TransactionStatus>OPEN</TransactionStatus>
            <UnitPrice>3.95</UnitPrice>
            <TransactionDate>2015-10-25</TransactionDate>
        </ItemStatus>
    </TransactionStatusResponse>
</DAMResponse>