Notifications for the Payment API

Notifications for the Payment API

Legal Disclaimer This document and the information contained herein (collectively, the "Information") is provided to you (both the individual receiving this document and any legal entity on behalf of which such individual is acting) ("You" and "Your") by AT&T, on behalf of itself and its affiliates ("AT&T") for informational purposes only. AT&T is providing the Information to You because AT&T believes the Information may be useful to You. The Information is provided to You solely on the basis that You will be responsible for making Your own assessments of the Information and are advised to verify all representations, statements and information before using or relying upon any of the Information. Although AT&T has exercised reasonable care in providing the Information to You, AT&T does not warrant the accuracy of the Information and is not responsible for any damages arising from Your use of or reliance upon the Information. You further understand and agree that AT&T in no way represents, and You in no way rely on a belief, that AT&T is providing the Information in accordance with any standard or service (routine, customary or otherwise) related to the consulting, services, hardware or software industries. AT&T DOES NOT WARRANT THAT THE INFORMATION IS ERROR-FREE. AT&T IS PROVIDING THE INFORMATION TO YOU "AS IS" AND "WITH ALL FAULTS." AT&T DOES NOT WARRANT, BY VIRTUE OF THIS DOCUMENT, OR BY ANY COURSE OF PERFORMANCE, COURSE OF DEALING, USAGE OF TRADE OR ANY COLLATERAL DOCUMENT HEREUNDER OR OTHERWISE, AND HEREBY EXPRESSLY DISCLAIMS, ANY REPRESENTATION OR WARRANTY OF ANY KIND WITH RESPECT TO THE INFORMATION, INCLUDING, WITHOUT LIMITATION, ANY REPRESENTATION OR WARRANTY OF DESIGN, PERFORMANCE, MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, OR ANY REPRESENTATION OR WARRANTY THAT THE INFORMATION IS APPLICABLE TO OR INTEROPERABLE WITH ANY SYSTEM, DATA, HARDWARE OR SOFTWARE OF ANY KIND. AT&T DISCLAIMS AND IN NO EVENT SHALL BE LIABLE FOR ANY LOSSES OR DAMAGES OF ANY KIND, WHETHER DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, PUNITIVE, SPECIAL OR EXEMPLARY, INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF GOODWILL, COVER, TORTIOUS CONDUCT OR OTHER PECUNIARY LOSS, ARISING OUT OF OR IN ANY WAY RELATED TO THE PROVISION, NON-PROVISION, USE OR NON-USE OF THE INFORMATION, EVEN IF AT&T HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH LOSSES OR DAMAGES. i

Table of Contents Contents 1 Overview... 5 2 Scenarios for Notification Events... 6 2.1 Grant Events... 7 2.2 Revoke and Conclude Events... 8 2.3 Renewal Events... 8 3 How Notifications Work... 9 4 Preparing to Receive Notifications... 10 5 Duplicate Notification Handling: Sequence Number... 10 6 Reason Code and Message... 12 7 Business Scenarios and Sample Messages... 14 7.1 Purchase a Subscription... 14 7.2 Cancel a Subscription... 14 7.3 Refund a Single Item... 15 7.4 Discontinue a Subscription... 16 7.5 Automatic Subscription Renewal... 17 ii

Table of Tables Figure 1: Payment Notification callback flow... 6 iii

Table of Examples Example 1: Request Example for Grant Event... 14 Example 2: Response Example for Revoke Event... 15 Example 3: Response Example for Revoke Event... 16 Example 4: Request Example for Conclude Event... 16 Example 5: Response Example for Renew Event... 17 iv

1 Overview For businesses that manage access control or customer care, the Payment API provides the ability to send notifications about several types of ownership events that either grant or deny the customer access to a product. As shown in Figure 1, the API Gateway communicates ownership state changes to the external system by sending a one-way SOAP message via HTTP or HTTPS. The external system should be the content provider's system. HTTPS is required for apps in the Production realm. In the case a message fails, the API Gateway has the ability to retry the message at a configurable interval. Page 5 of 11

Figure 1: Payment Notification callback flow The different types of event notifications and the situations in which you might want to receive the notifications are explained below. 2 Scenarios for Notification Events The API Gateway is able to send notifications to any merchant system. The Payment API is, however, targeted at developers that are handling subscriptions, purchase and access control, and customer care. If your app is managing access control, then you must specify that it submits purchase requests to the API Gateway. When the purchase is successfully processed, the API Gateway is able to send a grant notification to the developer's app; which should then enable the customer to Page 6 of 11

access the content. For recurring charge offers, which result in a purchase renewal on a predefined, periodic basis the API Gateway is able to send renewal notifications. If you are managing customer care requests, then you must specify how your app receives the notifications resulting from refund, do-not-renew, and cancellation requests. The Payment Notification supports the following business scenarios. New Transaction: When the customer successfully completes a one-time purchase. The API Gateway generates a grant event. New Subscription: When the customer successfully completes a subscription purchase. The API Gateway generates a grant event. Subscription Renewal: When a customer s subscription is successfully renewed at the end of their current subscription period. The API Gateway generates a renew event. Request a DNR: When the customer requests to discontinue a subscription offer, the customer s access to the content is maintained until the subscription period ends, which is typically the end of a 30-day period. The API Gateway generates a conclude event. Renewal Processing Failure: The subscriptions are automatically discontinued if a renewal cannot be processed successfully. The API Gateway generates a conclude event. Request Cancellation of a Subscription Offer: When the customer receives a refund for the current subscription period via the AT&T Online Assistance Center (OAC), through an AT&T customer service representative (CSR) or via the Refund Transaction method. The API Gateway generates a revoke event. Request a Refund: When the customer requests a refund for a single-item offer or subscription offer. The API Gateway generates a revoke event. 2.1 Grant Events A grant event is sent by the API Gateway when a customer successfully purchases a product. The API Gateway grants the customer access to the product and generates a notification about the grant event. Note: Subscription renewals, which typically occur monthly, do not produce a grant event. A grant event must always precede a revoke event. Grant: Produced when a customer successfully purchases a product offer. Page 7 of 11

2.2 Revoke and Conclude Events A revoke event stops and discontinues the customer s access to content. A revoke event is triggered by a customer s request to cancel a subscription product or to refund a single-item offer. There are two types of revoke events: Revoke and Conclude. Revoke: A revoke event causes the immediate removal of access rights. A revoke event occurs when one of the following happens. The customer cancels a subscription, which automatically triggers a refund request as well. Once ownership of a subscription is revoked, it cannot be restored. The customer must repurchase the subscription offer. In the OAC and AT&T Customer Care Center (CCC) user interfaces, a revoke event correlates to the Stop now and provide refund option. The customer is granted a refund to an item purchase. This revoke event corresponds to the Request Refund option in the OAC and CCC user interfaces. This option is always available in the CCC, but is only available in the OAC for products defined as refundable. The purchase event cannot be completed successfully, in which case the API Gateway revokes the customer s access to the content. The customer must request that their account be closed. Conclude: A conclude event applies only to subscription products. This event occurs when a customer requests a DNR on a subscription offer. The API Gateway allows the customer access to the content until the subscription period ends, at which point a conclude event is produced. There are no refunds involved in this scenario. In the OAC and CCC user interfaces, a conclude event corresponds to the Do not renew option. 2.3 Renewal Events For product offers that use a recurring charge, the API Gateway automatically charges the customer's account on a predefined, periodic basis; usually every month. Each time a recurring Page 8 of 11

charge occurs, the API Gateway creates a renewal event, and the API Gateway sends a notification to the developer's system indicating whether the renewal event was successful. A Renew notification is sent when the renewal processes successfully. This corresponds to the RenewSucceededEvent. A Revoke notification is sent when ownership should be revoked. This corresponds to the RevokeEvent. Note: If the API Gateway is unable to renew the subscription on the first attempt the API Gateway will try again during the subsequent 4 nightly renewal jobs in hopes of getting a successful renewal. This means that it could be an additional 5 days from the expected renewal date before the Renew notification is received. In this scenario, the original renewal date will still stay the same for each month going forward, so the developer s system does not need to recalibrate following a subscription that was on a subsequent try after failing initially. If the API Gateway is unable to renew the subscription after 5 tries, the subscription will be revoked. 3 How Notifications Work When an event occurs due to the scenarios mentioned above, the API Gateway attempts to deliver the event notifications to the callback URI. If notification is successful, the message is removed from the retry queue. If unsuccessful, the message is placed in the retry queue and the retry process takes over at a preconfigured interval. The current preconfigured interval is every 15 minutes for a period of 1 hour. The receiving URI must respond to the source with a success response within 3 seconds, otherwise the notification will be placed in the retry queue, even if the initial delivery was eventually successful after 3 seconds In this example scenario, the developer s system should be configured to ignore any duplicate and retried notifications that are received. Notifications that cannot be delivered remain in the database and can later be resent manually if requested by the developer s system. See the Duplicate Notification Handling: Sequence Number section for more information. The path from the API Gateway to the external system is defined by a destination, which includes a name, an owner, and a URI. A given destination is an HTTP server that can accept multiple event types like revoke, grant, and so on. The event message contains data associated with the event and the parameters associated with the message. Page 9 of 11

4 Preparing to Receive Notifications To receive messages from the API Gateway, you need to do the following: Provide the full callback URI at which you expect to receive messages in the Developer Program website. You should provide this information for both the Staging and Production systems. Set up IP filtering to receive the notification messages, which should come from the API Gateway only. The following are the IP addresses for filtering. 12.129.8.1 through 12.129.8.255 64.25.54.1 through 64.25.54.255 64.25.56.1 through 64.25.56.255 Implement the action to take for each event type including grant, revoke, and conclude. The API Gateway passes data to the external system via HTTPS using the post method. Each ownership event notification interaction consists of an HTTP post containing an XML payload representing an ownership event. 5 Duplicate Notification Handling: Sequence Number Each notification message generated by the API Gateway will receive a per-merchant identifier that will be contiguous across all messages generated for that merchant s system. This sequence number uniquely identifies each message delivered to a merchant s system and because it is contiguous, can be used by the merchant s system to identify duplicate messages and messages their system did not process. The sequence number is not intended to be the order in which messages should be processed. Merchant systems should be able to receive messages out of sequence order. Messages should be processed as they are received independent of sequence number. In addition, duplicate event notification (EN) messages may be received by the merchant s system either because of forced re-delivery of the message or because of an HTTPS request and response exchange between the API Gateway and the merchant s system that is not valid Page 10 of 11

or bad. The developer s system should ignore messages with a sequence number they have already processed. The following table describes a typical series of Payment events along with the sequence number generated for each EN message. Action EN Message Type EN Message Sequence Number Purchase Grant 1 Purchase Grant 2 Refund Revoke 3 Subscriber DNR Conclude 4 Subscription Renewal Renew 5 Purchase Grant 6 As your system receives EN messages, you should record the sequence number of each received message. At set intervals, such as daily or weekly, you should scan the sequence numbers of received EN messages and take note of any gaps in the sequence numbers. These are messages your system did not receive. Missing messages are an issue that merchants should escalate with an AT&T Product Manager by providing the missing sequence numbers for analysis of root cause and manual re-delivery. Note: EN messages that have not been received can only be re-delivered to the same URI at which the delivery was attempted the first time. It is not possible to send historic messages to a new or different URI from the original. Page 11 of 11

6 Reason Code and Message Revokes and concludes can happen for a variety of reasons, including: Revokes caused by CSR requested refunds. Concludes caused by a customer requested Do Not Renew in the Online Assistance Center. Revokes caused by a failure to renew a subscription due to lack of Pre-Paid balance. Note: In order to provide increased visibility into the cause of revokes and concludes to the merchant, the reason code, and reason message attributes are included in notifications. Reason Code Reason Message Relevant EN Events Description 0 Processed Normally GRANT, RENEW The ownership event occurred because of an untracked system event. 1000 Account Closed CONCLUDE The subscription was concluded because the customer s account was closed. 1600 CSR Requested CONCLUDE CSR Requested Conclude Conclude 1640 CSR Requested REVOKE CSR Requested Revoke Revoke 1740 CP Requested REVOKE CP requested Revoked Revoke 1760 CP Requested REVOKE CP Requested Refund Refund 1700 CP requested Conclude CONCLUDE Refund Transaction method performed conclude 2000 Refunded REVOKE The subscription was revoked because the active subscription period was refunded. 3000 User Requested DNR CONCLUDE The customer used the OAC to conclude their subscription. Page 12 of 11

Reason Code Reason Message Relevant EN Events Description 3100 CSR Requested DNR CONCLUDE 3200 Merchant Requested CONCLUDE DNR 5000 PrePaid Insufficient REVOKE Balance 5010 PrePaid System Unavailable 5100 SmartLimits Insufficient Balance 5105 SmartLimits Insufficient Bandwidth Balance 5200 PostPaid Over Spending Limit 5300 Blocked Parental Control REVOKE REVOKE REVOKE REVOKE REVOKE Page 13 of 11 An AT&T CSR concluded the customer s subscription using the CCC tool. A Merchant used the Refund Transaction API method to conclude the subscription. The subscription was revoked when the API Gateway was unable to renew it because of insufficient Pre-Paid balance. The subscription was revoked when the API Gateway was unable to renew it because of the Pre-Paid system being unavailable. The subscription was revoked when the API Gateway was unable to renew it because of insufficient SmartLimits balance. The subscription was revoked when the API Gateway was unable to renew it because of insufficient SmartLimits bandwidth balance. The subscription was revoked when the API Gateway was unable to renew it because the account was over its PostPaid spending limit. The subscription was revoked when the API Gateway was unable to renew it because the account had parental controls enabled. 5700 Account Not Billable REVOKE The subscription was revoked when the API Gateway was unable to renew it because the account changed to an un-billable status. 5800 Account Not Found in ED 5900 Inactive Product Offer REVOKE REVOKE The subscription was revoked when the API Gateway was unable to renew it because the account was no longer found in the Enterprise Directory (ED). The subscription was revoked when the API Gateway was unable to renew it because the product offer is no longer active.

7 Business Scenarios and Sample Messages The following scenarios illustrate the customer activities supported by External Notification, along with the associated behavior of the API. Note: All customer and business names used in these scenarios are fictitious. 7.1 Purchase a Subscription Customer 1 has a daily commute that is wrought with traffic problems, so the customer decides to subscribe to a traffic alert service from company 1. Company 1 uses the Payment API provided by AT&T to make a purchase request. When the API Gateway processes the initial $4.99 charge, a grant notification is generated that is sent to the company 1 system. The notification message looks like this. 1 <?xml version="1.0" encoding="utf-8"?> 2 <ownershipevent type="grant" timestamp="2003-01-16t10:32:15+00:00"> 3 <networkoperatorid>cingular</networkoperatorid> 4 <owneridentifier>mms-2529925543</owneridentifier> 5 <purchasedate>2003-01-14t09:42:08+00:00</purchasedate> 6 <productidentifier>traf34567</productidentifier> 7 <purchaseactivityidentifier>bc4ukz/jvl4aaaoaaqqx2xwwckbfbq+gi64= </purchaseactivityidentifier> 8 <instanceidentifier>rep25</instanceidentifier> 9 <minidentifier>2529925543</minidentifier> 10 <sequencenumber>1</sequencenumber> 11 <reasoncode>0</reasoncode> 12 <reasonmessage>processed Normally</reasonMessage> 13 <vendorpurchaseidentifier>inv123</vendorpurchaseidentifier> 14 </ownershipevent> Example 1: Request Example for Grant Event 7.2 Cancel a Subscription Customer 2 subscribed to a football score service offered by company 1 and within a few days he decided to cancel it and get a refund. Customer 1 calls AT&T customer service and the CSR Page 14 of 11

uses the AT&T Customer Care Center application to cancel the subscription and refund the purchase amount. When the API Gateway processes these requests, a revoke External Notification message is generated and sent to the company 1 system, telling it that customer 2 has cancelled the subscription. It is up to company 1 to revoke the access to the product for customer 2. The XML message sent by the API Gateway looks like Example 2. 1 <?xml version="1.0" encoding="utf-8"?> 2 <ownershipevent type="revoke" timestamp="2003-03-14t16:21:12+00:00" effective="2003-03-14t16:21:12+00:00"> 3 <networkoperatorid>cingular</networkoperatorid> 4 <owneridentifier>mms-2067438956</owneridentifier> 5 <purchasedate>2003-03-10t10:15:05+00:00</purchasedate> 6 <productidentifier>foot4231</productidentifier> 7 <purchaseactivityidentifier>bc4ukz/jvl4aaaoaaqqx2xwwckbfbq+ai74= </purchaseactivityidentifier> 8 <instanceidentifier>chicago bears</instanceidentifier> 9 <minidentifier>2067438956</minidentifier> 10 <sequencenumber>2</sequencenumber> 11 <reasoncode>2000</reasoncode> 12 <reasonmessage>refunded</reasonmessage> 13 <vendorpurchaseidentifier>inv124</vendorpurchaseidentifier> 14 </ownershipevent> Example 2: Response Example for Revoke Event 7.3 Refund a Single Item Customer 3 purchased a game written in Java that the customer did not like, so the customer calls AT&T customer service to request a refund. The CSR uses the AT&T Customer Care Center application to look up the product and then requests a refund on the customer s behalf. When the API Gateway processes this request, a message is sent to company 2. The message informs the company 2 system that customer 3 has requested a refund. It is up to company 2 to revoke the access to the game for customer 3. The XML message sent by the API Gateway looks like Example 3. 1 <?xml version="1.0" encoding="utf-8"?> 2 <ownershipevent type="revoke" timestamp="2003-03-14t16:21:12+00:00" effective="2003-03-14t16:21:12+00:00"> 3 <networkoperatorid>cingular</networkoperatorid> 4 <owneridentifier>mms-2529785543</owneridentifier> 5 <purchasedate>2003-03-10t10:15:05+00:00</purchasedate> 6 <productidentifier>web34567</productidentifier> Page 15 of 11

7 <purchaseactivityidentifier>bc4ukz/jvl4aaaoaaqqx2xwwckbfbq+bi84= </purchaseactivityidentifier> 8 <instanceidentifier></instanceidentifier> 9 <minidentifier>2529785543</minidentifier> 10 <sequencenumber>1</sequencenumber> 11 <reasoncode>2000</reasoncode> 12 <reasonmessage>refunded</reasonmessage> 13 <vendorpurchaseidentifier>gg123</vendorpurchaseidentifier> 14 </ownershipevent> Example 3: Response Example for Revoke Event 7.4 Discontinue a Subscription Customer 4 has been subscribing to sports score alerts from company 1 for a while and has grown tired of company 1. Although customer 4 wants to complete the current subscription, the customer has decided not to renew the current subscription when it is completed. So customer 4 accesses the AT&T OAC and views the details for this subscription. Customer 4 clicks on the Cancel Subscription selection and then selects the Do not renew option. When the API Gateway receives this information, a message is sent to the content provider. The message informs company 1 that customer 4 does not want to renew the subscription when it expires. It is up to company 1 to take the appropriate action. The XML message sent by the API Gateway looks like Example 4. 1 <?xml version="1.0" encoding="utf-8"?> 2 <ownershipevent type="conclude" timestamp="2003-02-01t18:42:10+00:00" effective="2003-02-22t12:00:00+00:00"> 3 <networkoperatorid>cingular</networkoperatorid> 4 <owneridentifier>mms-4253329807</owneridentifier> 5 <purchasedate>2002-10-21t17:24:08+00:00</purchasedate> 6 <productidentifier>sportsprovider4231</productidentifier> 7 <purchaseactivityidentifier>bc4ukz/jvl4aaaoaaqqx2xwwckbfbq+bi84= </purchaseactivityidentifier> 8 <instanceidentifier>sports1</instanceidentifier> 9 <minidentifier>4253329807</minidentifier> 10 <sequencenumber>3</sequencenumber> 11 <reasoncode>3000</reasoncode> 12 <reasonmessage>user Requested DNR</reasonMessage> 13 <vendorpurchaseidentifier>inv101</vendorpurchaseidentifier> 14 </ownershipevent> Example 4: Request Example for Conclude Event Page 16 of 11

7.5 Automatic Subscription Renewal At the end of the month, customer 5 has a month-to-month subscription renewal that comes up for processing by the API Gateway. After applying the charge successfully to customer 5 s account, a message is sent to Company 1. The XML message sent by the API Gateway looks like Example 5. 1 <?xml version="1.0" encoding="utf-8"?> 2 <ownershipevent type="renew" timestamp="2003-02-22t12:01:22+00:00> 3 <networkoperatorid>cingular</networkoperatorid> 4 <owneridentifier>mms-4253329807</owneridentifier> 5 <purchasedate>2002-10-21t17:24:08+00:00</purchasedate> 6 <productidentifier>sportsprovider4231</productidentifier> 7 <purchaseactivityidentifier>bc4ukz/jvl4aaaoaaqqx2xwwckbfbq+bi84= </purchaseactivityidentifier> 8 <instanceidentifier>atlanta falcons</instanceidentifier> 9 <minidentifier>4253329807</minidentifier> 10 <sequencenumber>5</sequencenumber> 11 <reasoncode>0</reasoncode> 12 <reasonmessage>processed Normally</reasonMessage> 13 <vendorpurchaseidentifier>inv101</vendorpurchaseidentifier> 14 </ownershipevent> Example 5: Response Example for Renew Event Page 17 of 11