Open Payments flow

This page describes the Open Payments flows at a high level. The sequence diagrams are for illustrative purposes and might not be an exact representation of a given flow.

Get account details

A client can retrieve public details about an Open Payments-enabled account by issuing a GET request to the account’s wallet address. Details include the asset code and scale of the underlying account and the authorization server endpoint to call for grant requests.

sequenceDiagram
    participant C as Client
    participant WA as Wallet address

    C->>WA: GET wallet address url (e.g. https://wallet.example.com/alice)
    WA->>C: 200 wallet address found, return public account details

View full diagram

Basic payment flow

Assumptions

• The client’s end-user is the payer.
• The client already has the payer’s OP-enabled account details and is able to send payments on behalf of the payer.
• The client has issued a GET request to the payee’s wallet address and received the authorization server and resource server URLs.

Incoming payment

The client first requests/receives a grant from the payee’s authorization server to create an incoming-payment resource. The client then sends a request to the payee-side resource server to create the resource. When created, the resource server returns unique payment details the client will use to address one or more payments to the payee.

sequenceDiagram
    participant C as Client instance
    participant AS as Payee-side
authorization server
    participant RS as Payee-side
resource server

    C->>AS: Grant request (POST) with type=incoming-payment
    AS->>C: 200 OK, returns access token
    C->>RS: Create incoming payment resource (POST)
    RS->>C: 201 Incoming payment resource created

View full diagram

Quote

The client requests/receives a grant from the end-user’s authorization server to create a quote resource. The client then sends a request to the end-user’s resource server to create the resource. When created, the resource server returns, among other things, a quote id and the amount it will cost to make the payment.

sequenceDiagram
    participant C as Client instance
    participant AS as Payer-side
authorization server
    participant RS as Payer-side
resource server

    C->>AS: Grant request (POST) with type=quote
    AS->>C: 200 OK, returns access token
    C->>RS: Create quote resource (POST)
    RS->>C: 201 Quote resource created

View full diagram

Outgoing payment

Before an outgoing payment resource can be created on the end-user’s account, Open Payments requires the client to send an interactive grant request to the authorization server.

An interactive grant requires explicit consent be collected from the end-user before an access token is issued. While the client must facilitate the interaction, the end-user’s authorization server and identity provider are responsible for the interface and collecting consent.

After consent is obtained, the client requests permission to continue the grant request in order to obtain an access token.

sequenceDiagram
    Client instance->>Authorization server (AS): Sends interactive grant request
    Authorization server (AS)-->>Client instance: 200 returns interact redirect uri and continue uri
    Client instance->>Authorization server (AS): Navigates to interact redirect uri
    Authorization server (AS)->>Authorization server (AS): Starts interaction and sets session
    Authorization server (AS)-->>Client instance: 302 temporary redirect to identity provider 
uri with grant info in query string
    Client instance->>Identity provider (IdP): Redirects to identity provider
    Identity provider (IdP)->>Identity provider (IdP): Resource owner (e.g. client end-user) 
accepts interaction
    Identity provider (IdP)->>Authorization server (AS): Sends interaction choice
    Authorization server (AS) -->>Identity provider (IdP): 202 choice accepted
    Identity provider (IdP)->>Authorization server (AS): Requests to finish interaction
    Authorization server (AS)->>Authorization server (AS): Ends session
    Authorization server (AS)-->>Identity provider (IdP): 302 temporary redirect to finish url 
(defined in initial grant request) 
secured with unique hash and 
interact_ref in query string
    Identity provider (IdP)->>Client instance: Follows redirect
    Client instance->>Client instance: Verifies hash
    Client instance->>Authorization server (AS): Sends grant continuation request with 
interact_ref in body to continue uri
    Authorization server (AS)->>Client instance: 200 returns grant access token

View full diagram

Once an access token is acquired, the client can request the creation of the outgoing-payment resource. The setup of the payment is complete and the Open Payments flow ends after the resource is created.

sequenceDiagram

    participant C as Client instance
    participant RS as Payer-side
resource server

    C->>RS: Create outgoing payment resource (POST)
    RS->>C: 201 Outgoing payment resource created

View full diagram

Get transaction history

To provide an end-user with their transaction history, the client can retrieve a list of the user’s incoming (received) payments and outgoing (sent) payments.

sequenceDiagram

    participant C as Client
    participant RS as Resource server

    C->>RS: Get list of incoming/outgoing payments 
with wallet-address={url of wallet address}
    RS->>C: 200 OK

View full diagram

Similarly, the client can provide the end-user with details about a specific incoming or outgoing payment.

sequenceDiagram

    participant C as Client
    participant RS as Resource server

    C->>RS: Get incoming/outgoing payment with 
id={url identifying incoming/outgoing payment}
    RS->>C: 200 Payment found

View full diagram

Complex flow

sequenceDiagram
    participant Cu as Customer
    participant A2 as Auth Server B
    participant R2 as Backend B
    participant R1 as Backend A
    participant A1 as Auth Server A
    participant Cl as Merchant

    activate Cl
    Cl->>+A1: incoming payment grant request
    A1->>-Cl: grant + access token
    Cl->>+R1: incoming payment creation request
    R1->>+A1: token introspection
    A1->>-R1: token valid + grant details
    R1->>-Cl: incoming payment
    rect rgba(0, 0, 255, .1)
    Cl->>+Cu: request wallet address
    Cu->>Cl: wallet address
    end
    Cl->>+R2: query customer's wallet address
    R2->>-Cl: wallet address details including auth server endpoint
    Cl->>+A2: quote grant request
    A2->>-Cl: grant + access token
    Cl->>+R2: quote creation request
    R2->>+A2: token introspection
    A2->>-R2: token valid + grant details
    R2->>-Cl: quote
    Cl->>+A2: outgoing payment grant request
    A2->>-Cl: IdP redirect info
    rect rgba(0, 0, 255, .1)
    Cl->>Cu: redirect to IdP
    Cu->>Cu: consent to grant request
    Cu->>-Cl: interaction finished
    end
    Cl->>+A2: continue grant request
    A2->>-Cl: grant + access token
    Cl->>+R2: outgoing payment creation request
    R2->>+A2: token introspection
    A2->>-R2: token valid + grant details
    R2->>R2: grant accounting
    R2->>-Cl: outgoing payment
    deactivate Cl

View full diagram