Webinos Logo

Payment API

Webinos API Specifications

27 Feb 2013

Authors


Abstract

Interface for Payment functions.

Table of Contents

  1. Introduction
  2. Interfaces and Dictionaries
    1. Webinos
    2. Payment
    3. ShoppingBasket
    4. ShoppingItem
    5. PaymentError
  3. Callbacks
    1. SuccessShoppingBasketCallback
    2. PaymentErrorCB
    3. PaymentChallengeCB
  4. Enums
    1. PaymentChallengeType
    2. PaymentErrors
  5. Features
  6. Full WebIDL

Summary of Methods

Interface Method
Webinos
Payment void createShoppingBasket(SuccessShoppingBasketCallback successCallback, PaymentErrorCB errorCallback, DOMString serviceProviderID, DOMString customerID, DOMString shopID)
ShoppingBasket void addItem(VoidFunction successCallback, PaymentErrorCB errorCallback, ShoppingItem item)
void update(VoidFunction successCallback, PaymentErrorCB errorCallback)
void checkout(VoidFunction successCallback, PaymentErrorCB errorCallback, PaymentChallengeCB challengeCallback)
void answerChallenge(DOMstring userResponse)
void release()

Introduction

This API provides generic shopping basket functionality to provide in-app payment.

It is not linked to a specific payment service provider and is designed to be sufficiently generic to be mapable to various payment services like GSMA OneAPI, BlueVia, Android Payment API or PayPal.

Interfaces and Dictionaries

Interface Webinos (partial interface)

Creates the webinos.payment namespace.

WebIDL
partial interface Webinos {

      readonly attribute Payment payment;
   };

Attributes

readonly Payment payment

webinos.payment object.

This attribute is readonly.

Interface Payment

The Payment interface

WebIDL
[NoInterfaceObject] interface Payment { 

        void createShoppingBasket(SuccessShoppingBasketCallback successCallback, PaymentErrorCB errorCallback,
        DOMString serviceProviderID, DOMString customerID, DOMString shopID);
  };

The Payment interface provides access to payment functionality.

The API supports creation of a shopping basket, adding items to the shopping basket, proceeding to checkout and releasing the shopping basket.

This essentially echoes the usual 'shopping basket' system used on many web sites.

The code example below refunds the user for a returned CD and charges for the deluxe edition of that CD, demonstarting charging and refunding payments.

Code example
    
        webinons.payment.createShoppingBasket(openBasketSuccess, paymentFailure, "PayPal", "mymail@provider.com", "ShopName12345");
        var myBasket = null;

        // Define the openBasketSuccess success callback.
        function openBasketSuccess(basket) {
                alert("Shopping basket was opened successfully");
                myBasket = basket;  
                // refound for a CD
                myBasket.addItem(CD2346278, paymentFailure,
                    {  productID: 'DCD2346233', 
                       description: 'Best of Ladytron 00-10 by Ladytron (Audio CD - 2011)', 
                       currency: 'EUR',
                       itemPrice: -14.99,
                       itemCount: 1}
        }

        // Define the refundItemSuccess success callback.
        function refundSuccess() {
                alert("Adding of refunding item was handled successfully");
                // charge for the deluxe CD
                myBasket.addItem(addItemSuccess, paymentFailure,
                    {  productID: 'DCD2346233', 
                       description: 'Best of Ladytron 00-10 (Deluxe Edition) by Ladytron (Audio CD - 2011)', 
                       currency: 'EUR',
                       itemPrice: 17.98,
                       itemCount: 1}
        }

        // Define the addItemSuccess success callback.
        function addItemSuccess() {
                alert("Adding of new item was handled successfully");
                // now close the bill and perform the actual payment
                myBasket.update(updateSuccess, paymentFailure);
        }
        
        // Define the updateSuccess success callback.
        function updateSuccess() {
                alert("Total amount is: "myBasket.totalAmount+" Tax is "+myBasket.tax);
                // now close the bill and perform the actual payment
                myBasket.checkout(checkoutSuccess, paymentFailure, paymentChallenge);
        }
        
        // Define the checkoutSuccess success callback.
        function checkoutSuccess() {
                alert("Checkout handled successfully - payment was performed.");
                 if (myBasket != null) myBasket.release();
        }        

        // Define the paymentFailure failure callback.
        function paymentFailure(e) {   
                alert("Failure occured during payment.");
                 if (myBasket != null) myBasket.release();
        }

        // Define the paymentChallenge callback.
        function paymentChallenge(cType, cValue) {   
                 
         if(cType=="url"){
           // direct web page of payment provider
           window.open(cValue, "Confirm Payment", "width=300,height=200,scrollbars=yes");
         }
         else if(cType=="text"){
             userInput = prompt(cValue, "");
             answerChallenge(userInput);
         }
         else if(cType=="image"){
             // this would need a custom prompt, which would make this example
             // too large - just pretent it's here.
             userInput = graphicPrompt(cValue, "");
             answerChallenge(userInput);
         }
         else alert("Unknown challenge type "+cType+" issued by payment provider.");  *
        }
         

 

Methods

createShoppingBasket

Creates a shopping basket

Signature
void createShoppingBasket(SuccessShoppingBasketCallback successCallback, PaymentErrorCB errorCallback, DOMString serviceProviderID, DOMString customerID, DOMString shopID);
Parameters
  • successCallback
  • errorCallback
    • Optional: No.
    • Nullable: No
    • Type: PaymentErrorCB
    • Description: Callback issued if an error occurs during the creation of the shopping basket
  • serviceProviderID
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: is the name of the payment provider to be used
  • customerID
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: is identification of the person making the payment as known to the payment provider
  • shopID
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: is the identification of the shop the payment is made to
Return value
void

Interface ShoppingBasket

The ShoppingBasket interface provides access to a shopping basket

WebIDL
[NoInterfaceObject] interface ShoppingBasket {   

        readonly attribute ShoppingItem[] items; 

        readonly attribute ShoppingItem[] extras; 

        readonly attribute float totalBill; 
        

        void addItem(VoidFunction successCallback, PaymentErrorCB errorCallback, ShoppingItem item);


        void update(VoidFunction successCallback, PaymentErrorCB errorCallback);


        void checkout(VoidFunction successCallback, PaymentErrorCB errorCallback, PaymentChallengeCB challengeCallback);


        void answerChallenge(DOMstring userResponse);



        void release();
  };

The shopping basket represents a current payment action and allows to add a number of items to the basket before proceeding to checkout.

Attributes

readonly ShoppingItem[] items

List of items currently in the shopping basket. These are the items that have been added with addItem.

This attribute is readonly.
readonly ShoppingItem[] extras

Automatically generated extra items, typically rebates, taxes and shipping costs.

These items are automatically added to the shopping basket by update() (or after the addition of an item to the basket).

These items can contain such 'virtual' items as payback schemes, rebates, taxes, shipping costs and other items that are calculated on the basis of the regular items added.

This attribute is readonly.
readonly float totalBill

The total amount that will be charged to the user on checkout.

Will be updated by update(), may be updated by addItem().

This attribute is readonly.

Methods

addItem

Adds an item to a shopping basket.

Signature
void addItem(VoidFunction successCallback, PaymentErrorCB errorCallback, ShoppingItem item);
Parameters
  • successCallback
    • Optional: No.
    • Nullable: No
    • Type: VoidFunction
    • Description: Callback issued when successfully added the item to the shopping basket
  • errorCallback
    • Optional: No.
    • Nullable: No
    • Type: PaymentErrorCB
    • Description: Callback issued if an error occurs during adding the item
  • item
    • Optional: No.
    • Nullable: No
    • Type: ShoppingItem
    • Description: the item to purchase
Return value
void
update

Updates the shopping basket

Signature
void update(VoidFunction successCallback, PaymentErrorCB errorCallback);

The update function updates the values in the shopping baskets, based on the added items. Such updates may include taxes, calculating the total amount, shipping costs or rebate calculations.

While this, preferably, is internally updated after the adding of each item, such an update might require communication with the payment service provider and it might be undesireable in specific implementations to perform such a query after each individual item, so a specifc update function is provided to force such an update.

The checkout function will always perform an update internally before payment.

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No
    • Type: VoidFunction
    • Description: Callback issued when the update is performed
  • errorCallback
    • Optional: No.
    • Nullable: No
    • Type: PaymentErrorCB
    • Description: Callback issued if an error occurs during update
Return value
void
checkout

Performs the checkout of the shopping basket.

Signature
void checkout(VoidFunction successCallback, PaymentErrorCB errorCallback, PaymentChallengeCB challengeCallback);

The items in the shopping basket will be charged to the shopper.

Depending on the implementation of the actual payment service, this function might cause the checkout screen of the payment service provider to be displayed.

Parameters
  • successCallback
    • Optional: No.
    • Nullable: No
    • Type: VoidFunction
    • Description: Callback issued when the checkout is performed and payment is made
  • errorCallback
    • Optional: No.
    • Nullable: No
    • Type: PaymentErrorCB
    • Description: Callback issued if an error occurs during adding the amount
  • challengeCallback
    • Optional: No.
    • Nullable: No
    • Type: PaymentChallengeCB
    • Description: Callback that will be used if the payment provider requires additional confirmation to finalize payment
Return value
void
answerChallenge

Provide the user response to a challenge to the payment provider

Signature
void answerChallenge(DOMstring userResponse);

If a payment provider presents an image or a text challenge to the user, the client needs to present them and gather a text response from the user, which is returned to the payment provider via the userResponse function.

Parameters
  • userResponse
    • Optional: No.
    • Nullable: No
    • Type: DOMstring
    • Description: Information that the user issued in response to the challenge (on image and text challenges)
Return value
void
release

Releases a shopping basket.

Signature
void release();

The current shopping basket will be released.

If no checkout has been performed, the initiated shopping transaction will be cancelled.

Return value
void

Dictionary ShoppingItem

The ShoppingItem captures the attributes of a single shopping product

WebIDL
   dictionary ShoppingItem {

         DOMString productID;

         DOMString description;

         DOMString currency;

         float itemPrice;

         unsigned long itemCount;

         unsigned long itemsPrice;
    };

The shopping basket represents a current payment action and allows to add a number of items to the basket before proceeding to checkout.

Dictionary Members

DOMString productID

An id that allows the shop to identify the purchased item

DOMString description

A human-readable text to appear on the bill, so the user can easily see what they bought.

DOMString currency

The 3-figure code as per ISO 4217.

float itemPrice

The price per individual item in the currency given above, a negative number represents a refund.

unsigned long itemCount

The number of identical items purchased

unsigned long itemsPrice

Price for all products in this shopping item.

Typically this is itemPrice*itemCount, but special '3 for 2' rebates might apply.

Updated by the shopping basket update function.

Dictionary PaymentError

Payment specific errors.

WebIDL
        dictionary PaymentError {


        PaymentErrors code;

        DOMString message;
  };

The PaymentError dictionary encapsulates all errors in the manipulation of payments objects in the Payment API.

Dictionary Members

PaymentErrors code

An error code assigned by an implementation when an error has occurred in Payment processing.

No exceptions.

DOMString message

A text describing an error occuring in the Payment in human readable form.

No exceptions.

Callbacks

SuccessShoppingBasketCallback

Callback for successful creation of a shopping basket

WebIDL
        callback SuccessShoppingBasketCallback = void (ShoppingBasket basket);
Signature
void SuccessShoppingBasketCallback(ShoppingBasket basket);
Parameters
  • basket
    • Optional: No.
    • Nullable: No
    • Type: ShoppingBasket
    • Description: The shopping basket to which items can be added.

PaymentErrorCB

Callback for errors during payment related functions

WebIDL
        callback PaymentErrorCB = void (PaymentError error);
Signature
void PaymentErrorCB(PaymentError error);
Parameters
  • error
    • Optional: No.
    • Nullable: No
    • Type: PaymentError
    • Description: The Payment API related error object of an unsuccessful asynchronous operation.

PaymentChallengeCB

Callback for additional confirmation / identification challenges by the payment provider

WebIDL
        callback PaymentChallengeCB = void (PaymentChallengeType challengeType, DOMString challenge);

In many payment scenarios, the payment provider will require additional information and confirmation by the user to ensure that the payment is done with user consent and that the user is not impersonated by an application. To facilitate this, the payment provider can issue a challenge, which will be presented to the user and needs to be responded to by the user. It is the task of the payment provider to ensure that challenges are changing and a capture/replay attack will not be successful.

Depening on the needs of the transaction, this can also be used to ensure that the payment is confirmed by a person (for example by using captcha-style images) and also to confirm to users that they are indeed connected to the proper payment provider (for example by presenting an image, only known to the user and the payment provider overlaid with information about the current payment process).

Challenges can take three forms: Text challenges - such as "Enter the PIN from the SMS er just sent you." Image challenges - captcha-style images or any image containing a textual question URL - many payment providers require a re-direct to their own web page for additional identification and confirmation. On receiving an URL, the client is required to open a frame with this URL so the user can comunicate and provide credentials directly to the payment provider.

Signature
void PaymentChallengeCB(PaymentChallengeType challengeType, DOMString challenge);

In many payment scenarios, the payment provider will require additional information and confirmation by the user to ensure that the payment is done with user consent and that the user is not impersonated by an application. To facilitate this, the payment provider can issue a challenge, which will be presented to the user and needs to be responded to by the user. It is the task of the payment provider to ensure that challenges are changing and a capture/replay attack will not be successful.

Depening on the needs of the transaction, this can also be used to ensure that the payment is confirmed by a person (for example by using captcha-style images) and also to confirm to users that they are indeed connected to the proper payment provider (for example by presenting an image, only known to the user and the payment provider overlaid with information about the current payment process).

Challenges can take three forms: Text challenges - such as "Enter the PIN from the SMS er just sent you." Image challenges - captcha-style images or any image containing a textual question URL - many payment providers require a re-direct to their own web page for additional identification and confirmation. On receiving an URL, the client is required to open a frame with this URL so the user can comunicate and provide credentials directly to the payment provider.

Parameters
  • challengeType
    • Optional: No.
    • Nullable: No
    • Type: PaymentChallengeType
    • Description: Defines the challenge type issued by the payment provider.
  • challenge
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: Defines the challenge to be presented to the user

Enums

PaymentChallengeType

Types of payment challenges

WebIDL
          enum PaymentChallengeType {"text", "image", "url"};

Values

text
image
url

PaymentErrors

Types of error messages specific to payment functionality

WebIDL
         enum PaymentErrors {"basket_already_open", "basket_not_open", "payment_charge_failed", "payment_refund_not_supported", "payment_refund_failed", "payment_chargeable_exceeded", "payment_authentication_failed"};

Values

basket_already_open
basket_not_open
payment_charge_failed
payment_refund_not_supported
payment_refund_failed
payment_chargeable_exceeded
payment_authentication_failed

Features

This section lists the URIs used to declare the features of this API. The feature URIs are used by the developer in:

Note that for use as serviceType in discovery the feature strings can optionally be extended with query parameters that further refines the search operation. See the webinos Discovery API for more information.

http://webinos.org/api/payment

Identifies all payment interactions.

http://webinos.org/api/payment/checkout

Identifies access to the checkout function, enabling a separate policy (ask user consent) for the checkout itself.

Full WebIDL

WebIDL
partial interface Webinos {

      readonly attribute Payment payment;
   };





 
[NoInterfaceObject] interface Payment { 

        void createShoppingBasket(SuccessShoppingBasketCallback successCallback, PaymentErrorCB errorCallback,
        DOMString serviceProviderID, DOMString customerID, DOMString shopID);
  };
  

   
[NoInterfaceObject] interface ShoppingBasket {   

        readonly attribute ShoppingItem[] items; 

        readonly attribute ShoppingItem[] extras; 

        readonly attribute float totalBill; 
        

        void addItem(VoidFunction successCallback, PaymentErrorCB errorCallback, ShoppingItem item);


        void update(VoidFunction successCallback, PaymentErrorCB errorCallback);


        void checkout(VoidFunction successCallback, PaymentErrorCB errorCallback, PaymentChallengeCB challengeCallback);


        void answerChallenge(DOMstring userResponse);



        void release();
  };


   dictionary ShoppingItem {

         DOMString productID;

         DOMString description;

         DOMString currency;

         float itemPrice;

         unsigned long itemCount;

         unsigned long itemsPrice;
    };  


        callback SuccessShoppingBasketCallback = void (ShoppingBasket basket);
                        

        callback PaymentErrorCB = void (PaymentError error);
        


        callback PaymentChallengeCB = void (PaymentChallengeType challengeType, DOMString challenge);
        




          enum PaymentChallengeType {"text", "image", "url"};
          

         enum PaymentErrors {"basket_already_open", "basket_not_open", "payment_charge_failed", "payment_refund_not_supported", "payment_refund_failed", "payment_chargeable_exceeded", "payment_authentication_failed"};


        dictionary PaymentError {


        PaymentErrors code;

        DOMString message;
  };