@ng-web-apis/payment-request
Version:
This is a library for declarative use of Payment Request API with Angular
255 lines (197 loc) • 9.04 kB
Markdown
#  Payment Request API for Angular
[](https://npmjs.com/package/@ng-web-apis/payment-request)
[](https://bundlephobia.com/result?p=@ng-web-apis/payment-request)
[](https://codecov.io/github/taiga-family/ng-web-apis/tree/main/libs/payment-request)
Angular does not have any abstractions over
[Payment Request API](https://developer.mozilla.org/en-US/docs/Web/API/Payment_Request_API). This library provides you
two ways to use this API with Angular of 6+ version.
## Install
If you do not have [@ng-web-apis/common](https://github.com/taiga-family/ng-web-apis/tree/main/libs/common):
```bash
npm i @ng-web-apis/common
```
Now install the package:
```bash
npm i @ng-web-apis/payment-request
```
## How to use
As an Angular service:
```ts
import {WaPaymentRequestService} from '@ng-web-apis/payment-request';
...
constructor(private readonly paymentRequest: WaPaymentRequestService) {}
pay(details: PaymentDetailsInit) {
this.paymentRequest.request(details).then(
response => {
response.complete();
},
error => {},
);
}
```
As a set of directives:
```html
<div
waPayment
[paymentTotal]="total"
>
<div
*ngFor="let item of items"
waPaymentItem
[paymentLabel]="item.label"
[paymentAmount]="item.amount"
>
{{item.label}} ({{item.amount}})
</div>
<button
(waPaymentSubmit)="onPaymentSubmit($event)"
(waPaymentError)="onPaymentError($event)"
>
Buy
</button>
</div>
```
Do not forget to import `WaPaymentRequest`:
```ts
import {WaPaymentRequest} from '@ng-web-apis/payment-request';
...
@Component({
...
imports: [
...
WaPaymentRequest,
]
})
export class YourComponent {}
```
As a good example of usage you can take a look at
[a project live demo on CodeSandbox](https://codesandbox.io/s/github/ng-web-apis/payment-request/tree/master/projects/demo)
#### waPayment
waPayment directive defines a scope for a new payment and needs
[PaymentItem](https://www.w3.org/TR/payment-request/#paymentitem-dictionary) object with information about a label and a
total sum of the payment
How to use:
```html
<any-element
waPayment
[paymentTotal]="total"
>
...
</any-element>
```
It implements
[PaymentDetailsInit](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.paymentdetailsinit.html)
Required inputs:
- `paymentTotal` is a information about a label and a total sum of the payment as
[PaymentItem](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.paymentitem.html)
Additional inputs:
- `paymentId` is an id of the payment as `string`
- `paymentModifiers` is an array of
[PaymentDetailsModifier](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.paymentdetailsmodifier.html)
- `paymentShippingOptions` is a
[WaPaymentShippingOption](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.paymentshippingoption.html)
object for the payment.
#### waPaymentItem
Each item of the payment is a `waPaymentItem` directive. It is a declarative
[PaymentItem](https://www.w3.org/TR/payment-request/#paymentitem-dictionary) for your Payment
How to use:
```html
<any-element
waPayment
[paymentTotal]="total"
>
<any-element
*ngFor="let item of items"
waPaymentItem
[paymentLabel]="item.label"
[paymentAmount]="item.amount"
>
{{item.label}}
</any-element>
</any-element>
```
It implements
[PaymentItem](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.paymentitem.html)
Required inputs:
- `paymentAmount` is a price of payment item in modal as
[PaymentCurrencyAmount](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules_typedoc_node_modules_typescript_lib_lib_dom_d_.paymentcurrencyamount.html)
- `paymentLabel` is a title of payment item in modal as `string`
Additional inputs:
- `paymentPending` is native property for PaymentItem as `boolean`
#### waPaymentSubmit
This directive starts a Payment Request modal in your browser that returns
[PaymentResponse](https://developer.mozilla.org/en-US/docs/Web/API/PaymentResponse) or an error
How to use:
```html
<any-element
waPayment
[paymentTotal]="total"
>
...
<button
(waPaymentSubmit)="onPayment($event)"
(waPaymentError)="onPaymentError($event)"
>
Buy
</button>
</any-element>
```
Outputs:
- `waPaymentSubmit` emits [PaymentResponse](https://developer.mozilla.org/en-US/docs/Web/API/PaymentResponse) object to
handle a payment request result
- `waPaymentError` emits an `Error` or `DOMException` with information about user's problem that did not allow payment
to proceed
## Tokens
The library also provides some tokens to simplify working with Payment Request API:
- `WA_PAYMENT_REQUEST_SUPPORT` returns `true` if user's browser supports Payment Request API
```ts
export class Example {
constructor(@Inject(WA_PAYMENT_REQUEST_SUPPORT) private readonly canRequest: boolean) {}
}
```
- You can provide `WA_PAYMENT_METHODS` as an array of supported API methods. It uses
`[{supportedMethods: 'basic-card'}]` by default
```ts
@Component({
// ...
providers: [
{
provide: [WA_PAYMENT_METHODS],
useValue: [
// a sample with Google Pay from https://developers.google.com/pay/api/web/guides/paymentrequest/tutorial?hl=en
{supportedMethods: 'https://google.com/pay', data: googlePaymentDataRequest},
{supportedMethods: 'basic-card'},
],
},
],
})
export class Example {
// ...
}
```
- You can provide `WA_PAYMENT_OPTIONS` as an object with info that you need about a payer. It uses `{}` by default
```ts
@Component({
// ...
providers: [
{
provide: [WA_PAYMENT_OPTIONS],
useValue: {
shippingType: 'express',
requestPayerName: true,
requestShipping: true,
requestPayerEmail: true,
},
},
],
})
export class Example {
// ...
}
```
## Browser support
| [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/edge/edge_48x48.png" alt="IE / Edge" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/firefox/firefox_48x48.png" alt="Firefox" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/chrome/chrome_48x48.png" alt="Chrome" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) | [<img src="https://raw.githubusercontent.com/alrra/browser-logos/master/src/safari/safari_48x48.png" alt="Safari" width="24px" height="24px" />](http://godban.github.io/browsers-support-badges/) |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
| 12+ | Disabled by default | 61+ | 11.1+ |
## See also
All [@ng-web-apis](https://taiga-family.github.io/ng-web-apis/) for your apps