From Apez

Automated Notification System

The Automated Notification System (ANS) provides notification of Apez events to external entities, such as web-servers or in-world objects.

It can use either HTTP GET to notify a web-service or email (for example to notify in-world objects or any system that can process automated emails). It is modeled after the [PayPal] Name Value Pair mechanism and is also supported by other SL services, such as SL Exchange.

Apez currently provides notifications for vend service sales. You can set the relevant options from the preferences page.

Format

The notifications consist of a set of variables and values. In the case of HTTP GET, the variables and values are provided as standard URL parameters (the values being URL encoded). For email notifications, the variable-value pairs are separated by a vertical bar character "|" (and the entire message is also enclosed by vertical bars). For the HTTP method the server should return the provided validation code (see below).

For example, if you've set your ANS to URL "http://my.site.com/ans.php" the notification will access the web-server with a URL such as:

http://my.site.com/ans.php?Source=Apez&Type=Purchase&MerchantName=Joe+Avatar& ... etc

In the case of email notifications, the email body will contain:

|Source=Apez|Type=Purchase|MerchantName=Joe+Avatar| ... |

The order of the variables is not significant and can change.

Variables

Common

• Source - always "Apez"
• Grid - "SL:Production" (may take other values in future)
• Timestamp - Unix timestamp (seconds since Epoch) of when event occurred or notification was made
• Timestamp8601 - Timestamp in ISO8601 format (UTC/Zulu timezone) - yyyy-MM-ddTHH:mm:ssZ
• ValidationCode - a string that the server should return to indicate the ANS was received/processed

Purchase

• Type - "Purchase"
• Currency - standard foreign 3-letter currency codes (e.g. "USD"). L$ is denoted "LLD" (note: other providers use "SLL").
• SaleID - an (upto) 20 digit ID unique to each sale
• TransactionID - an (upto) 20 digit ID unique to the transaction representing the buyer's payment
• ProductID - Product ID (as found on the product settings page)
• PaymentGross - amount payed by the buyer (in specified currency)
• PaymentShared - amount shared (e.g. via share group, if any)
• PaymentCommission - amount deducted in commissions (both applicable Apez and reseller sales commissions)
• BuyerKey - key of the buyer avatar
• BuyerName - name of the buyer avatar
• SellerKey - key of the seller avatar (e.g. often the vendor owner)
• SellerName - name of the seller avatar
• MerchantKey - key of merchant avatar (product owner)
• MerchantName - name of merchant avatar
• ReceiverKey - key of avatar to which item was delivered (buyer, unless gift purchase)
• Receivername - name of avatar to which item was delivered
• ProductName - Product name (at notification time)
• InventoryName - Name of inventory item delivered (as in iServ)
• CollectionName - Product collection name containing product
• Region - Grid region/sim name (if in-world sale) or blank
• Location - Grid region/sim local x,y,z coordinates (if in-world sale) or blank
• SecurityCodeSaleHash - hash used to confirm this notification originated from Apez (see below)

Additional variables for cross-service-provider compatibility

• PaymentFee - Fees charged for sale (currently same as commission above)
• PayerKey - same as BuyerKey
• PayerName - same as BuyerName
• ItemID - same as ProductID
• ItemName - ProductName if product sale, InventoryName otherwise

Validation

The online options for ANS on the prefs page include a Security Code field. The SecurityCodeSaleHash variable will have the value of the MD5 hash of the string formed by contatenating the Security Code, the SaleID and the string ":0". For example, in LSL, this can be computed as:

string expectedSecurityCodeSaleHash = llMD5String(securityCode + saleID, 0);

and in PHP:

$expectedSecurityCodeSaleHash = md5($securityCode . $saleID . ":0");

This will always be unique since the SaleID is unique. If the computed hash isn't the same as the value provided in the ANS notification then the notification did not originate from Apez (or your chosen Security Code has been guessed/compromised).

For HTTP GET ANS notifications, the accessed server should return the string "ok:" followed by the provided ValidationCode in the body of the response so that the Apez server knows the notification was received. If the DNS lookup fails, the server can't be contacted, or the GET response doesn't contain that string, the Apez server will assume the notification wasn't delivered.

Notes

At this time the Apez server doesn't re-try failed ANS notifications, but will do so in the near future.

The HTTP GET response may contain other data, such as HTML tags etc, but must contain the ok:<ValidationCode> string embedded somewhere. The length of the response should be kept to a minimum (excessively large responses will cause ANS to be disabled).

Currently, the Apez sales processing occurs when a sale is triggered from online or when the sale event from a vendor in-world is received. This is when the ANS notification is issued. Hence, it is possible that the delivery may still fail after this time and, if automatic refunds are enabled, the buyer may be refunded. In future, the sales processing will occur only after successful delivery and ANS notifications will be made only at that time.