About receiving payments

Receiving Web Monetization payments requires you to have an account with a compatible digital wallet provider. Not all wallet providers support receiving Web Monetization payments.

Your digital wallet provider will supply 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 financial entities, they are regulated within the countries they operate. One regulation, known as KYC (Know Your Customer), requires financial entities to collect your 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 provider to receive payments. Be sure to select a provider 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 wallet a unique identifier called a wallet address or a payment pointer. You’ll need this identifier to web monetize your content.

Identifier	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 get started page for more information.

When you include the <link> element on a page, you’re telling your website visitors’ browsers that you can accept Web Monetization payments. Visitors using the Web Monetization extension in their browsers 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 uses it to request information from your wallet provider. 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 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 receiving and/or sending micropayments
• Defining what a micropayment is in the context of their business
• Determining the minimum amount for a micropayment

Let’s say your wallet provider allows you to receive micropayments. Your provider defines a micropayment as any payment under $0.05 USD. This means you could, for example, receive a payment of one US cent—as long as the sender’s wallet provider allows them to send that amount.

Your wallet provider may also have business rules set up such that micropayments accumulate on your account but aren’t deposited until you reach a minimum (e.g., $1.00 USD).

Web Monetization can even support payments of a fraction of a cent (e.g., $0.00001); however, sending and receiving fractional amounts must be supported by the respective wallet providers.

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 becomes available for third-party applications, such as your visitor’s Web Monetization extension, to communicate with the wallet providers.

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.

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 from your wallet provider to the agent contains information such as the currency your account is denominated in and the URLs of 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 access 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, the agent issues a POST request to your visitor’s wallet provider. The purpose of this call is to give your visitor’s wallet 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 from your visitor’s wallet provider indicates whether the outgoing payment was created on their side. A payment could fail if the visitor has insufficient funds, for example. The following example indicates the outgoing payment was successfully created.

   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
       },
       "debitAmount": {
           "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"
   }