Open Payments splits one payment API into three servers and borrows GNAP for grants

A standard for the entities that hold the money, not a payment API you call

Open Payments is described as an open API standard that can be implemented by account servicing entities, for example banks, digital wallet providers and mobile money providers, to facilitate interoperability in the setup and completion of payments for different use cases.

The wording is careful and worth unpacking. This is a standard implemented by the parties that hold accounts, not an API a merchant calls to pay someone. If you are a shop looking for a checkout, this is not your project. If you are a bank, a wallet, or a mobile money provider, and you want another company's users to be able to pay you through a protocol both of you implement, it is.

The use cases the README lists are broad: Web Monetization, tipping and donations described as low value and low friction, eCommerce checkout, P2P transfers, subscriptions, and invoice payments.

The homepage is openpayments.dev, the licence is Apache-2.0, and the primary language of the repository is listed as Rust, though the repository itself is mostly documentation and specifications. The project sits under the Interledger organisation, and the README offers a set of starting points for anyone new to Interledger, including the Interledger website, the Interledger specification and an explainer video.

The licensing choice is deliberate in a payments context. Apache-2.0 with an explicit patent grant is the kind of licence a regulated institution asks about before depending on a protocol, and the fact that it is the licence here is part of why interoperability is plausible at all.

Three servers, and the reason the split matters

The Open Payments APIs are a collection of three sub-systems, and the split is the architecture.

A wallet address server exposes public information about Open Payments-enabled accounts, called wallet addresses. A resource server exposes APIs for performing functions against the underlying accounts. And an authorisation server exposes APIs compliant with the GNAP standard for getting grants to access the resource server APIs.

The reason this is three servers rather than one is a separation of concerns that maps onto how the money actually moves. Publishing a wallet address is a public act, like publishing a bank account number. Actually moving money against an account is a privileged act that has to be authorised. And the authority to grant that access is a third thing again, with its own rules about how a client asks for it.

GNAP, the Grant Negotiation and Authorization Protocol, is specified in RFC 9635, and the authorisation server in Open Payments is required to be compliant with it. The README does not describe the internals of any of the three, which is expected, because the detail lives in the specifications repository.

So the three Open Payments OpenAPI specifications are found in the open-payments-specifications repository, while this repository hosts the documentation for the APIs, published on openpayments.dev. That division is the key thing to understand before reading anything else: the normative definitions live elsewhere, and what is here is the prose that explains them.

A documentation site, a submodule, and a Netlify deploy

The repository layout tells you what kind of project this is before you read a line of the documentation.

There is a docs/ directory, a snippets/ directory, an open-payments-specifications entry that is the git submodule for the specification repository, and a pnpm-workspace.yaml with a pnpm-lock.yaml. The top level also has.eslintrc.yml,.eslintignore,.prettierignore,.npmrc and.nvmrc, so the tooling conventions are all in one place.

The package.json is private, which is right for a documentation repository, and it declares the engines as pnpm ^8.15.6 and node 22, with a matching packageManager field. The scripts are the ones you would expect for a docs repo: lint runs eslint with max-warnings=0, format runs prettier and then lint, and there are separate lint and format tasks scoped to the docs workspace with the --filter docs syntax.

There is a checks script that runs both check:prettier and check:lint, which is the gate a contribution has to pass. There is also a clean script that removes node_modules directories with find and prune, and the embeddedLanguageFormatting option is turned off, which is consistent with a repository that embeds code samples from other sources and does not want prettier reformatting them.

The Netlify badge at the top of the README is the deployment signal. openpayments.dev is built and published by Netlify from this repository, which is why the documentation is versioned alongside the prose rather than being edited by hand on a hosting platform.

Running the docs locally, and the submodule that catches people

The Local Development Environment section is short and assumes NVM.

# install node from `./.nvmrc`
nvm install

# install pnpm
corepack enable

# if moving from yarn run
pnpm clean

# install dependencies
pnpm i

# install `open-payments-specifications` submodule
git submodule update --init

The last line is the one that matters. The specifications are a git submodule, and without that command the documentation has no specifications to reference, so pages will be broken or empty in a way that is not obviously a setup mistake.

The Node version comes from the .nvmrc file, and pnpm is enabled through corepack rather than installed globally, which is why the packageManager field pins the exact version. The pnpm clean step exists for people moving from yarn, and it is the clean script from package.json that does the work, removing node_modules directories with find and prune.

Once that is done, you can preview the docs.

pnpm --filter docs start

And the checks are split into two.

# format and lint code:
pnpm format

# check lint and formatting
pnpm checks

# verify code formatting:
pnpm check:prettier

# verify lint
pnpm check:lint

The distinction between format and checks matters in a repository with a lot of embedded code: format writes changes, checks only reports them, and the CI gate is the one that only reports.

The SDKs are the part most implementers will actually touch

The README gives a short section on Open Payments SDKs, which provide developers with pre-built functions that simplify interactions with the Open Payments API. There is a before-you-begin page on client libraries.

The three servers in the previous section are the protocol. The SDKs are what a developer actually calls. That distinction is what makes the project adoptable in practice, because implementing a GNAP compliant authorisation server is a serious undertaking, and a pre-built client for the resource server and wallet address server is where most of the effort is avoided.

What the README does not say is which languages have client libraries, what they cover of the three sub-systems, or how they handle credential management, which is where a payments integration gets its complexity. The client libraries page is where those answers are, and the SDK link is the first place to go after the specifications.

It is also worth noting what is absent. There is no mention of a settlement or clearing layer, no ledger, and no currency conversion, so Open Payments is a protocol for the setup and completion of payments between account servicing entities, not a replacement for the money movement infrastructure underneath them.

Where Open Payments is the wrong tool

Three cases, and the first is a category mistake that costs people a week.

This is not something a merchant integrates to accept a card or a bank transfer. The README says the standard is implemented by account servicing entities, and the use cases are listed as things those entities enable, Web Monetization, tipping, checkout, transfers, subscriptions and invoices. If your requirement is to be able to take a payment, you are looking for a checkout SDK or a payment gateway, and the Open Payments SDKs are for the other side of that arrangement.

The second is the compliance work. Implementing the authorisation server means implementing GNAP, and the resource server needs the grant handling to be correct. The standard gives you the shape, and the security review of your own implementation is on you. For an organisation without a payments engineering function, running your own wallet address and resource server is a significant commitment even with a good specification.

The third is that interoperability is a network effect. The value of the standard comes from other account servicing entities implementing it, and the README does not publish a list of who does. If there is no counterparty in your market using Open Payments, a correct implementation of the standard connects you to nothing, and the effort has no payoff.

That is the honest cost of adopting an open standard, and it is a question to answer before writing code rather than after. The community call, which the README says happens every other Thursday at 12:00 UTC via Google Meet, is a reasonable place to ask.

Editorial conclusion

Adopt Open Payments if you are an account servicing entity, a wallet or mobile money provider, or a merchant integration that needs to move money through a shared protocol rather than a single provider's API. Do not adopt it as a consumer payments SDK, because the repository holds a standard and its documentation, not a service you call as a merchant. Before you build, read the three OpenAPI specifications in the open-payments-specifications repository, since the documentation in this repository is only useful next to them, and check the SDK page for a client library in your language.

Frequently asked questions

Official sources

1. interledger/open-payments on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases