Package io.fliqa.client.interledger

Interface InterledgerApiClient

All Known Implementing Classes:

InterledgerApiClientImpl

public interface InterledgerApiClient

Client interface for communicating with Interledger Open Payments protocol servers.

This client implements a subset of the Interledger Open Payments specification optimized for Fliqa's payment facilitation use cases. It does not support all Interledger flows but focuses on the core payment workflows where Fliqa acts as an intermediary between senders and receivers.

Configuration Requirements

• Client wallet address (payment facilitator/initiator)
• Ed25519 private key for request signing
• Key ID corresponding to the private key

Supported Payment Flow

The client supports a 7-step payment flow where Fliqa facilitates payments between tenants (receivers) and users (senders):

1. Wallet Discovery - Get wallet information for receiver and sender
2. Receiver Grant - Create access grant for incoming payments
3. Incoming Payment - Create payment request with amount
4. Sender Quote - Calculate transaction costs and fees
5. User Interaction - Redirect user to approve payment
6. Payment Finalization - Complete payment after approval
7. Status Monitoring - Track payment completion

Security

All requests are cryptographically signed using Ed25519 signatures following the HTTP Message Signatures specification. This ensures request authenticity and integrity when communicating with Interledger servers.

Since:

1.0

See Also:

• InterledgerApiClientImpl

Field Summary

Fields

Modifier and Type	Field	Description
static final int	INTERNAL_SERVER_ERROR

Method Summary

Modifier and Type	Method	Description
OutgoingPayment	continueGrant(PaymentPointer sender, Quote quote, URI returnUrl, String nonce)	Creates a pending outgoing payment that requires user interaction for authorization.
IncomingPayment	createIncomingPayment(PaymentPointer receiver, AccessGrant pendingGrant, BigDecimal amount)	Creates an incoming payment request on the receiver's wallet.
AccessGrant	createPendingGrant(PaymentPointer receiver)	Creates a pending grant for a receiving wallet to enable incoming payment creation.
Quote	createQuote(String quoteToken, PaymentPointer sender, IncomingPayment incomingPayment)	Creates a quote that calculates the exact cost for the sender to complete the payment.
AccessGrant	createQuoteRequest(PaymentPointer sender)	Creates a quote request grant for the sender's wallet.
AccessGrant	finalizeGrant(OutgoingPayment outgoingPayment, String interactRef)	Finalizes the grant after the user has approved the payment.
Payment	finalizePayment(AccessGrant finalized, PaymentPointer senderWallet, Quote quote)	Executes the final payment using the finalized grant.
IncomingPayment	getIncomingPayment(IncomingPayment incomingPayment, AccessGrant grantRequest)	Retrieves the current status of an incoming payment.
PaymentPointer	getWallet(WalletAddress address)	Retrieves wallet information from an Interledger payment pointer.

Field Details

INTERNAL_SERVER_ERROR

static final int INTERNAL_SERVER_ERROR

See Also:

• Constant Field Values

Method Details

getWallet

PaymentPointer getWallet(WalletAddress address)
                  throws InterledgerClientException

Retrieves wallet information from an Interledger payment pointer.

This is typically the first step in any payment flow, used to discover the wallet's supported assets, authorization server, and resource server endpoints. The wallet information is essential for subsequent grant requests and payment operations.

Parameters:

address - the wallet address that facilitates, sends, or receives payments

Returns:

wallet information including asset details, authorization server, and resource server URLs

Throws:

InterledgerClientException - if the wallet cannot be found or accessed

See Also:

• PaymentPointer
• WalletAddress

createPendingGrant

AccessGrant createPendingGrant(PaymentPointer receiver)
                        throws InterledgerClientException

Creates a pending grant for a receiving wallet to enable incoming payment creation.

This grant provides Fliqa with permission to create incoming payment requests on behalf of the receiver. The grant includes access tokens that authorize operations like creating, reading, and completing incoming payments.

Step 1 in the payment flow (Receiver side).

Parameters:

receiver - the wallet that will receive the payment

Returns:

access grant containing tokens and permissions for incoming payments

Throws:

InterledgerClientException - if the grant cannot be created or the wallet rejects the request

See Also:

• AccessGrant
• PaymentPointer

createIncomingPayment

IncomingPayment createIncomingPayment(PaymentPointer receiver,
 AccessGrant pendingGrant,
 BigDecimal amount)
                               throws InterledgerClientException

Creates an incoming payment request on the receiver's wallet.

This establishes a payment destination with a specific amount that senders can pay to. The incoming payment serves as the target for the outgoing payment from the sender's wallet.

Step 2 in the payment flow (Receiver side).

Parameters:

receiver - the wallet that will receive the payment

pendingGrant - access grant obtained from createPendingGrant(PaymentPointer)

amount - the payment amount with two decimal places precision

Returns:

incoming payment request that can be referenced by sender wallets

Throws:

InterledgerClientException - if the payment request cannot be created

See Also:

• IncomingPayment
• AccessGrant

createQuoteRequest

AccessGrant createQuoteRequest(PaymentPointer sender)
                        throws InterledgerClientException

Creates a quote request grant for the sender's wallet.

This grant provides permission to request quotes from the sender's wallet, which is necessary to calculate transaction fees and exchange rates before creating the actual payment.

Step 3 in the payment flow (Sender side).

Parameters:

sender - the wallet that will send the payment

Returns:

access grant for creating quotes on the sender's wallet

Throws:

InterledgerClientException - if the quote request grant cannot be created

See Also:

• AccessGrant
• PaymentPointer

createQuote

Quote createQuote(String quoteToken,
 PaymentPointer sender,
 IncomingPayment incomingPayment)
           throws InterledgerClientException

Creates a quote that calculates the exact cost for the sender to complete the payment.

The quote includes the debit amount (what the sender pays) and receive amount (what the receiver gets), accounting for any transaction fees and currency conversions. This quote links the sender's wallet to the specific incoming payment.

Step 4 in the payment flow (Sender side).

Parameters:

quoteToken - access token from the quote request grant

sender - the wallet that will send the payment

incomingPayment - the target payment request created on the receiver's wallet

Returns:

quote containing debit amount, receive amount, and payment details

Throws:

InterledgerClientException - if the quote cannot be generated

See Also:

• Quote
• IncomingPayment

continueGrant

OutgoingPayment continueGrant(PaymentPointer sender,
 Quote quote,
 URI returnUrl,
 String nonce)
                       throws InterledgerClientException

Creates a pending outgoing payment that requires user interaction for authorization.

This step initiates the interactive authorization flow where the user must visit a redirect URL to approve the payment in their wallet. The user will be redirected back to the return URL with an interaction reference upon completion.

Step 5 in the payment flow (Sender side).

Parameters:

sender - the wallet that will send the payment

quote - the quote generated for this payment

returnUrl - URI where the user will be redirected after payment authorization

nonce - unique identifier to prevent replay attacks and maintain state

Returns:

outgoing payment with interaction details including the redirect URL

Throws:

InterledgerClientException - if the payment cannot be created

See Also:

• OutgoingPayment
• Quote

finalizeGrant

AccessGrant finalizeGrant(OutgoingPayment outgoingPayment,
 String interactRef)
                   throws InterledgerClientException

Finalizes the grant after the user has approved the payment.

Once the user completes the interactive authorization flow, they are redirected back with an interaction reference. This method uses that reference to finalize the grant and obtain the final access token needed to execute the payment.

Step 6 in the payment flow (Client side).

Parameters:

outgoingPayment - the pending payment to be finalized

interactRef - interaction reference returned from the user's wallet after authorization

Returns:

finalized access grant with tokens to execute the payment

Throws:

InterledgerClientException - if the grant cannot be finalized or the interaction reference is invalid

See Also:

• AccessGrant
• OutgoingPayment

finalizePayment

Payment finalizePayment(AccessGrant finalized,
 PaymentPointer senderWallet,
 Quote quote)
                 throws InterledgerClientException

Executes the final payment using the finalized grant.

This method transfers the funds from the sender's wallet to the receiver's wallet using the finalized access grant. The payment amount and details are based on the previously generated quote.

Step 7 in the payment flow (Client side).

Parameters:

finalized - the finalized access grant obtained from finalizeGrant(OutgoingPayment, String)

senderWallet - the wallet that will send the payment

quote - the quote that determines payment amounts and fees

Returns:

completed payment details including transaction ID and status

Throws:

InterledgerClientException - if the payment execution fails

See Also:

• Payment
• AccessGrant
• Quote

getIncomingPayment

IncomingPayment getIncomingPayment(IncomingPayment incomingPayment,
 AccessGrant grantRequest)
                            throws InterledgerClientException

Retrieves the current status of an incoming payment.

This method is used to monitor payment completion and track the received amount. It can be called multiple times to poll for payment status updates until the payment is marked as completed.

Parameters:

incomingPayment - the incoming payment to check

grantRequest - the access grant that provides permission to read the payment

Returns:

current payment status including completion state and received amount

Throws:

InterledgerClientException - if the payment cannot be found or access is denied

See Also:

• IncomingPayment
• AccessGrant