15 KiB
Web Payment APIs
- nemo (RFCs We Love, May 2020)
whoami
- Nemo me@captnemo.in
- Tech/Security @ Razorpay
webpayments
The goal is to create a safe, decentralized system and a set of open, patent and royalty-free specifications that allow people on the Web to send each other money as easily as they exchange instant messages and e-mail today.
W3C
- ActivityPub
- CGI
- CSS
- DOM
- HTML
- RDF
- SOAP
- SVG
- XHTML
- XML
- XPath
demo
Before we start, let's do a quick demo of how it all comes together.
why?
- Make it easier to accept payments world-wide.
- Can we have "Payment negotiation", ala content-negotiation?
- Can we have privacy-preserving payment methods?
- Every webshop has its own checkout/cart implementation - can we standardize this?
specifications*
See github.com/w3c/webpayments/wiki for a complete list
* working drafts
specifications*
- Payment Request API: how to initiate a payment
- Payment Method Identifiers: what is a payment method?
- Payment Method Manifest: definition of a payment method
- Payment Handler API: how a payment method is processed?
Agenda
Try to understand how we can complete a payment entirely from within your browser without relying on any proprietary APIs (as a processor/merchant), and yet being compatible with any payment instrument.
Definitions
The payment method: the means that the payer uses to pay the payee (e.g., a basic card payment). They are uniquely identified via a Payment Method Identifier (PMI)
The payment method provider establishes the ecosystem to support that payment method.
The details of how to fulfill a payment request for a given payment method is an implementation detail of a payment handler, which is a Web application that can handle a request for payment on behalf of the user.
Examples
payment method: Paytm Wallet Account, UPI, Card, Gift Card, Voucher Code, Bitcoin.
Payment Method Identifier: https://paytm.com
, https://npci.org.in/upi
, basic-card
payment method provider: Razorpay
, Stripe
, PayPal
, NPCI/UPI
, your-bank-goes-here
ecosytem overview
Flow
Payment Method Identifier
- URL-based payment method identifier (say,
https://bitcoincore.org/
orhttps://pay.wechat.com
). - or a standardized payment method identifier (currently only
basic-card
is on the registry).
humanized: how to identify and categorize various payment methods?
Payment Method Manifest
allows the curators of a defined payment method or owners of a proprietary payment method to authorize (via a manifest file) which payment handlers may be used to fulfill the payment method.
humanized: defines the "how-to-process" action of a specific payment method. The one for basic-card
is standardized in a specification already.
How to get to the manifest?
GET / HTTP/2
Host: alicepay.com
HTTP/2 204
Link: </pay/payment-manifest.json>; rel="payment-method-manifest"
You can alternatively just redirect from your PMI URL, or serve the JSON directly on the PMI URL
What's inside a Manifest?
A payment method manifest tells the user-agent "how to process payments for a particular method".
URL: https://alicepay.com/pay/payment-manifest.json
{
"default_applications": ["app/webappmanifest.json"],
"supported_origins": [
"https://bobpay.xyz",
"https://alicepay.friendsofalice.example"
]
}
Google Pay's Payment Method Manifest
curl -A "AppleWebKit/1 Chromium/1 Chrome/1" https://pay.google.com/gp/p/payment_method_manifest.json
{
"default_applications": ["https://pay.google.com/gp/p/web_manifest.json"],
"supported_origins": ["https://pay.google.com"]
}
what happens?
user-agent
can go next to https://alicepay.com/pay/app/webappmanifest.json
to install the AlicePay application.
supported_origins
defines which origins can be trusted to install an application for this payment method.
What's inside a Manifest (1)
{
//...
"supported_origins": [
"https://beta.alicepay.com",
"https://bobpay.com"
]
}
A payment application hosted at either alicepay.com
, beta.alicepay.com
, or bobpay.com
is now authorized for the payment method https://alicepay.com
.
What's inside a Manifest (2)
{
//...
"supported_origins": "*"
}
any third party is allowed to support the payment method.
Google Pay's Web Manifest
Not part of the webpayments spec
URL: https://pay.google.com/gp/p/web_manifest.json
{
"short_name": "Google Pay",
"name": "Google Pay",
"icons": [{
"src": "https://www.gstatic.com/instantbuy/icons/gpay_24.png",
"sizes": "24x24"
},{
"src": "https://www.gstatic.com/instantbuy/icons/gpay_32.png",
"sizes": "32x32"
}],
"serviceworker": {
"src": "/gp/p/service_worker.js",
"use_cache": true
}
}
recap
So far, the user-agent has done the following:
- seen a
payment-method
(we haven't gotten to how) - discovered the payment method manifest URL
- parsed the payment method manifest to determine the webapp manifest URL
- fetched the webapp manifest URL
- installed the payment method's application(s)
The application installation is based on W3C's Web App Manifest specification.
What's inside the Payment Handler?
A PaymentManager is an additional attribute to the ServiceWorker
specification, which allows a piece of code to run/listen in background in your browser, even after the tab is closed.
PaymentManager {
instruments = PaymentInstruments {
delete(instrumentKey)
get(instrumentKey)
keys()
has(instrumentKey);
set(instrumentKey, PaymentInstrument details);
clear();
}
userHint
}
Payment Instrument
Defines what all different instruments a user might have registered against this method (Multiple wallets, bank accounts, cards etc).
PaymentInstrument {
// Visa Card ending in **1214
name;
// Visa icon
icons;
// PMI
method;
// Can be used to restrict card usage by network for eg.
capabilities;
}
PaymentHandler API
A payment handler listens on the PaymentRequestEvent
, and returns a PaymentHandlerResponse
once done.
PaymentHandlerResponse {
methodName // PMI
details {}
payerName;
payerEmail;
payerPhone;
shippingAddress;
shippingOption;
}
Payment Handler
Each payment handler defines:
- Steps to check if a payment can be made (listen to
CanMakePaymentEvent
) - Steps to respond to a payment request: (
PaymentRequestEvent
)
The structure of this object is specific to each payment method.
- Steps for when a user changes payment method (optional) (
PaymentRequestDetailsUpdate
)
Steps that describe how to handle the user changing payment method or monetary instrument (e.g., from a debit card to a credit card)
Payment Request API
PaymentRequest interface
id
show()
abort()
canMakePayment()
hasEnrolledInstrument()
shippingAddress
shippingType
onmerchantvalidation
onshippingaddresschange
shippingOption
onshippingoptionchange
onpaymentmethodchange
Native Applications?
You can declare support for native applications via a few non-standardized changes to the payment method manifest:
{
"related_applications": [{
"platform": "play",
"id": "com.bobpay.app",
"min_version": "1",
"fingerprints": [{
"type": "sha256_cert",
"value": "92:5A:39:05:C5:B9:EA:BC:71:48:5F:F2"
}],
"url": "https://play.google.com/store/apps/details?id=com.bobpay.app"
}]
}
Native applications (2)
Instead of using service-workers now, your payment application can rely on platform-specific APIs for the same purpose. Android uses Intents, for eg.
In the Wild
- Google Pay is already using Payments API to support cross-platform Payments, by declaring a new "https://google.com/pay" payment method.
- Apple Pay runs in browsers using the Payment Request API.
- So does Samsung Pay
- Payment processors are adding support for it: Stripe, BrainTree, Worldline
- Facebook implements it within their in-app browser for the Mobile SDK.
The "Payment Handler" for most of the above implementations is a close browser<>payment app coupling, with an application such as Samsung/Apple/Google Pay.
Current Status
- All major browser implement Payment Request API to various degrees, primarily for the
basic-card
usecase. - Payment Handler registration is only supported in Chrome.
Future Scope
- Installing a payment app is clunky, maybe we can just install the service-worker directly.
- Lots of work happening towards standardization of non-card payments (such as SEPA, Tokenized Cards, credit-transfer).
- Getting the drafts published as a W3C recommendation
Questions?
- Tweet to me @captn3m0
- Emails: me@captnemo.in