View source for Direct Delivery and Automatic Notification System

<noinclude>
{{Navbox/Marketplace/en}}
</noinclude>
In the early days of the SL Exchange virtual goods sales website, the authors of the site implemented a feature that came to be known as “Automatic Notification System” or {{abbr|ANS|Automatic Notification System}} for short. Details about every sale made through the website were bundled into a single transaction and forwarded to either an outside website or an In-World object.

SL Exchange then changed their name to [[:Category:Xstreet|XStreet SL]], at which point Linden Lab purchased it and then retired it in favor of their new SL Marketplace. After the release of the SL Marketplace, they continued to support the ANS feature and even enhanced it some by redefining some of the values provided and reusing some that had fallen into disuse.

Now that Linden Lab has released their Direct Delivery service, the ANS feature has again been modified to support the same functionality and to ensure its viability into the future.

== Who Should Read This Document ==
If you are a Merchant already using ANS as it exists for support of sales made through the Magic Box, then you will want to read this document to learn how it has been changed and what you will need to do in order to support the new format and features of ANS.

If you are a Merchant that is either not familiar with ANS or is not currently using it but you would like more control over your sales and customer data, you should read this document to learn how it might help you track sales, support your customers, compile marketing and advertising data and give you better information about your business.

== ANS Overview ==
The ANS feature of the SL Marketplace forwards information about every sale made on the SL Marketplace to an outside website. A program or web page on the receiving site is responsible for accepting the information, called an ANS Transaction Record, and processing it in whatever fashion is desired. That program or web page is called the “ANS Processor”.

In order to make use of the ANS Transaction Record, you must be capable of writing and hosting the ANS Processor yourself; Linden Lab does not provide this service. If you are not able to do the programming yourself but you wish to utilize the information provided by ANS, you may wish to contact one of the third parties that offers ANS Processing Services<ref>Probably only [https://www.casperdns.com/ Casper] at this time (— {{u|Gwyneth Llewelyn}}, May 2023)</ref>.

== Versions of ANS ==
There are two different versions of ANS presently supported by the SL Marketplace. One version called “ANS/XS” supports sales delivered only from a Magic Box. It is sent by the old XStreet SL website and has been in use by the SL Marketplace. The other version called “ANS/SLM” supports sales delivered via Magic Boxes or Direct Delivery and is sent by the SL Marketplace. Most of the information provided by the two versions is identical; however, there are key differences that are important to understand.

{{NormalNote|It is possible to have both versions of ANS active at the same time. If you are already using ANS/XS and begin using ANS/SLM then you will receive two transactions for products delivered by a Magic Box, one from each source. Your ANS Processor should be capable of accepting duplicated transactions.}}
=== ANS/XS – ANS for XStreet SL ===
The ANS Transaction Record sent by the XStreet SL website defines the item delivered and specific details about the product on the SL Marketplace. The transaction record also includes information needed to verify that the record is correct and represents a valid sale. ANS/XS is capable of sending the ANS Transaction Record to either an external website or to an In-World Object. Note that the ANS Transaction Record is sent only for sales delivered by a Magic Box.

=== ANS/SLM – ANS for the SL Marketplace ===
The ANS Transaction Record sent from the SL Marketplace website contains the same basic information. However, the method of validating an ANS/SLM transaction varies significantly from that used for ANS/XS. Furthermore, the ANS/SLM version will only send an ANS Transaction Record to an external website; it does not support sending the record to an In-World Object. ''The ANS/SLM Transaction Record is sent for every sale regardless of the delivery method, Magic Box or Direct Delivery.''

== Basic ANS Transaction Record ==
The basic ANS Transaction Record contains the following information. Note that the order of the fields is not important; your ANS Processor should be capable of accepting the fields in any order provided.

{| style="padding:4px; border:1px solid gray" | style="border-collapse:collapse; padding:4px; border:1px solid black; background-color:#eee"
|- style="padding:4px; border:1px solid gray"
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Field Name
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Description
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Type
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Size
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Comments
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | Currency
| style="padding:4px; border:1px solid gray" | The type of currency used for the purchase.
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 10
| style="padding:4px; border:1px solid gray" | Always "SLL"
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | Type
| style="padding:4px; border:1px solid gray" | The type of transaction
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 50
| style="padding:4px; border:1px solid gray" | "Purchase", or "Redelivery"
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | PaymentGross
| style="padding:4px; border:1px solid gray" | The total amount of the purchase price paid
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 12
| style="padding:4px; border:1px solid gray" | &nbsp;
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | PaymentFee
| style="padding:4px; border:1px solid gray" | The commission fee charged by the SL Marketplace
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 12
| style="padding:4px; border:1px solid gray" | &nbsp;
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | PayerName
| style="padding:4px; border:1px solid gray" | The Purchaser’s Account Name
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 100
| style="padding:4px; border:1px solid gray" | Note 5
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | PayerKey
| style="padding:4px; border:1px solid gray" | The Purchaser’s Avatar UUID
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 36
| style="padding:4px; border:1px solid gray" | &nbsp;
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | ReceiverName
| style="padding:4px; border:1px solid gray" | The Receiver’s Account Name
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 100
| style="padding:4px; border:1px solid gray" | Note 5
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | ReceiverKey
| style="padding:4px; border:1px solid gray" | The Receiver’s Avatar UUID
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 36
| style="padding:4px; border:1px solid gray" | &nbsp;
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | MerchantName
| style="padding:4px; border:1px solid gray" | The Merchant’s Account Name
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 100
| style="padding:4px; border:1px solid gray" | Note 5
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | MerchantKey
| style="padding:4px; border:1px solid gray" | The Merchant’s Avatar UUID
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 36
| style="padding:4px; border:1px solid gray" | &nbsp;
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | TransactionID
| style="padding:4px; border:1px solid gray" | SL Marketplace Order Number
| style="padding:4px; border:1px solid gray" | bigint
| style="padding:4px; border:1px solid gray" | 20
| style="padding:4px; border:1px solid gray" | &nbsp;
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | ItemID
| style="padding:4px; border:1px solid gray" | SL Marketplace Product ID Number
| style="padding:4px; border:1px solid gray" | int
| style="padding:4px; border:1px solid gray" | 10
| style="padding:4px; border:1px solid gray" | Note 1
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | ItemName
| style="padding:4px; border:1px solid gray" | SL Marketplace Product Name
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 100
| style="padding:4px; border:1px solid gray" | Note 2
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | InventoryName
| style="padding:4px; border:1px solid gray" | Magic Box Contents Object Name
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 100
| style="padding:4px; border:1px solid gray" | Note 3
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | Location
| style="padding:4px; border:1px solid gray" | SL Marketplace Order Line Item ID Number
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 40
| style="padding:4px; border:1px solid gray" | Note 4
|}

''Note 1: Every product listed on the SL Marketplace is assigned a unique Product ID Number. You can determine a product’s ID Number by examining the URL of the Product’s Listing page. The Product ID Number is the last part of the URL.''

''Note 2: This is the Item Name as shown on the Product’s Listing Page on the SL Marketplace.''

''Note 3: This is the name of the Inventory Object or the Top-Level Folder delivered when the Product is purchased. In the case of ANS/XS it will always be the name of the Object contained within the Contents of the Magic Box. For ANS/SLM it is the name of the Object (if delivered from a Magic Box) or the Top-Level Folder (if delivered via Direct Delivery).''

''Note 4: Orders on the SL Marketplace may contain up to 10 separate items, each detailed on a separate line. The Line Item ID Number uniquely identifies the specific line item within the Order.''

''Note 5: The Account Name is either two words for older "Legacy" names or one word for newer single-word accounts; the last name "Resident" is not included for single-word account names.''

=== ANS/XS Specific Fields ===
When a product is delivered from a Magic Box, there is one additional field included that will contain important data as follows:

{| style="padding:4px; border:1px solid gray" | style="border-collapse:collapse; padding:4px; border:1px solid black; background-color:#eee"
|- style="padding:4px; border:1px solid gray"
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Field Name
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Description
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Type
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Size
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Comments
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | VerifyKey
| style="padding:4px; border:1px solid gray" | Transaction Specific Verification Key
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 100
| style="padding:4px; border:1px solid gray" | &nbsp;
|}
,
The VerifyKey field will contain a 32-character string that is supplied to the XStreetSL.com website for verification. If the ANS Transaction is valid, the XStreetSL.com website will return “SUCCESS”; otherwise, it will return “FAILURE”.

In order to verify each transaction, your ANS/XS Processor must perform an HTTP GET to the following URL:

{{Indent60px|<pre><nowiki>https://www.xstreetsl.com/ans.php?VerifyKey=&lt;VerifyKey&gt;</nowiki></pre>}}

You must include the 32-character string supplied in the VerifyKey field as part of the URL as shown above.

=== ANS/SLM Specific Fields ===
When a product is delivered from the SL Marketplace, the VerifyKey field is included but it will always be empty and thus can be disregarded. Additionally, the Region field contains the hard-coded text “SLM”. This field can be used to verify that the source of the ANS Transaction is the SL Marketplace.

{| style="padding:4px; border:1px solid gray" | style="border-collapse:collapse; padding:4px; border:1px solid black; background-color:#eee"
|- style="padding:4px; border:1px solid gray"
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Field Name
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Description
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Type
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Size
! style="padding:4px; border:1px solid gray; background-color:black; color:white" | Comments
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | VerifyKey
| style="padding:4px; border:1px solid gray" | Transaction Specific Verification Key
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 100
| style="padding:4px; border:1px solid gray" | Always empty
|- style="padding:4px; border:1px solid gray"
| style="padding:4px; border:1px solid gray" | Region
| style="padding:4px; border:1px solid gray" | Website Identifier
| style="padding:4px; border:1px solid gray" | varchar
| style="padding:4px; border:1px solid gray" | 100
| style="padding:4px; border:1px solid gray" | Always "SLM"
|}

=== Validating an ANS/SLM Transaction Record ===
Included in the HTTP Headers sent to your ANS/SLM Processor is a 40-character Verification Hash that can be used to compare against the 40-character {{Wikipedia|SHA-1|SHA1}} Hash calculated by your ANS/SLM Processor. The Verification Hash calculated by the SL Marketplace is provided in the {{mono|X-ANS-Verify-Hash}} header field and can be read by accessing the “{{mono|HTTP_X_ANS_VERIFY_HASH}}” header<ref>The confusion between the two styles of writing the name of this HTTP header has mostly to do with the way Apache/mod_php reinterprets the headers; it might not apply on different programming languages systems and/or different ways of running the PHP interpreter with the webserver (e.g. PHP-FPM). — {{u|Gwyneth Llewelyn}}, May 2023</ref>. In addition to the Verification Hash, your processor must also know your Merchant-specific Salt Code.

When you set the URL of your ANS/SLM Processor in the [[Direct Delivery and Automatic Notification System/Where to Set the ANS URL|Merchant ANS Configuration]], a Salt Code will be generated and displayed. You must note the Salt Code and program it into your ANS/SLM Processor (or add it to your Third-Party Merchant Configuration). Once the Salt Code is known, you can calculate the Verification Hash and compare it against the Verification Hash provided in the {{mono|X-ANS-Verify-Hash}} header.

=PHP Example=

Here is an example PHP snippet that retrieves the proper HTTP Header containing the Verification Hash provided by the SL Marketplace then uses the ANS Transaction Record and the Salt Code to calculate and compare to the Verification Hash.

<syntaxhighlight lang="php">
<?php

$myDDHash = $_SERVER['HTTP_X_ANS_VERIFY_HASH'];
$myDDSalt = <Your Salt Code Here>;

$myCalcHash = sha1($_SERVER['QUERY_STRING'] . $myDDSalt);

if ($myDDHash == $myCalcHash) {
	echo "Valid ANS Transaction";
} else {
	echo "Invalid ANS Transaction";
}

</syntaxhighlight>

=C# Example=
Here's a corresponding .NET Framework 3.5/C# example:

<syntaxhighlight lang="csharp">
// ANS Validation - Antonius Frentis
string calcHash;
string saltCode = "Your Salt Code Here";
string serverHash = Request.Headers["X-ANS-Verify-Hash"];

calcHash = FormsAuthentication.HashPasswordForStoringInConfigFile(Request.Url.Query.Remove(0,1) + saltCode, "SHA1").ToLowerInvariant();
if (calcHash == serverHash)
{
	// Valid ANS Transaction
}
else
{
	// Invalid ANS Transaction
}
</syntaxhighlight>

=Python Example=

Here is an example in [https://www.python.org/ Python] to process the information sent and to check the verification hash. Note that the salt is hardcoded in the code, and it is provided simply as an example of how to process the fields and verify the message using Python. 

It relies on having a web server properly configured to launch CGI binaries safely, which will usually be under a special {{Mono|../cgi-bin/}} directory, by convention. Thus, the URL to be written on the Marketplace will look like {{Mono|https://example.com/cgi-bin/my-python-receiver}}.

The code assumes a Unix/Linux environment<ref>And very likely running Apache. — ''[[User:Gwyneth_Llewelyn|Gwyn]]''</ref>, but if your Python interpreter lives elsewhere, you need to change the first line to reflect the actual path to it.

<syntaxhighlight lang="python">
#!/usr/bin/env python

import os
import sys
import cgi
import hashlib

# Open the file to write the information to and post the HTTP header
fp = open("/tmp/ans.txt","w")
print("Content-Type: text/html\n\n");

# Print out the verification hash
try:
      fp.write("Verify: {0}\n".format(os.environ['HTTP_X_ANS_VERIFY_HASH']))
except KeyError:
      print("Error - no verification string sent")
      fp.close()
      sys.exit()

# Check to see if the query string is consistent with the verification
# hash
mySalt = "1234567890abcdef"   # This is the salt given to us in the marketplace
checkHash = hashlib.sha1()

try:
      checkHash.update(os.environ['QUERY_STRING'])
except KeyError:
      print("Error - no query string sent")
      fp.close()
      sys.exit()

checkHash.update(mySalt)
fp.write("Query string hash: {0}\n".format(checkHash.hexdigest()))

# Now print out all of the form fields 
formValues = cgi.FieldStorage()
fp.write("\n\nForm fields:\n")
for a in formValues:
   fp.write("{0}: {1}\n".format(a,formValues.getfirst(a)))

# Finally print out the uuid of the account that the item was sent to.
try:
  fp.write("The UUID of the person who received this item is {0}\n".format(\
      formValues.getfirst('ReceiverKey')))
except KeyError:
  fp.write("There was no receiver listed.\n")

fp.flush()
fp.close()

</syntaxhighlight>

The Python code above will create a file {{Mono|/tmp/ans.txt}} which will resemble the following text:

{{Indent60px|<pre><nowiki>
Verify: db10b66eafefe87e8484b0e9547ae28ce3763e86
Query string hash: db10b66eafefe87e8484b0e9547ae28ce3763e86


Form fields:
ItemID: 5555555
ReceiverName: buyer resident
MerchantName: seller resident
MerchantKey: 111222333444555666
ReceiverKey: 777888999000aaabbb
InventoryName: Gift Card For You
Type: Purchase
Region: SLM
PaymentFee: 6
Currency: SLL
PaymentGross: 125
Location: 1234567890
PayerKey: 777888999000aaabbb
TransactionID: 998877665544
ItemName: Gift Card For You
PayerName: buyer resident
The UUID of the person who received this item is 777888999000aaabbb
</nowiki></pre>}}

[[Category:Marketplace]]