© 2011-2012 webinos consortium.
Interface for Payment functions.
| 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() |
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.
Creates the webinos.payment namespace.
partial interface Webinos {
readonly attribute Payment payment;
};
readonly
Payment paymentwebinos.payment object.
The Payment interface
[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.
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."); *
}
createShoppingBasketCreates a shopping basket
void createShoppingBasket(SuccessShoppingBasketCallback successCallback, PaymentErrorCB errorCallback, DOMString serviceProviderID, DOMString customerID, DOMString shopID);
The ShoppingBasket interface provides access to a shopping basket
[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.
readonly
ShoppingItem[] itemsList of items currently in the shopping basket. These are the items that have been added with addItem.
readonly
ShoppingItem[] extrasAutomatically 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.
readonly
float totalBillThe total amount that will be charged to the user on checkout.
Will be updated by update(), may be updated by addItem().
addItemAdds an item to a shopping basket.
void addItem(VoidFunction successCallback, PaymentErrorCB errorCallback, ShoppingItem item);
updateUpdates the shopping basket
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.
checkoutPerforms the checkout of the shopping basket.
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.
answerChallengeProvide the user response to a challenge to the payment provider
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.
releaseReleases a shopping basket.
void release();
The current shopping basket will be released.
If no checkout has been performed, the initiated shopping transaction will be cancelled.
The ShoppingItem captures the attributes of a single shopping product
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.
DOMString productIDAn id that allows the shop to identify the purchased item
DOMString descriptionA human-readable text to appear on the bill, so the user can easily see what they bought.
DOMString currencyThe 3-figure code as per ISO 4217.
float itemPriceThe price per individual item in the currency given above, a negative number represents a refund.
unsigned long itemCountThe number of identical items purchased
unsigned long itemsPricePrice 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.
Payment specific errors.
dictionary PaymentError {
PaymentErrors code;
DOMString message;
};
The PaymentError dictionary encapsulates all errors in the manipulation of payments objects in the Payment API.
PaymentErrors codeAn error code assigned by an implementation when an error has occurred in Payment processing.
No exceptions.
DOMString messageA text describing an error occuring in the Payment in human readable form.
No exceptions.
SuccessShoppingBasketCallbackCallback for successful creation of a shopping basket
callback SuccessShoppingBasketCallback = void (ShoppingBasket basket);
void SuccessShoppingBasketCallback(ShoppingBasket basket);
PaymentErrorCBCallback for errors during payment related functions
callback PaymentErrorCB = void (PaymentError error);
void PaymentErrorCB(PaymentError error);
PaymentChallengeCBCallback for additional confirmation / identification challenges by the payment provider
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.
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.
PaymentChallengeTypeTypes of payment challenges
enum PaymentChallengeType {"text", "image", "url"};
textimageurlPaymentErrorsTypes of error messages specific to payment functionality
enum PaymentErrors {"basket_already_open", "basket_not_open", "payment_charge_failed", "payment_refund_not_supported", "payment_refund_failed", "payment_chargeable_exceeded", "payment_authentication_failed"};
basket_already_openbasket_not_openpayment_charge_failedpayment_refund_not_supportedpayment_refund_failedpayment_chargeable_exceededpayment_authentication_failedThis 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.
Identifies all payment interactions.
Identifies access to the checkout function, enabling a separate policy (ask user consent) for the checkout itself.
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;
};