Documentation

SDK Description

This SDK allows merchants to accept payments on Smart TVs using PW Smart TV Payments product.

Installing the SDK into your app

Add the following line into your application HTML file:

<script type="text/javascript" src="https://api.paymentwall.com/js/pwsmart/ver/pwsmart.1.4.js"></script>

Configuration

Make sure that "Evaluation Mode" is ON in your project's settings:

Initialization constructor takes a JSON object as parameter:

PWSmartGateway.init(details);

details JSON object parameters:

Example:

PWSmartGateway.init({
    key: 'YOUR_PROJECT_KEY',
    countryCode: 'US',
    containerId: 'my-div',
    lang: 'en',
    gaWebPropertyId: 'UA-XXXX-Y',
    brand: 'lgtv'
});

If the library is loaded asynchronously use the callback method below to know when SDK has been fully loaded.

Example:

// Asynchronous initialization
window.PWSmartGatewayOnLoadedCallback = function() {
    PWSmartGateway.init({
        key: 'YOUR_PROJECT_KEY',
        countryCode: 'US',
        containerId: 'my-div',
        lang: 'en',
        gaWebPropertyId: 'UA-XXXX-Y'
        brand: 'lgtv'
    });
};

Display the payment widget

After initializing the SDK, use the method showPaymentForm() below to show the payment widget. If you did not specify a containerId in the step above, the widget will show itself inside the body HTML tag automatically.

PWSmartGateway.showPaymentForm(value, function() { ... }, function() { ... });

value JSON object parameters:

Example:

// 2 months subscription
PWSmartGateway.showPaymentForm(
    {
        productId: 'Order_2044',
        productName: '2 month subscription',
        currency: 'USD', 
        amount: '9.99', 
        period: 'month',
        duration: 2,
        userId: 'test_user_2', 
        onExit: function() {},
        showBackButton: true,
        enablePaymentRecoverFlow: true,
        titles: {'buyHeading': 'Subscribe to #product', 'buyHeadingRecurring': '#price per #period'}
    }, 
    function() {
        alert('Payment Success'); // callback on success
    }, 
    function (error) {
        alert('Payment Failure'); // callback on failure
    }
);

// fixed product (no subscription)
PWSmartGateway.showPaymentForm(
    {
        productId: 'Order_2045',
        productName: '5000 Gold Coins',
        currency: 'USD', 
        amount: '9.99',
        userId: 'test_user_2', 
        onExit: function() {},
        showBackButton: true,
        enablePaymentRecoverFlow: true,
        titles: {'buyHeading': 'Subscribe to #product', 'buyHeadingRecurring': '#price per #period'}
    }, 
    function() {
        alert('Payment Success'); // callback on success
    }, 
    function (error) {
        alert('Payment Failure'); // callback on failure
    }
);

Hide alternative payment methods in the widget

If you want to hide alternative payment methods in the widget you need to pass that parameter: hidePaymentMethods:true

It is also possible to configure products directly in your Project's settings (in your PW Merchant Area) and make a simplified SDK call.

Product configured in project:

Example:

PWSmartGateway.showPaymentForm(
    {
        productId: 'test sku', // SKU ID of the product inside your project's products
    }, 
    function() {
        alert('Payment Success'); // callback on success
    }, 
    function (error) {
        alert('Payment Failure'); // callback on failure
    }
);

Response

Once you make the showPaymentForm() call successfully, the expected result is to see the payment form in screen:

Payment Error

Error messages are displayed automatically on the widget for the end user.

Check payment status

If you would like to first check if the product has already been purchased, you can use checkPaymentStatus() method:

PWSmartGateway.checkPaymentStatus(value, function() { ... }, function() { ... });

JSON object parameters:

If a payment is found using the provided parameters, the success callback receives an array containing JSON objects for each payment found. Please refer here for more details about the response JSON objects. If no payment is found, error callback is triggered.

PWSmartGateway.checkPaymentStatus(
    {
        productId: 'Order_2044', // Product SKU ID
        userId: 'test_user_2'    // ID of the user. By default SDK uses device ID
    },
    function (response) {
        // callback on success
        // refer to https://www.paymentwall.com/en/documentation/Payment-Status-API/3019 for response format
    },
    function (response) { // No payment found, show payment form so customer can purchase
        PWSmartGateway.showPaymentForm(
            {
                productId: 'Order_2044', // Required. Merchant's product SKU ID
                productName: 'Test Key', // Optional. By default pulled by SKU ID from Products section of Merchant Area
                currency: 'USD',         // Optional. By default pulled by SKU ID from Products section of Merchant Area
                amount: '9.99',          // Optional. By default pulled by SKU ID from Products section of Merchant Area
                userId: 'test_user_2'    // Optional. ID of the user. By default SDK uses device ID
            }, 
            function() {
                alert('success'); // callback on success
            }, 
            function (error) {
                alert('failure'); // callback on failure
            }
        );
    }
);

Subscription management

To cancel a user's subscription, you can show the cancellation form to the end-user using the following method:

PWSmartGateway.showCancelSubscriptionForm(value, function() { ... }, function() { ... });

JSON object parameters:

Example:

PWSmartGateway.showCancelSubscriptionForm(
    {
        productId: 'product_sku_id',
        userId: 'test_user_2'
    },
    function (response) {
        // callback on success
    },
    function (response) { 
        // callback on failure
    }
);

Error handling

Third parameter of PWSmartGateway.showPaymentForm is failure callback. It accepts error object of the following format:

{
  type:"error",
  code:1001, 
  message:"Product is not found"
}

Possible error codes:

• 1000 - User cancelled the payment process.
• 1001 - Product is not found. Check the product SKU ID, or provide product name, amount and currency

Pingback Processing

Pingbacks are server-to-server messages that Paymentwall triggers whenever a payment is approved or declined. Implementing pingbacks is required in order to have your project approved. Please refer to Digital Goods API pingbacks to learn about implementation.

Going live

After you finish the integration, you should submit your project for review in your merchant area by clicking the button next to it:

Make sure you finished all steps in the Integration Checklist that pops up when you submit your project for review:

After that, Paymentwall Integration and Compliance team will reach out to you (through Inquiries section in Merchant Area) in order to approve your project and pushing it LIVE.