AT&T API Platform SDK for Microsoft®  2.3.3
Wrapper classes that allow developers to build robust applications using .NET
 All Classes Namespaces Functions Enumerations Properties
Payment Service Cookbook

Overview

This cookbook shows you how to develop a Payment Service application using the Platform SDK for Microsoft.
The Platform SDK for Microsoft provides the following methods:

  • Create a New Transaction (Single pay)
  • Get Transaction Status
  • Refund a Transaction
  • Create a new Subscription
  • Get Subscription Status
  • Get Subscription Details
  • Refund a Subscription
  • Get and Acknowledge Notifications from the AT&T Platform

To use these methods in an application, perform the following steps:

  1. Add a reference to the SDK as shown in the About the Cookbooks section and import the ATT_MSSDK.Paymentv3 and ATT_MSSDK.Notaryv1 namespaces.
  2. Create an instance of RequestFactory with the scope type RequestFactory.ScopeTypes.Payment, as shown in the About the Cookbooks section.
  3. Invoke the Payment Service methods using the RequestFactory instance.

Creating a New Transaction (Single Pay)

To create a new transaction in your Payment Service application, complete the following steps.

Step 1. Notarize and Encrypt the transaction payload

To notarize and encrypt the transaction payload, invoke the GetNotarizedForNewTransaction method using the RequestFactory instance by passing the amount, category, description, transactionId, productId, redirectUrl and transactionOperationStatus as arguments as shown in the following code example. The Notary Response returned by this method can be used to initiate a new Transaction Purchase in the next step.

 double amount = x.xx;
 string category = "xxxxxxxxxxxx";
 string description = "xxxxxxxxxx";
 string transactionId = "xxxxxxxxxxxxxxxxxx";
 string productId = "xxxxxxxxxxxx";
 string redirectUrl = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";
 string transactionOperationStatus = "xxxxxxx";
 NotaryResponse nr = this.GetNotarizedForNewTransaction(amount, category, description, transactionId, productId, redirectUrl, 
                                                      transactionOperationStatus);

Step 2. Get New Transcation Redirection URL

To get the redirect URL that points to AT&T Payment Platform, invoke the GetNewTransactionRedirect method using the RequestFactory instance by passing the Notary Response that was returned by GetNotarizedForNewTransaction in the previous step. This URL is used by the application to redirect the user to the AT&T payment endpoint which collects user consent for the transaction.

 string TransactionRedirectUrl = "";
 TransactionRedirectUrl = GetNewTransactionRedirect(NotaryResponse notaryResponse);

Step 3. Redirect the user to AT&T payment platform

Redirect the subscriber's browser to the URL that was returned by the GetNewTransactionRedirect method in the previous step.

 Response.Redirect(transactionRedirectUrl);

Step 4. User Authorizes the payment

The AT&T Platform displays a login page, authenticates the user's credentials, displays the Advice of Charge page, and requests that the user authorizes the payment transaction.

Step 5. Receive Transaction Authenticate Code

Once the user authorizes the payment transaction, the AT&T Platform processes the payment transaction and returns control back to application with 'TransactionAuthCode' as a query string. The TransactionAuthCode can then be used to get the status of the transaction.

Getting the Status of a Transaction

To get the status of a previously executed transaction, invoke the GetTransactionStatus method using the RequestFactory instance by passing TransactionAuthCode/TransactionId as shown in the following code example.

 TransactionStatus transactionStatus = null;
 string keyValue = "xxxxxxxxxxx";
 transactionStatus = this.requestFactory.GetTransactionStatus(TransactionIdTypes.MerchantTransactionId, keyValue);

Refunding a Transaction

To refund a transaction, invoke the Refund method using the RequestFactory instance by passing the TransactionId as shown in the following code example.

 string refundResponseId = string.Empty;
 string transactionId = "xxxxxxxxxxxxxxx";
 refundResponseId = this.requestFactory.Refund(transactionId, 1, "Customer was not happy");

Creating a New Subscription

To create a new subscription in your Payment Service application, complete the following steps.

Step 1. Get New Subscription Redirection URL

To get the redirect URL that points to the AT&T Payment Platform, invoke the GetNewSubscriptionRedirect method using the RequestFactory instance by passing the amount, category, description, transactionId, productId, redirectUrl, and transactionOperationStatus as shown in the following code example.

 double amount = 1.99;
 string  description = "xxxxxxxx";
 string merchantTransactionId = "xxxxxxxxxxxxxxx";
 string merchantProductId = "xxxxxxxxxxxxxxxxxxxxxxxxx";
 string merchantRedirectURI = "xxxxxxxxxxx";
 string subscriptionRedirect = requestFactory.GetNewSubscriptionRedirect(amount, PaymentCategories.ApplicationGames, 
                                  description, merchantTransactionId, merchantProductId, merchantRedirectURI);

Step 2. Redirect the user to AT&T payment platform

Redirect the subscriber's browser to the URL that was received as a response to the GetNewSubscriptionRedirect method.

 Response.Redirect(subscriptionRedirect);

Step 3. User Authorizes the payment

The AT&T Platform displays a login page, authenticates the user's credentials, displays the Advice of Charge page, and requests that the user authorizes the payment transaction.

Step 4. Receive Transaction Authenticate Code

Once the user authorizes the payment transaction, the AT&T Platform processes the payment transaction and returns control back to the application with 'TransactionAuthCode' as a query string. The TransactionAuthCode can then be used to get the status of the subscription.

Getting the Status of a Subscription

To get the status of a previously executed subscription, invoke the GetSubscriptionStatus method using the RequestFactory instance by passing TransactionAuthCode/TransactionId as shown in the following code example.

 string subsMerTrId = "xxxxxxxx";
 SubscriptionStatus subscriptionStatus = null;
 subscriptionStatus = requestFactory.GetSubscriptionStatus(SubscriptionIdTypes.MerchantTransactionId, subsMerTrId);

Getting the details of a Subscription

To get the details of a subscription, invoke the GetSubscriptionDetails method using the RequestFactory instance by passing the subscription Id and consumer Id as shown in the following code example.

 string merchantSubscriptionId = "xxxxxxxxxxxx";
 string consumerId = "xxxxxxxxxxxxxx";
 SubscriptionDetails subscriptionDetails = null;
 subscriptionDetails = requestFactory.GetSubscriptionDetails(merchantSubscriptionId, consumerId);

Refunding a Subscription

Invoke Refund

To refund a subscription, invoke the Refund method using the RequestFactory instance by passing the subscription id, and refund reason as shown in the following code example.

 string refundResponseId = string.Empty;
 string subscriptionId = "xxxxxxxxxxxxxx";
 refundResponseId = this.requestFactory.Refund(subscriptionId, 1, "Customer was not happy");

Getting and Acknowledging Notifications from the AT&T Platform

The AT&T Platform sends notifications based on certain events that are relevant to a merchant. For this release of the AT&T API Platform SDK for Microsoft®, these events are: refund, stop subscription, cancel subscription, and restore subscription. The merchant's application must set up a callback listener that will accept these notification requests. This is done by registering a callback listener application URL with the AT&T Developer Program at https://devconnect-api.att.com. The notification request message will only contain the notification identifiers. The merchant application should use the notification identifiers that are passed in the notification request message to retrieve the details of the notification using the GetNotification method. When the application has received the notification, it can stop the notification of a particular event by invoking the AcknowledgeNotification method.

To get and acknowledge the notifications in the callback listener application, do the following:

Step 1. Add a reference to the SDK

Import the ATT_MSSDK and ATT_MSSDK.ATT_MSSDK.Paymentv3 namespaces.

 using System.Web;
 using ATT_MSSDK;
 using ATT_MSSDK.Paymentv3;

Step 2. Create an instance of RequestFactory

To Create an instance of the RequestFactory class that identifies your application and provides access to the Payment Service, pass the API Key and Secret Key values that were assigned to your application when you registered it with AT&T and pass a scope value of RequestFactory.ScopeTypes.Payment, as arguments to the RequestFactory constructor.

 string endPoint = "xxxxxx.xxxxx.xxx";
 string apiKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";  //API Key of the Payment Service application registered at devconnect.
 string secretKey = "xxxxxxxxxxxxxxxx";  //Secret Key of the Payment Service application registered at devconnect.
 List<RequestFactory.ScopeTypes> scopes = new List<RequestFactory.ScopeTypes>();
 scopes.Add(RequestFactory.ScopeTypes.Payment);
 RequestFactory requestFactory = new RequestFactory(endPoint, apiKey, secretKey, scopes, null, null);

Step 3. Invoke GetNotificationIds

Invoke the GetNotificationIds method using the RequestFactory instance. This method reads the Input stream and returns a list of notification identifiers that are received from the AT&T Platform.

 List notificationIds = this.requestFactory.GetNotificationIds(Request.InputStream); //Request.InputStream provided by .Net Framework to get the contents of the incoming http entity body.

Step 4. Invoke GetNotification

Invoke the GetNotification method using the RequestFactory instance by passing each notification identifier that was received by invoking the GetNotificationIds method in the previous step. The GetNotification method returns Notification Object containing the details of the Notification along with the NotificationType . Based on the NotificationType, Notification Object can be type casted into one of the following types

CancelSubscriptionNotificationObject
FreePeriodConversionNotificationObject
SubscriptionRecurrenceNotificationObject
StopSubscriptionNotificationObject
SuccessfulRefundNotificationObject
RestoreSubscriptionNotificationObject

 NotificationObject notificationObject;
 string notificationId = string.Empty;
 string notificationType = string.Empty;
 
 foreach (NotificationId notificationIdObject in notificationIds)
 {
     notificationId = notificationIdObject.Id;
     notificationObject = this.requestFactory.GetNotification(notificationId);
     
     notificationType = notificationObject.NotificationObjectType.ToString();
     if (notificationType.Equals(NotificationType.SubscriptionRecurrence.ToString()))
     {
         SubscriptionRecurrenceNotificationObject subscriptionRecurrenceNotificationObject = (SubscriptionRecurrenceNotificationObject)notificationObject;
     }
     if(notificationType.Equals(NotificationType.CancelSubscription.ToString()))
     {
          CancelSubscriptionNotificationObject cancelSubscriptionNotificationObject = (CancelSubscriptionNotificationObject)notificationObject;
     }
 }

Step 5. Invoke AcknowledgeNotifications

Invoke the AcknowledgeNotifications method using the RequestFactory instance by passing a notification identifier. This method acknowledges the notification and requests that the notification be stopped.

 string notificationId = "xxxxxxxxxxxxx";
 AcknowledgeNotificationResponse response = this.requestFactory.AcknowledgeNotifications(notificationId);