Skip to content

Pago Payment Processor

Keith Irwin requested to merge ki9/ccs-proposals:master into master

Pago Payment Processor

pago (Esperanto for "payment") will be a monero payment platform with flexible html/css/js frontends. Pago will be lightweight and use few external dependencies. For example, information about payments will be stored in a viewonly wallet file, which is password-encrypted by default and can be backed up like any database. Unlike, for example, an SQL database, a wallet file is an unopinionated monero standard. This means there's no need to import libraries for database queries; everything can be queried through the official wallet RPC.

Pago's frontends will be unstyled unopinionated code snippets, not complete stand-alone dashboards. This will allow them to be implemented into existing websites by hand. In the future, these snippets can be adapted into plugins for various ecommerce platforms like WooCommerce, Odoo, and Magento.

The need for processors

I've noticed that most websites that accept cryptocurrency online use PayPal to do so. PayPal collects data and charges a "swipe" fee. This goes against monero's ethos of being private and having low transaction fees, yet there are few options for non-saavy webmasters to implement monero payments on a website. Easy-to-deploy payment processors like pago are needed to make it easier for businesses to accept monero as payment, which in turn catalyzes a circular economy where goods and services can be ordered with monero.

Structural overview

Pago will have three major components, shown in the dashed square below:

     monero network


 ┌─────────▼───────────┐
 │monerod (remote node)│
 └─────────────▲───────┘
      DaemonRPC│
   ┌───────────▼────┐
   │View-only wallet│
   └─▲────────────▲─┘
     │  WalletRPC │
+----│------------│----+
| ┌──▼──────────┐ │    |
| │ Payment API │ |    |
| └───────▲─────┘ │    |
|  HTTP/WS│       │    |
| ┌───────▼┐ ┌────▼───┐|
| │Payment │ │Merchant│|
| │Frontend│ │Frontend│|
| └────────┘ └────────┘|
+-----------------pago-+
  1. The Payment API which creates and checks payments using authenticated RPC calls to a viewonly monero wallet
  2. The Payment frontend, an html/js/css interface for customers/donors to make payments
  3. The Merchant frontend, an html/js/css interface for merchants to check payment status

Pago requires an existing monero wallet and daemon. To maximize flexibility for the admin, it will come with a docker-compose file with the following sane defaults:

  • Public remote node
  • Dockerized wallet generated from Address and ViewKey
  • Dockerized APIs

However, it will be easy for the admin to:

  • Use another monero daemon or activate a containerized one by uncommenting a paragraph in the docker-compose file
  • Use an existing wallet, perhaps from a previous pago instance
  • Run anything or everything outside docker

When initiating pago, the admin chooses a subaccount (in the .env file) for use with pago. Pago will create subaddresses for each "order". In this way, even if a wallet file is lost, an unlabeled history of received payments can still be restored from the blockchain with the address and viewkey.

Payment API

The payment API will be written in NodeJS and runnable in a docker container. The whole point of this API is to restrict access to the wallet RPC so a client doesn't have access to all its methods. That is, a client that knows its own subaddress can access details about it using get_address_index but must not be able to access a list of other subaddresses using get_address. The API will have at least these methods:

  • createPayment, which wraps create_address and creates a new subaddress for an individual "purchase". The requested amount and perhaps other details will be saved in the subaddress "label". The subaddress will be returned to the payment frontend.
  • getPayment, which wraps get_address_index and will take a subaddress as input and return the total amount requested (from the label) and the status of any transactions to that subaddress.

Payment frontend

The payment frontend lets customers "checkout" or make a donation of an arbitrary amount. It will:

  • Call the payment API but can't make authenticated WalletRPC calls directly.
  • Receive a subaddress from the payment API's createPayment endpoint.
  • Display a QR code and public key (subaddress). Clicking either will open the user's wallet application using the existing monero URI standard.
  • Instantly update when a transaction hits the mempool. This update will use websockets if javascript is enabled.
  • Support partial payments. If a partial payment is made, the QR code and URI will update to the remaining balance instantly (if javascript is enabled).
  • Support browsers with javascript turned off. A note in a <noscript> tag will alert the user to the need to refresh the page regularly to check payment status.
  • Show all transactions and their confirmations in a table. A timer emoji (️) will indicated transactions with less than 10 confirmations, while a checkbox () indicates 10 or more confirmations. A double-spend will be detected and marked by an X emoji ().

Merchant frontend

The merchant frontend allows merchants to track payments and their confirmations so they can decide, for example, whether to ship a product or not.

  • Connects to the wallet RPC directly using authenticated calls
  • Will display the status (confirmations, amount, etc) and emojis (️,,) of payments and their transactions.

Future proposals

  • eCommerce plugins: Plugins for popular eCommerce sites like WooCommerce, Odoo, and Magento would be a logical next step, as most online stores are built using these tools. These plugins would leverage the payment and merchant frontends to allow shop owners to accept monero payments quickly and easily.
  • Support for subscriptions: Additional details like subscription id and payment interval saved in the address's label field would make subscriptions easier to manage. For example, a customer that pays monthly for a VPS could pay in monero. The frontends would also need to be updated, e.g. to notify customers of upcoming payments and provide them with a new payment page.

Similar projects

moneroPay is similar thing but uses a separate SQL database and does not provide frontends. Standalone AcceptXMR isn't done yet. BTCPay Server spawns half a dozen docker containers for a single currency and eats all your resources. Also doesn't support using a public remote node (yet).

Merge request reports