Webinos Logo

Payment API

Webinos API Specifications

9 Sep 2013

Authors


Abstract

Interface for Payment functions.

Table of Contents

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

Summary of Methods

Interface Method
Payment void pay(PaymentSuccessCB successCallback, PaymentErrorCB errorCallback, PaymentChallengeCB challengeCallback, ShoppingItem[] itemList, ShoppingItem bill, DOMString? customerID, DOMString sellerID)

Introduction

This API provides 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.

It should be noted that the webinos Payment API assumes that the payment process is triggered by the web applications.

Currently, for most current (web based) payment scenarios, the payment process is triggered by the merchant's server, i.e. the user clicks the 'buy' button on the web page, the server redirects to the payment provider's page (so the merchant can be sure that the proper payment provider is contacted and the bill is unmodified), the user performs the transaction and is re-directed to the merchant's server, where the confirmation from the payment provider is sufficient for the merchant to be sure that the payment has taken place.

However, this process can not always be maintained for payment done from within a web application. In these cases (and these are the cases the webinos API is to be used for), the payment is triggered by the application, not the merchant's server. As this adds some security concerns (as any confirmation from the payment provider to the application can be spoofed), it requires the merchant to be able to confirm the payment receipt by some server-to-server vackground channel (between the payment provider and the merchant). This will be either by query from the merchant side (as offered by PayPal) or by automatic sending of a receipt by the payment provider (as offered by Firefox Payment).

Even though application initiated payment is currently rare, the movement from web page based commerce to web application based commerce will increase the use of this mode and the webinos Payment API is aimed to support it.

Interfaces and Dictionaries

Interface Payment

The Payment interface

WebIDL
[NoInterfaceObject] interface Payment : Service{ 

        void pay(PaymentSuccessCB successCallback, PaymentErrorCB errorCallback, PaymentChallengeCB challengeCallback,
        ShoppingItem [] itemList, ShoppingItem bill,  DOMString? customerID, DOMString sellerID);
  };

The Payment interface provides access to payment functionality.

The API supports the payment from the device user to a merchant or other user, utilizing a payment provider.

The payment interface is a discoverable interface through the webinos Discovery API findServices() method and thus inherits the Discovery API Service interface.

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
       // creating item list
       var itemList = new Array();
       itemList[0] = {  productID: 'DCD2346233', 
                       description: 'Best of Ladytron 00-10 by Ladytron (Audio CD - 2011)', 
                       currency: 'EUR',
                       itemPrice: 14.99,
                       itemCount: 1
                     };
       itemList[1] = {  productID: 'DCD1358954167', 
                       description: 'Breakfast at Tiffanys DVD', 
                       currency: 'EUR',
                       itemPrice: 5.97,
                       itemCount: 1
                     };
       itemList[2] = {  description: 'Postage and Packaging', 
                       currency: 'EUR',
                       itemPrice: 5.0,
                       itemCount: 1
                     };
    
       var bill = {  description: 'Bill 123456', 
                       currency: 'EUR',
                       itemPrice: 25.96 
                     };
       // paymentService is the messaging service, discovered through the webinos Discovery API, 
       // that has been selected by the user    
        paymentService.pay(paymentSuccess, paymentFailure, paymentChallenge,
                             itemList, bill,  "mymail@provider.com", "ShopName12345" );
        
        // Define the checkoutSuccess success callback.
        function paymentSuccess() {
                alert("Payment handled successfully - payment was performed.");
        }        

        // Define the paymentFailure failure callback.
        function paymentFailure(e) {   
                alert("Failure occured during payment.");
        }

        // 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

pay

Performs the payment using a payment provider.

Signature
void pay(PaymentSuccessCB successCallback, PaymentErrorCB errorCallback, PaymentChallengeCB challengeCallback, ShoppingItem[] itemList, ShoppingItem bill, DOMString? customerID, DOMString sellerID);

The bill 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: PaymentSuccessCB
    • 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
  • itemList
    • Optional: No.
    • Nullable: No
    • Type: array
    • Description: This is a list of shopping items that have been bought - this is primarily for providing detailed invoisces if the payment provider allows itemized bills. Due to the use of coupons or special combination offers, there is no requirement that the sums of the individual prices is the same as the charged amount for the bill. The item list has only informative purpose and can be left empty or null.
  • bill
    • Optional: No.
    • Nullable: No
    • Type: ShoppingItem
    • Description: This defines the payment to be performed. Mandatory parts of the bill are the amount to be paid, the currency and an ID that allows the merchant to match the payment to the purchase. For the bill, itemCount is required to be 1 and itemsPrice and itemPrice need to be identical. A human readable description should be provided, but isn't mandatory.
  • customerID
    • Optional: No.
    • Nullable: Yes
    • Type: DOMString
    • Description: is identification of the person making the payment as known to the payment provider
  • sellerID
    • Optional: No.
    • Nullable: No
    • Type: DOMString
    • Description: is the identification of the shop the payment is made to
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;

         float 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

float itemsPrice

Price for all products in this shopping item.

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

Dictionary PaymentError

Payment specific errors.

WebIDL
        dictionary PaymentError {


        PaymentErrors code;

        DOMString message;

        boolean retryPossible;
  };

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.

boolean retryPossible

A boolean value describing whether the error is likely to be of a temporary nature (such as a connection failure) which might not be present on a retry a couple of seconds later. As a guideline, for every condition that is not likely to be resolved within one minute, 'retryPossible' should be false.

No exceptions.

Callbacks

PaymentSuccessCB

Callback for errors during payment related functions

WebIDL
        callback PaymentSuccessCB = void (DOMstring proofOfPurchase);
Signature
void PaymentSuccessCB(DOMstring proofOfPurchase);
Parameters
  • proofOfPurchase
    • Optional: No.
    • Nullable: No
    • Type: DOMstring
    • Description: Payment provider specific token to verify purchase.

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 we 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 we 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 { "payment_charge_failed", "payment_chargeable_exceeded", "payment_authentication_failed"};

Values

payment_charge_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:

http://webinos.org/api/payment

Identifies all payment interactions.

Full WebIDL

WebIDL
[NoInterfaceObject] interface Payment : Service{ 

        void pay(PaymentSuccessCB successCallback, PaymentErrorCB errorCallback, PaymentChallengeCB challengeCallback,
        ShoppingItem [] itemList, ShoppingItem bill,  DOMString? customerID, DOMString sellerID);
  };
  

   dictionary ShoppingItem {

         DOMString productID;

         DOMString description;

         DOMString currency;

         float itemPrice;

         unsigned long itemCount;

         float itemsPrice;
    };  

     
                        

        callback PaymentSuccessCB = void (DOMstring proofOfPurchase);
        

        callback PaymentErrorCB = void (PaymentError error);
        


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



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

         enum PaymentErrors { "payment_charge_failed", "payment_chargeable_exceeded", "payment_authentication_failed"};


        dictionary PaymentError {


        PaymentErrors code;

        DOMString message;

        boolean retryPossible;
  };