Interledger Payment Method

This specification describes data structures and formats, and a simple processing model, to facilitate payments on the Web using the standards defined by the Interledger Protocol [[!interledger-protocol]].

The working group maintains a list of all bug reports that the group has not yet addressed. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

This specification was contributed by the Interledger Payments Community Group.

Sending comments on this document

If you wish to make comments regarding this document, please raise them as GitHub issues. Only send comments by email if you are unable to raise issues on GitHub (see links below). All comments are welcome.

Introduction

This specification defines the "interledger" payment method for use, for instance, with the Payment Request API. With it, merchants can request a payment that follows the Interledger standards.

The Interledger Protocol defines a number of standards that can be universally applied to all payments, irrespective of the network used to initiate or receive the payment. These include a universal addressing scheme for any destination account, a two-phase request/response orchestration for payment authorization, and a standard message "signature" scheme using simple SHA-256 hash digests.

Model

This section defines concepts used in this specification.

Interledger Addresses

An Interledger Address is an address for any account on any payment network that can be the target of a payment. This includes traditional payment accounts like bank accounts (identified by an IBAN or account number), or card accounts (identified by a PAN), but also accounts on newer networks such as distributed ledgers and crypto-currency systems. It is defined in the [[!interledger-addresses]] specification.

The scheme is a hierarchical addressing scheme where addresses are expressed as case-sensitive, ASCII strings containing one or more segments delimited by the period character. Their hierarchical nature makes them well-suited for routing payments while their large allowed size means that new addresses can be created per payment and reference data included in the suffix.

Conditions, Fulfillments and Errors

The Condition is a 32-byte number that is the result of performing the one-way SHA-256 hash operation on the 32-byte Fulfillment. The Condition is provided by the payer in an Interledger payment. The Fulfillment is returned by the payee in an Interledger payment.

In the case of a failed payment an error will be returned with an appropriate Interledger Error Code to indicate the cause of the failure.

More details on the role of conditions and fulfillments and details of the different error codes can be found in the [[!interledger-protocol]] specification.

Payment Pointer

A Payment Pointer is an identifer, that can be used to resolve and discover the details of a payment. It may resolve to the details of an entity or a specific obligation that can be paid (such as an invoice).

Specifically, a Payment Pointer is resolved to a payment setup protocol receiver endpoint as defined in the [[!payment-pointers]] specification.

Flow

An Interledger payment is initiated by the payer upon receipt of a Payment Pointer from the payee. The payer (or their agent) uses this to resolve a payment setup protocol receiver endpoint which it queries for the details of the payment.

The payer then completes an Interledger payment and returns the Interledger Address and Fulfillment to the payee to allow them to verify the payment has been completed successfully.

Interfacing with a payment handler

The steps to complete a payment with a payment handler with InterledgerRequest data are given by the following algorithm. If the end user successfully completes the payment the algorithm returns an Interledger Address and a Fulfillment in an InterledgerResponse.

Let response be an InterledgerResponse.
Perform the steps defined in [[!payment-pointers]] to resolve the payment details from the Payment Pointer at data["payee"].
Complete a payment to the Interledger Address derived from those payment details.
Set response["payeeAddress"] to the Interledger Address the payment was sent to.
If the payment was successful set response["fulfillment"] to the Fulfillment returned upon completing the payment.
Else, let error be an InterledgerError and:
1. Set error["errorCode"] to the Interledger Error Code returned in the failed payment.
2. Set error["triggeredBy"] to the Interledger Address indicated in the failed payment as the source of the error.
3. Set response["error"] to error.
Return response.

InterledgerResponse

        interface InterledgerError {
          attribute DOMString errorCode;
          attribute DOMString triggeredBy;
        };

        dictionary InterledgerResponse {
          DOMString payeeAddress;
          DOMString? fulfillment;
          InterledgerError? error;
        };

The InterledgerResponse dictionary contains the following fields:

payeeAddress: The payeeAddress field contains the ILP Address of the payee.
fulfillment: The fulfillment field contains the Fulfillment that was returned by the payee during the Interledger payment. The 32-bytes are returned as a Base64 encoded string per [[!RFC4648]].
error: The error field will contain an InterledgerError if there was an error processing the payment.

InterledgerError

The InterledgerError interface contains the following attributes:

errorCode: The errorCode is an Interledger Error Code.
triggeredBy: The triggeredBy member contains the Interledger Address of the entities that originally emitted the error.