Open Payments flow

Summary

When a client issues payment instructions, numerous interactions between the client and servers are needed to obtain grants, verify identities, and create the resources required to complete a transaction.

This page provides a high-level look at the API calls and interactions that occur between the client and servers during a payment. The sequence diagrams are for illustrative purposes and may be simplified in some instances.

Assumptions

• The client’s ? Such as a mobile or web application or service user is the sender.
• The client already has the sender’s Open Payments-enabled account details and is able to send payments on their behalf.

Get account details

A client retrieves public details about a recipient’s Open Payments-enabled account by issuing a GET request to the recipient’s wallet address. Details include the asset code and scale of the underlying account, as well as the authorization and resource server URLs which the client needs in order to set up a payment to the recipient.

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

Incoming payment

The client first requests/receives a grant from the authorization server of the recipient’s ASE ? account servicing entity to create an incoming-payment resource. The client then sends a request to the ASE’s 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 recipient.

sequenceDiagram
    participant C as Client
    participant AS as Authorization server
recipient's ASE
    participant RS as Resource server
recipient's ASE

    C->>AS: POST grant request with type=incoming-payment
    AS-->>C: 200 OK, returns access token
    C->>RS: POST create incoming payment
    RS-->>C: 201 incoming payment created, return incoming payment with public details

View full diagram

Quote

The client requests/receives a grant from the authorization server of the sender’s ASE ? Account servicing entity to create a quote resource. The client then sends a request to the 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
    participant AS as Authorization server
sender's ASE
    participant RS as Resource server
sender's ASE

    C->>AS: POST grant request with type=quote
    AS-->>C: 200 OK, returns access token
    C->>RS: POST create quote
    RS-->>C: 201 quote created, returns quote details

View full diagram

Outgoing payment

Before an outgoing payment resource can be created on the sender’s account, Open Payments requires the client to send an interactive grant request to the authorization server of the sender’s ASE ? Account servicing entity .

An interactive grant requires explicit consent be collected from the sender before an access token is issued. While the client must facilitate the interaction, the authorization server and identity provider (IdP) of the sender’s ASE 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.

Continue request timing

For outgoing payments, explicit user consent is required before proceeding with the continuation request. After the user completes their interaction with the identity provider (IdP), they should be redirected back to your application. At this point, you can make the grant continuation request. In scenarios where a user interface is not available, consider implementing a polling mechanism to check for the completion of the interaction.

sequenceDiagram autonumber
    Client->>Authorization server (AS): POST grant request (with interact object)
    Authorization server (AS)-->>Client: 200 OK, returns interact redirect URI and continue URI
    Client->>Authorization server (AS): Navigates to interact redirect URI
    Authorization server (AS)->>Authorization server (AS): Starts interaction and sets session
    Authorization server (AS)-->>Client: 302 temporary redirect to identity provider 
URI with grant info in query string
    Client->>Identity provider (IdP): Redirects to identity provider
    Identity provider (IdP)->>Identity provider (IdP): Resource owner (e.g. client 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 URI 
(defined in initial grant request) 
secured with unique hash and 
interact_ref in query string
    Identity provider (IdP)->>Client: Follows redirect
    Client->>Client: Verifies hash
    Client->>Authorization server (AS): POST grant continuation request with 
interact_ref in body to continue URI
    Authorization server (AS)-->>Client: 200 OK, 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
    participant RS as Resource server
sender's ASE

    C->>RS: POST create outgoing payment
    RS-->>C: 201 outgoing payment created, 
returns outgoing payment details

View full diagram

Get transaction history

To provide a 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, returns array of incoming/outgoing payments 
with relevant payment details

View full diagram

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

sequenceDiagram

    participant C as Client
    participant RS as Resource server

    C->>RS: GET an incoming/outgoing payment with 
id={URL identifying incoming/outgoing payment}
    RS-->>C: 200 incoming/outgoing payment found, 
returns incoming/outgoing payment details

View full diagram

Bringing it all together

This diagram brings the aforementioned concepts together, except for getting transaction history, to present a full transaction sequence without delving too deeply into the contents of each request and response. A link to view a larger version of the diagram is provided at the bottom of the page.

As shown below, both the sender and the recipient’s ASEs must operate their own authorization and resource servers. Grant requests for incoming payment and quote resources are typically non-interactive. A grant request for an outgoing payment resource requires explicit consent from the sender (e.g., the client’s user), which is obtained through the sender’s identity provider.

More information about grant interaction flows can be found in the Grant negotiation and authorization page.

sequenceDiagram
    autonumber
    box rgb(225,245,254) Sender's
account servicing entity
    participant SIDP as Identity provider
    participant SRS as Resource server
    participant SAS as Auth server
    end
    participant SC as Client
    box rgb(232,245,233) Recipient's
account servicing entity
    participant RW as Wallet address URL
    participant RAS as Auth server
    participant RRS as Resource server
    end
    SC->>+RW: Requests the wallet address
    RW-->>-SC: Provides the wallet address details
    SC->>+RAS: Requests a non-interactive grant for an incoming payment
    RAS-->>-SC: Provides access token and grant for the payment
    SC->>+RRS: Request to create the incoming payment
    RRS->>+RAS: Requests access token validation
    RAS-->>-RRS: Access token is validated
    RRS-->>-SC: Responds with created incoming payment details
    SC->>+SAS: Requests a non-interactive grant for a quote
    SAS-->>-SC: Provides access token and grant for the quote
    SC->>+SRS: Request to create the quote
    SRS-->>-SC: Quote is created
    SC->>+SAS: Requests an interactive grant for an outgoing payment
    SAS-->>-SC: Provides interact redirect URI and continue URI
    SC->>+SAS: Navigates to the interact redirect URI
    SAS->>SAS: Starts the interaction process and sets up the session
    SAS-->>-SC: Provides identity provider URI
    SC->>+SIDP: Navigates (redirects) to identity provider
    SIDP->>SIDP: Sender accepts interaction, 
confirms payment intent
    SIDP->>SAS: Sends interaction choice
    SAS-->>SIDP: Confirms the choice has been accepted
    SIDP->>SAS: Requests to finalize the interaction
    SAS->>SAS: Completes the session
    SAS->>SIDP: Redirects to interact URI defined in initial grant request
    SIDP-->>-SC: Client follows redirect
    SC->>SC: Verifies hash
    SC->>+SAS: Requests a grant continuation
    SAS-->>SC: Provides a grant access token
    SC->>+SRS: Request to create the outgoing payment
    SRS->>SAS: Requests access token validation
    SAS-->>SRS: Access token is validated
    SRS->>-SC: Responds with created outgoing payment details

View full diagram