Package io.fliqa.client.interledger

Class InterledgerApiClientImpl

java.lang.Object
io.fliqa.client.interledger.InterledgerApiClientImpl
All Implemented Interfaces:
InterledgerApiClient
public class InterledgerApiClientImpl extends Object implements InterledgerApiClient
Default implementation of the InterledgerApiClient interface.

This implementation provides a complete HTTP-based client for the Interledger Open Payments protocol, with cryptographic request signing using Ed25519 keys. The client is designed for Fliqa's payment facilitation use cases where Fliqa acts as an intermediary between payment senders and receivers.

Features

  • Cryptographic request signing using Ed25519 private keys
  • HTTP/2 client with configurable timeouts and connection limits
  • Comprehensive error handling with structured exception types
  • Request/response logging for debugging and auditing
  • Input validation for all public methods

Thread Safety

This implementation is thread-safe and can be used concurrently from multiple threads. The underlying HTTP client and cryptographic operations are thread-safe.

Security

All requests to Interledger servers are signed using Ed25519 signatures following the HTTP Message Signatures specification. The client validates that all required parameters are provided and non-null before making requests.

Error Handling

The client distinguishes between different types of HTTP errors:

  • 4xx errors - Client errors (invalid requests, authentication failures)
  • 5xx errors - Server errors (Interledger server issues)
  • Network errors - Connection timeouts, DNS failures, etc.
Since:
1.0
See Also:

  • Constructor Details

    • InterledgerApiClientImpl

      public InterledgerApiClientImpl(WalletAddress clientWallet, PrivateKey privateKey, String keyId, InterledgerClientOptions options)
      Creates a new Interledger API client with custom configuration options.

      This constructor allows full customization of the HTTP client behavior including connection timeouts, request timeouts, and maximum concurrent connections.

      Parameters:
      clientWallet - the wallet address of the payment facilitator (Fliqa)
      privateKey - Ed25519 private key for signing requests
      keyId - identifier for the private key, used in signature headers
      options - HTTP client configuration including timeouts and connection limits
      Throws:
      IllegalArgumentException - if any parameter is null or keyId is empty
      See Also:

    • InterledgerApiClientImpl

      public InterledgerApiClientImpl(WalletAddress clientWallet, PrivateKey privateKey, String keyId)
      Creates a new Interledger API client with default configuration options.

      This convenience constructor uses default HTTP client settings, including standard timeouts and connection limits suitable for most use cases.

      Parameters:
      clientWallet - the wallet address of the payment facilitator (Fliqa)
      privateKey - Ed25519 private key for signing requests
      keyId - identifier for the private key, used in signature headers
      Throws:
      IllegalArgumentException - if any parameter is null or keyId is empty
      See Also:

  • Method Details

    • createDefaultHttpClient

      protected static HttpClient createDefaultHttpClient(InterledgerClientOptions options)

    • getWallet

      public PaymentPointer getWallet(WalletAddress address) throws InterledgerClientException
      Description copied from interface: InterledgerApiClient
      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.

      Specified by:
      getWallet in interface InterledgerApiClient
      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:

    • createPendingGrant

      public AccessGrant createPendingGrant(PaymentPointer receiver) throws InterledgerClientException
      Description copied from interface: InterledgerApiClient
      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).

      Specified by:
      createPendingGrant in interface InterledgerApiClient
      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:

    • createIncomingPayment

      public IncomingPayment createIncomingPayment(PaymentPointer receiver, AccessGrant pendingGrant, BigDecimal amount) throws InterledgerClientException
      Description copied from interface: InterledgerApiClient
      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).

      Specified by:
      createIncomingPayment in interface InterledgerApiClient
      Parameters:
      receiver - the wallet that will receive the payment
      pendingGrant - access grant obtained from InterledgerApiClient.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:

    • createQuoteRequest

      public AccessGrant createQuoteRequest(PaymentPointer sender) throws InterledgerClientException
      Description copied from interface: InterledgerApiClient
      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).

      Specified by:
      createQuoteRequest in interface InterledgerApiClient
      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:

    • createQuote

      public Quote createQuote(String quoteToken, PaymentPointer sender, IncomingPayment incomingPayment) throws InterledgerClientException
      Description copied from interface: InterledgerApiClient
      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).

      Specified by:
      createQuote in interface InterledgerApiClient
      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:

    • continueGrant

      public OutgoingPayment continueGrant(PaymentPointer sender, Quote quote, URI returnUrl, String nonce) throws InterledgerClientException
      Description copied from interface: InterledgerApiClient
      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).

      Specified by:
      continueGrant in interface InterledgerApiClient
      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:

    • finalizeGrant

      public AccessGrant finalizeGrant(OutgoingPayment outgoingPayment, String interactRef) throws InterledgerClientException
      Description copied from interface: InterledgerApiClient
      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).

      Specified by:
      finalizeGrant in interface InterledgerApiClient
      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:

    • finalizePayment

      public Payment finalizePayment(AccessGrant finalizedGrant, PaymentPointer senderWallet, Quote quote) throws InterledgerClientException
      Description copied from interface: InterledgerApiClient
      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).

      Specified by:
      finalizePayment in interface InterledgerApiClient
      Parameters:
      finalizedGrant - the finalized access grant obtained from InterledgerApiClient.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:

    • getIncomingPayment

      public IncomingPayment getIncomingPayment(IncomingPayment payment, AccessGrant grant) throws InterledgerClientException
      Description copied from interface: InterledgerApiClient
      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.

      Specified by:
      getIncomingPayment in interface InterledgerApiClient
      Parameters:
      payment - the incoming payment to check
      grant - 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:

    • send

      public <T> T send(HttpRequest request, Class<T> responseType) throws InterledgerClientException
      Sends an HTTP request and processes the response to return the desired type.
      Type Parameters:
      T - represents the type of the response object to be returned after deserialization.
      Parameters:
      request - the HTTP request to be sent
      responseType - the class type of the response object to be returned
      Returns:
      the deserialized response of type T
      Throws:
      InterledgerClientException - if an error occurs during the request, response handling, or deserialization process