Skip to content

Web Monetization flow

Web Monetization (WM) relies on Open Payments (OP) and OP-enabled accounts to coordinate payments.

The WM agent first issues a series of API calls to the receiving account’s payment pointer, then to the sending account’s payment pointer, to obtain the necessary authorization and instructions for sending a payment.

Sequence diagram

View full image

Web Monetization flow example

This section provides an example of the API calls that occur when a web monetized user visits a web monetized site.

There’s a few points to keep in mind as you review the example.

  • It’s up to the site visitor, not the web monetized site, to decide how often and how much to pay, as well as the currency in which to send a payment.
  • While Web Monetization and Open Payments work together to coordinate payments, neither moves money. Payment processing and settlement must occur between the sending and receiving accounts over a common payment rail.

Scenario

Alice adds the monetization <link> element to her website. Included within the <link> is her payment pointer, https://wallet.example/alice, assigned to her by her WM receiver.

Bob signs up with a WM provider who supplies him with a funded sending account. The sending account’s payment pointer is https://anotherwallet.example/bob. After installing a WM agent in his browser and linking the WM agent to his WM provider, his WM agent now has permission to request payments be sent from his account.

1 - Check for Web Monetization

As Bob browses Alice’s site, his WM agent detects a monetization <link> element.

<link rel="monetization" href="https://wallet.example/alice" />

2 - Send request to payment pointer (receiving account)

The WM agent issues a request to Alice’s payment pointer to discover the Open Payments service endpoint.

Request

GET /alice HTTP/1.1
Accept: application/json
Host: wallet.example

3 - Send grant request to WM receiver’s auth server

The WM agent issues a request to the WM receiver’s grant request endpoint (authorization server) to get an access token.

In this example, the WM agent requests access to create and read incoming payments (i.e., payments coming in to Alice’s WM receiver).

Request

POST /auth/ HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: wallet.example
Content-Length: 218

{
  "access_token":{
    "access":[
      {
        "type":"incoming-payment",
        "actions":[
          "create",
          "read"
        ],
        "identifier":"https://wallet.example/alice"
      }
    ]
  },
  "interact":{
    "finish":{
    "method":"redirect"
  }
},
"client":"https://anotherwallet.example/bob"
}

4 - Send incoming payment request to payment pointer (receiving account)

The WM agent creates an incoming payment for the session (e.g., the open browser tab) by issuing an incoming payment request to Alice’s payment pointer. The request uses details obtained from the previous API calls.

Request

POST /alice/incoming-payments HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0
Host: wallet.example

5 - Send outgoing payment request to payment pointer (sending account)

The WM agent uses the details obtained thus far to create an outgoing payment request against Bob’s account (via his payment pointer). Note that this is just a request to send a payment. The payment itself has not been sent and the request is in a pending state.

Request

POST /bob/outgoing-payment HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: {{ outgoingPaymentGrant.accessToken.value }}
Host: anotherwallet.example
 
sequenceDiagram
autonumber
    box aliceblue WM provider
    participant OPS as Open Payments<br/>sending account
    end
    participant WMA as WM agent
    participant page as Web page
    box aliceblue WM receiver
    participant OPR as Open Payments<br/>receiving account
    participant AS as Auth server
    end
note over AS,OPR: The auth server can be<br/>located outside of the <br/>WM receiver's domain
WMA->>page: Detects monetization <link> element,<br/>extracts payment pointer
WMA->>OPR: Requests the payment pointer's public info
OPR->>WMA: Returns info, including auth server URL
WMA->>AS: Requests access rights
AS->>WMA: Returns access token
WMA->>OPR: Requests creation of an incoming payment resource
OPR->>WMA: Responds with unique payment details for addressing the payment to the account
WMA->>+OPS: Requests an outgoing payment be<br/>created against the sending account
note left of OPS: Connection persists until<br/>request moves from 'pending'<br/>state to 'sending' state
OPS->>-WMA: Responds with details about the<br/>'receive', 'send', and 'sent' amounts
WMA->>WMA: Fires monetization event
note over OPS,OPR: Payment processing and settlement occurs between the WM provider and WM receiver, outside of the WM flow