Payment Handler API
Lets a payment app run inside the browser as a payment option.
In one line
Can offer its own pay option in the browser's payment sheet, once you install it
Lets a payment app run inside the browser as a payment option.
Lets a wallet website register as a payment method; the site sees only the payment response.
What it can and can't do
What the user does: You pick that payment app in the browser's payment sheet, after it was added.
It can
- Show up as a payment choice in the browser pay sheet
- Open its own window to take payment details
- Send the store an approval after you pay
It cannot
- Appear without being installed first
- Take money without you picking it
- Work in Firefox or Safari, including on iPhone
- See other payment apps you use
How it differs between platforms: Chrome and Edge support it. Firefox and Safari do not.
Browser support
| Browser | Status | First version | Released | Note |
|---|---|---|---|---|
| Chrome | Supported | 70 | 2018-10-16 | None |
| Edge | Supported | 79 | 2020-01-15 | None |
| Firefox | Not supported | Not available | Not listed | None |
| Safari | Not supported | Not available | Not listed | None |
| Safari on iPhone | Not supported | Not available | Not listed | None |
| Chrome on Android | Supported | 70 | 2018-10-17 | None |
| Samsung Internet | Supported | 10.0 | 2019-08-22 | None |
How a site asks for it
| API | ServiceWorkerRegistration.paymentManager, 'paymentrequest' event, enableDelegations() |
| Browser compat keys | api.PaymentManager |
| How access is granted | install |
| What the user sees | Payment sheet lists the registered handler after install |
| Needs a secure context (HTTPS) | Yes |
| Needs a user gesture | No |
| How long it lasts | Per origin |
| How to take it back | Site settings |
| Inside an iframe | Same as top level; cross-origin iframes need a permissions policy where listed |
Typical flow
- Call the API
- Browser applies its access rules
- Page receives the result
Data you get
What comes back: Lets a payment app run inside the browser as a payment option.
Shape: object
How often: on demand
| Field | Type | Unit | Range | Precision |
|---|---|---|---|---|
methodName | string | None | URL based identifier | Not listed |
details | object | None | handler defined | Not listed |
Technical limits
- Chrome and Edge only
- Handler must be a service worker with HTTPS
The story
What it is
A payment app can run inside the browser as a way to pay.
For you
At checkout the browser pay sheet may list a payment app you installed from a website, like a bank or wallet app.
For makers
Banks and wallets can offer their payment method without a native app. Merchants just ask for the payment method and the browser connects them.
Where you see it
| Type | Example | Apps |
|---|---|---|
| banking | A bank registers its own payment app so customers pay with it at any merchant. | None named |
| payments | A digital wallet offers its balance as a payment choice. | Samsung Pay, PayPal |
| shopping | A shop accepts any installed payment app without special integrations. | None named |
| games | A web game sells in game currency using a wallet balance. | None named |
| travel | A booking site lets you pay with a loyalty points wallet. | None named |
| security | A bank checks you in its own app before approving, so card theft is harder. | None named |
Risks
- Fake payment apps
- Few browsers support it
What the platform says
- Google: Web based payment apps. web.dev explains that Payment Handler lets a web based payment app show up in the browser pay sheet.
Good uses and abuse
Legitimate uses
- Wallet and bank handlers
Known abuse
- Fake handlers for phishing
Scores
| Score | Value | Meaning |
|---|---|---|
| Sensitivity | 3 of 5 | How revealing the data is |
| Utility | 2 of 5 | How useful it is to honest apps |
| Friction | 1 of 5 | How much the user has to do |
| Fingerprint bits | Not rated | Rough identifying entropy, when known |
History
- 2018, Chrome 70: Payment Handler ships
- 2020, Chrome 80: enableDelegations
Sources
How well checked: Checked against real behavior.