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. This page describes the Web Monetization flow by providing an example set of these API calls.

Reminders

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.

Web Monetization flow

Alice has web monetized her site by adding the monetization <link> element to each page. Included within each <link> is her payment pointer (https://wallet.example/alice), assigned to her by her WM receiver.

Bob has signed up with a WM provider who’s supplied him with a funded sending account. The sending account’s payment pointer is https://anotherwallet.example/bob. After installing a WM agent into 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.

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" />

Send request to site’s payment pointer

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

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"
}

Send incoming payment request to WM receiver

The WM agent creates an incoming payment for the session (e.g., the open browser tab) by issuing an incoming payment request to the WM receiver. 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

Send quote request to WM provider

Up to this point, the WM agent has communicated with Alice’s WM receiver. Now, the WM agent begins communicating with Bob’s WM provider.

The WM agent sends the WM provider a quote that represents how much to send from Bob’s account. In this example, the WM agent creates a quote for $0.02 USD.

Since we’re assuming the WM agent already has a grant to create an outgoing payment on Bob’s account, the grant access token will appear as the Authorization value in the header.

Request

POST /bob/quote HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: {{ quoteGrant.accessToken.value }}
Host: anotherwallet.example

{
  "receiver":"https://wallet.example/alice/incoming-payments/  08394f02-7b7b-45e2-b645-51d04e7c330c",
  "sendAmount":{
    "value":"2",
    "assetCode":"USD",
    "assetScale":2
  }
}

Send outgoing payment request to WM provider

The WM agent uses the details obtained thus far to create an outgoing payment request against Bob’s payment pointer. Note that this is just a request to send a payment. The payment itself has not been sent yet.

Request

POST /bob/outgoing-payment HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: {{ outgoingPaymentGrant.accessToken.value }}
Host: anotherwallet.example
Content-Length: 89

{
  "quoteId":"https://anotherwallet.example/bob/quotes/8c68d3cc-0a0f-4216-98b4-4fa44a6c88cf"
}

The Web Monetization flow is complete. It’s now up to the WM provider to process the payment and settle with the WM receiver.