How payments work

Digital wallets

To receive (and send) payments, you must have an account with a compatible digital wallet. Not all digital wallets support receiving payments with Web Monetization.

A digital wallet is the entity that supplies you with the financial account you’ll use to receive payments. Withdrawing your funds typically requires you to link a card or bank account to your wallet.

Since wallet providers are a type of financial entity, they are regulated within the countries they operate. One type of regulation, known as KYC (Know Your Customer), requires such entities to collect personal information and verify your identity before allowing you to open an account.

Web Monetization-compatible digital wallets

You must have an account with a compatible digital wallet to receive payments. Be sure to select a wallet that:

• Is available in your region
• Supports your preferred currency
• Allows you to withdraw your funds if you choose to transact in fiat

Your wallet provider will assign your account a unique ID called either a payment pointer or a wallet address. This ID is kind of like an account name. It’s a publicly shareable ID that you will need when web monetizing your content.

The format of the ID depends on whether your wallet provider assigned you a payment pointer or a wallet address.

ID name	Example format
Payment pointer	$wallet.example.com/alice
Wallet address	https://wallet.example.com/alice

Web monetized content

Once you have your payment pointer or wallet address, you’re ready to add the Web Monetization <link> element to each page of your site you want to monetize. Visit the quick start guide for more information.

When you include the <link> element on a page, you’re telling your visitors’ browsers that you can accept payments. Visitors who have installed and configured the Web Monetization extension can then choose to send you payments in the amount and frequency of their choosing.

Payments

Your visitors’ Web Monetization extension acts like a messaging service. When they land on your page, their extension identifies your <link> element and sends a message to your payment URL. This begins a number of API requests and responses between the extension and your wallet provider, and the extension and your visitor’s wallet provider to facilitate a payment.

Micropayments

If you’re already somewhat familiar with Web Monetization, you may have heard about how it supports micropayments.

In general, a micropayment is a very small payment. Each wallet provider is responsible for a few things:

• Deciding whether to support sending and/or receiving micropayments
• Defining what a micropayment is in the context of their business

Let’s say your wallet provider allows you to receive micropayments and defines a micropayment as any payment under $0.05 USD. This means that you could receive a single payment of, for example, one US cent. Web Monetization is designed to facilitate payments of even a fraction of a cent; however, you can only receive micropayments if your wallet provider supports them. Your wallet provider may also have business rules set up to allow you to accumulate micropayments, but not deposit the payments into your wallet account until you reach a certain amount.

On the other side of a transaction, your site visitor can only send micropayments if allowed to do so by their own wallet provider.

A deeper dive into payments

Open Payments

For a wallet to be compatible with Web Monetization, the provider must implement the Open Payments standard. When implemented, a set of APIs become available for third-party applications, such as your visitor’s Web Monetization extension, to communicate with the wallet provider.

Web Monetization extension

A component within the extension—called the Web Monetization agent—is responsible for communicating with a wallet provider via the Open Payments APIs. The next section describes the series of API calls required to initiate a payment.

Web Monetization payment sequence

Note

The examples below are simplified representations of the Open Payments API calls and may not show every required parameter.

1. The Web Monetization agent locates your monetization link and extracts your payment URL (the href value). Example monetization link

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

2. The agent issues a GET request to the URL. Example request

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

3. The response to the agent contains information such as the currency your account is denominated in and the URLs for your wallet provider’s authorization and resource servers. Example response

   HTTP/1.1 200 Success
   Content-Type: application/json
   
   {
       "assetCode":"USD",
       "assetScale":2,
       "authServer":"https://wallet.example/auth",
       "resourceServer":"https://wallet.example/resource"
   }

4. The agent issues a POST request to your wallet provider’s authServer URL. The request contains the access permissions the agent is requesting. Example request

   POST /auth/ HTTP/1.1
   Accept: application/json
   Content-Type: application/json
   Host: wallet.example
   
   {
       "access_token":{
           "access":[
               {
                   "type":"incoming-payment",
                   "actions":["create", "read"],
                   "identifier":"https://wallet.example/alice"
               }
           ]
       },
       "client":"https://cloudninewallet.example/visitor"
   }

   Note

   The client in the response above is your visitor’s wallet address/payment pointer. This URL is only used by the agent and is not available to you.

5. The response to the agent contains an auth token that the agent needs to make its next request. Example response

   {
       "access_token":{
       "value":"OS9M2PMHKUR64TB8N6BW7OZB8CDFONP219RP1LT0",
       "manage":"https://wallet.example/auth/token/dd17a202-9982-4ed9-ae31-564947fb6379",
       "access":[
           {
               "type":"incoming-payment",
               "actions":["create", "read"],
               "identifier":"https://wallet.example/alice"
           }
       ]
       }
   }

6. The agent issues a POST request to your wallet provider’s resourceServer URL. The purpose of this call is to request the information needed by your visitor’s wallet provider so their provider correctly addresses the payment to you. Example request

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

7. The response to the agent contains unique payment details that will be used to address the payment to your payment account. Example response

   {
       "id":"https://wallet.example/alice/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c",
       "walletAddress":"https://wallet.example/alice",
           "receivedAmount":{
           "value":"0",
           "assetCode":"USD",
           "assetScale":2
           },
       "completed":false,
       "createdAt":"2022-03-12T23:20:50.52Z",
   }

8. At this point, the agent has finished communicating with your wallet provider. Now, it issues a POST request to your visitor’s wallet provider. The purpose of this call is to give the provider what it needs to send the payment. Example request

   POST /visitor/outgoing-payment HTTP/1.1
   Accept: application/json
   Content-Type: application/json
   Authorization: {{ GNAP outgoingPaymentGrant.accessToken.value }}
   Host: cloudninewallet.example
   
   {
       "walletAddress": "https://wallet.example/alice",
       "quoteId": "https://wallet.example/quotes/ab03296b-0c8b-4776-b94e-7ee27d868d4d",
   }

9. The response to the agent indicates whether the visitor’s wallet provider is able to send the payment. A payment could fail if the visitor has insufficient funds, for example. Assuming everything’s good, the visitor’s wallet provider responds to the agent with payment details. Example response

   {
   "id":"https://cloudninewallet.example/visitor/outgoing-payments/8c68d3cc-0a0f-4216-98b4-4fa44a6c88cf",
   "walletAddress":"https://cloudninewallet.example/visitor/",
   "receiver":"https://wallet.example/alice/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c",
   "receiveAmount":{
       "value":"2",
       "assetCode":"USD",
       "assetScale":2
       },
   "sendAmount":{
       "value":"2",
       "assetCode":"USD",
       "assetScale":2
       },
   "sentAmount":{
       "value":"0",
       "assetCode":"USD",
       "assetScale":2
       },
   "createdAt":"2022-03-12T23:20:55.52Z",
   "updatedAt":"2022-03-12T23:20:55.52Z"
   }

   Note

   Notice that the sentAmount value is 0. All the API calls up to this point have been to set up the payment. This amount will go up over time, depending on the pay rate your visitor has set in their extension.