DOCSEARCHbyAlgolia
Submit Docs

Open Payments Documentation

repository·main·Indexed 19 days ago

https://github.com/interledger/open-payments

Open Payments is an open API standard enabling interoperability for payments across account servicing entities like banks and digital wallets. It provides a framework for wallet address discovery, resource management, and GNAP-compliant authorization, supporting use cases such as Web Monetization, eCommerce, P2P transfers, and subscriptions.

Tokens
128.5K
Snippets
288
Records
411
Agent score
63%

What's inside Open Payments

  1. What is Open Payments?

    main

    Open Payments is an open API standard designed for account servicing entities (such as banks, digital wallet providers, and mobile money providers) to enable interoperability for various payment use cases, including Web Monetization, eCommerce, P2P transfers, and subscriptions.

    The standard is composed of three core sub-systems:

    1. Wallet address server: Exposes public information about Open Payments-enabled accounts (wallet addresses).
    2. Resource server: Provides APIs to perform functions against the underlying accounts.
    3. Authorisation server: Provides APIs compliant with the GNAP standard to obtain grants for accessing the resource server APIs.

  2. Overview of Open Payments security posture

    main

    Open Payments relies on three cryptographic checkpoints to secure interactions between clients and ASEs (Authorization/Resource Servers). ASEs are responsible for the verification side of all three:

    1. HTTP message signatures: Authenticates the sender and detects tampering on every request.
    2. Client keys: Ensures the ASE knows which public key to verify against (via wallet address JWKS or directed identity).
    3. Interaction hashes: Allows clients to verify that a redirect during an interactive grant actually originated from the ASE's authorization server.

  3. What is a wallet address?

    main

    A wallet address is a secure, sharable URL that acts as a service endpoint for an Open Payments-enabled account. It serves two primary functions:

    1. Proxy Identifier: It acts as an alias for an underlying financial account, allowing for privacy (e.g., generating unique addresses for different clients to prevent tracking).
    2. Resource Locator: It provides the entry point for clients to interact with the account via Open Payments APIs and the Account Servicing Entity (ASE).

    Key Characteristics:

    • All wallet addresses are URLs, but not all URLs are wallet addresses.
    • A single account can have multiple wallet addresses if permitted by the ASE.
    • Clients should treat any two distinct wallet addresses as distinct accounts, even if they proxy the same underlying account. Permission for one address does not grant permission for another.

  4. What is an Account Servicing Entity (ASE)?

    main

    An Account Servicing Entity (ASE) is a regulated provider (such as a bank, digital wallet, or mobile payment system) that maintains payment accounts for senders and recipients.

    By adopting the Open Payments standard, an ASE makes its customers' financial accounts Open Payments-enabled. This allows client developers to use standardized APIs to retrieve account details and issue payment instructions, eliminating the need for custom integrations for every individual ASE.

  6. How amounts are represented in Open Payments

    main

    In Open Payments, monetary values are represented using a standardized structure consisting of three components: value, assetCode, and assetScale. This approach avoids floating-point errors by using integers for calculations.

    Components

    • value: A numerical representation of the amount. To maximize precision, Open Payments uses unsigned 64-bit integers without decimals.
    • assetCode: The identifier for the currency or asset, following the ISO 4217 standard (e.g., USD, EUR).
    • assetScale: A number between 0 and 255 that indicates the number of decimal places for the currency.

    Conversion Formula

    To convert the integer value to a human-readable display amount, use the following formula:

    $$\frac{\text{value}}{10^{\text{assetScale}}} = \text{display amount}$$

    Example Structure

    An amount of $100.00 USD is represented as:

    {
  "value": "10000",
  "assetCode": "USD",
  "assetScale": 2
}

  7. Implement token validation for the resource server

    main

    The resource server must validate access tokens using one of two patterns chosen by the ASE:

    1. Introspection: The resource server calls the authorization server for every request to check the token. This is simple but increases traffic/latency.
    2. Self-contained tokens: The authorization server signs tokens that the resource server validates locally using shared key material. This is more scalable but requires robust revocation propagation.

  8. How interactive grants work for outgoing payments

    main

    Outgoing payments require explicit user consent before a grant can be issued. This is handled via an interactive grant process:

    1. The client requests an outgoing payment grant from the authorization server.
    2. The authorization server provides the client with an Identity Provider (IdP) URI.
    3. The client redirects the user to that IdP URI to obtain consent.

    Authorization servers issuing interactive grants must be integrated with an identity provider (IdP).

  10. How grants and access tokens relate

    main

    The authorization server translates a grant into one or more access tokens.

    • Grant: A durable state held by the authorization server that records what the resource owner consented to. It is the basis for issuing tokens.
    • Access Token: A short-lived credential bound to a grant.

    Key constraints:

    • The authorization server must validate the grant every time a client uses an access token.
    • Revoking a grant must automatically revoke every access token bound to it.
    • ASEs decide if tokens are opaque (requiring a callback to the ASE for validation) or self-contained (validated locally by the resource server via shared keys).

  11. Define recurring intervals for outgoing payments

    main

    When requesting an interactive outgoing payment grant for recurring subscriptions, use the interval property to define the repetition pattern. The interval follows a specific format:

    R{repetitions}/{start_date}/{period}

    Example: R12/2025-10-14T00:03:00Z/P1M

    • R12/: The payment repeats 12 times.
    • 2025-10-14T00:03:00Z/: The start date and time (UTC).
    • P1M: The period between repetitions (e.g., P1M for one month).

    This configuration allows a single grant to authorize multiple payments over a set period (e.g., 12 monthly payments).

    R12/2025-10-14T00:03:00Z/P1M

  12. Understand HTTP message signatures in Open Payments

    main

    Open Payments uses HTTP message signatures to secure communications between senders, receivers, or third-party payment systems. These cryptographic digital signatures provide two primary security guarantees:

    1. Authenticity: Verifies the identity of the system requesting access to resources.
    2. Integrity: Protects specific message fields from being tampered with during transit.

    The implementation follows the HTTP Signatures section of the GNAP (Grant Negotiation and Authorization Protocol) specification.