Transaction Lifecycle

This is a how-to guide to the various types of transaction requests. For the exact details of the XML requests and response, please check the the Transaction Open, Transaction Retry, and Transaction Cancel.

Purchase

The transaction lifecycle starts off with your customer making a purchase. As part of the customer purchase process, you will need to send a TransactionOpenRequest to DAM. This can contain one or more assets, but for this example we will be dealing with a single sheet asset. From the TransactionOpenResponse, you will need to save the TransactionID. It is required in order to make TransactionReryRequests and TransactionCancelRequests. The ViewURL and the DownloadURL can be used to display the purchase right away, although the URLS will expire quickly. In making this request, you will be invoiced at the end of the month for all transactions opened this month.

TransactionOpenRequest 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>
    <TransactionOpenRequest>
        <VendorLineItem>
            <AssetId>4000</AssetId>
            <OrderNumber>12345</OrderNumber>
            <CountryCode>US</CountryCode>
            <UnitPrice>3.99</UnitPrice>
            <LineItemPrice>7.98</LineItemPrice>
            <Quantity>2</Quantity>
            <OrderLineId>56789</OrderLineId>
            <CurrencyCode>USD</CurrencyCode>
            <Personalization>custname:John Customer</Personalization>
        </VendorLineItem>
    </TransactionOpenRequest>
</DAMRequest>

Sheet TransactionOpenResponse 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>
    <TransactionOpenResponse>
        <TransactionItem>
            <AssetId>4000</AssetId>
            <OrderNumber>12345</OrderNumber>
            <OrderLineId>56789</OrderLineId>
            <TransactionId>1122333</TransactionId>
            <FileName>A_B_004000.sco</FileName>
            <FileType>SCORCH</FileType>
            <MimeType>application/x-sibelius-score</MimeType>
            <FileURL>http://haldms.halleonard.com/sf/A_B_004000.sco</FileURL>
            <Footer1>This is the first page footer.</Footer1>
            <Footer2>This is the second page footer.</Footer2>
            <ViewURL mimeType="text/xml">haldms.halleonard.com/nf/viewer/A39NVEXG5TPJ2TNUQ12DRJ8JX27X5WF6</ViewURL>
            <DownloadURL mimeType="application/pdf">haldms.halleonard.com/nf/download/F1U8PFF8RL2F5L2FHHQC8WJ65A7KK9YW</DownloadURL>
            <StatusCode>1</StatusCode>
            <StatusDescription>OK.</StatusDescription>
        </TransactionItem>
    </TransactionOpenResponse>
</DAMResponse>

Displaying the Purchase

The ViewURL, if present in the Transaction Open or Retry response, will display the fully interactive viewer. The DownloadURL will cause a watermarked PDF to be downloaded to the user's computer. If you wish to force the PDF to be displayed in the browser window using the built-in PDF viewer instead of having the user save the file to their computer, you can append "/inline" to the DownloadURL that was provided. In the case of a touch device, the DownloadURL will always display the file in a browser window.

Purchase Mode HTML Code

These URLs expire after 30 minutes so every time the user accesses the purchase, you will need to make another TransactionRetryRequest.

TransactionRetryRequest 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>
    <TransactionRetryRequest>
        <TransactionItem>
            <TransactionId>1122333</TransactionId>
            <Personalization>custname:John Customer</Personalization>
        </TransactionItem>
    </TransactionRetryRequest>
</DAMRequest>

TransactionRetryResponse 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>
    <TransactionRetryResponse>
        <TransactionItem>
            <AssetId>4000</AssetId>
            <OrderNumber>12345</OrderNumber>
            <OrderLineId>56789</OrderLineId>
            <TransactionId>1122444</TransactionId>
            <FileName>A_B_4000.sco</FileName>
            <FileType>SCORCH</FileType>
            <MimeType>application/x-sibelius-score</MimeType>   
            <FileURL>https://haldms.halleonard.com/sf/A_B_4000.sco</FileURL>
            <ParentTransactionId>1122333</ParentTransactionId>
            <ViewURL mimeType="text/xml">haldms.halleonard.com/nf/viewer/A39NVEXG5TPJ2TNUQ12DRJ8JX27X5WF6</ViewURL>
            <DownloadURL mimeType="application/pdf">haldms.halleonard.com/nf/download/F1U8PFF8RL2F5L2FHHQC8WJ65A7KK9YW</DownloadURL>
            <StatusCode>1</StatusCode>
            <StatusDescription>OK.</StatusDescription>
        </TransactionItem>
    </TransactionRetryResponse>
</DAMResponse>

Canceling a Transaction

In order to cancel a transaction because of customer dissatisfaction, purchasing error, etc., you can do so by either using the !Vendor Admin(/getting-started/vendor-admin/#cancel-transactions) or by sending a TransationCancelRequest. The cancel process will mark any related transactions as CANCELLED -- children, grandchildren, sibilings, parents, and grandparents will be marked as CANCELLED. Note that this only affects the transaction data in the DAM System database. It is your responsibility to update your local database and issue any needed refund through your credit card processor. If you have already been billed for a transaction that you cancel, a credit will be issued on a future billing invoice.

TransactionCancelRequest 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>
    <TransactionCancelRequest>
        <TransactionItem>
            <TransactionId>1122444</TransactionId>
        </TransactionItem>
    </TransactionCancelRequest>
</DAMRequest>

TransactionCancelResponse 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>
    <TransactionCancelResponse>
        <TransactionItem>
            <AssetId>4000</AssetId>
            <OrderNumber>12345</OrderNumber>
            <StatusCode>1</StatusCode>
            <StatusDescription>OK.</StatusDescription>
            <TransactionId>1122444</TransactionId>
        </TransactionItem>
    </TransactionCancelResponse>
</DAMResponse>