Package org.bitcoinj.protocols.payments

Class PaymentSession

  • public class PaymentSession
extends java.lang.Object

    Provides a standard implementation of the Payment Protocol (BIP 0070)

    A PaymentSession can be initialized from one of the following:

    If initialized with a BitcoinURI or a url, a network request is made for the payment request object and a ListenableCompletableFuture is returned that will be notified with the PaymentSession object after it is downloaded.

    Once the PaymentSession is initialized, typically a wallet application will prompt the user to confirm that the amount and recipient are correct, perform any additional steps, and then construct a list of transactions to pass to the sendPayment method.

    Call sendPayment with a list of transactions that will be broadcast. A Protos.Payment message will be sent to the merchant if a payment url is provided in the PaymentRequest. NOTE: sendPayment does NOT broadcast the transactions to the bitcoin network. Instead it returns a ListenableCompletableFuture that will be notified when a Protos.PaymentACK is received from the merchant. Typically a wallet will show the message to the user as a confirmation message that the payment is now "processing" or that an error occurred, and then broadcast the tx itself later if needed.

    See Also:
    BIP 0070

    • Field Detail

      • pkiVerificationData

        @Nullable
public final PaymentProtocol.PkiVerificationData pkiVerificationData
        Stores the calculated PKI verification data, or null if none is available. Only valid after the session is created with the verifyPki parameter set to true.

    • Method Detail

      • createFromBitcoinUri

        public static ListenableCompletableFuture<PaymentSession> createFromBitcoinUri​(BitcoinURI uri)
                                                                        throws PaymentProtocolException

        Returns a future that will be notified with a PaymentSession object after it is fetched using the provided uri. uri is a BIP-72-style BitcoinURI object that specifies where the Protos.PaymentRequest object may be fetched in the r= parameter.

        If the payment request object specifies a PKI method, then the system trust store will be used to verify the signature provided by the payment request. An exception is thrown by the future if the signature cannot be verified.

        Throws:
        PaymentProtocolException

      • createFromBitcoinUri

        public static ListenableCompletableFuture<PaymentSession> createFromBitcoinUri​(BitcoinURI uri,
                                                                               boolean verifyPki)
                                                                        throws PaymentProtocolException
        Returns a future that will be notified with a PaymentSession object after it is fetched using the provided uri. uri is a BIP-72-style BitcoinURI object that specifies where the Protos.PaymentRequest object may be fetched in the r= parameter. If verifyPki is specified and the payment request object specifies a PKI method, then the system trust store will be used to verify the signature provided by the payment request. An exception is thrown by the future if the signature cannot be verified.
        Throws:
        PaymentProtocolException

      • createFromBitcoinUri

        public static ListenableCompletableFuture<PaymentSession> createFromBitcoinUri​(BitcoinURI uri,
                                                                               boolean verifyPki,
                                                                               @Nullable
                                                                               TrustStoreLoader trustStoreLoader)
                                                                        throws PaymentProtocolException
        Returns a future that will be notified with a PaymentSession object after it is fetched using the provided uri. uri is a BIP-72-style BitcoinURI object that specifies where the Protos.PaymentRequest object may be fetched in the r= parameter. If verifyPki is specified and the payment request object specifies a PKI method, then the system trust store will be used to verify the signature provided by the payment request. An exception is thrown by the future if the signature cannot be verified. If trustStoreLoader is null, the system default trust store is used.
        Throws:
        PaymentProtocolException

      • createFromUrl

        public static ListenableCompletableFuture<PaymentSession> createFromUrl​(java.lang.String url)
                                                                 throws PaymentProtocolException
        Returns a future that will be notified with a PaymentSession object after it is fetched using the provided url. url is an address where the Protos.PaymentRequest object may be fetched. If verifyPki is specified and the payment request object specifies a PKI method, then the system trust store will be used to verify the signature provided by the payment request. An exception is thrown by the future if the signature cannot be verified.
        Throws:
        PaymentProtocolException

      • createFromUrl

        public static ListenableCompletableFuture<PaymentSession> createFromUrl​(java.lang.String url,
                                                                        boolean verifyPki)
                                                                 throws PaymentProtocolException
        Returns a future that will be notified with a PaymentSession object after it is fetched using the provided url. url is an address where the Protos.PaymentRequest object may be fetched. If the payment request object specifies a PKI method, then the system trust store will be used to verify the signature provided by the payment request. An exception is thrown by the future if the signature cannot be verified.
        Throws:
        PaymentProtocolException

      • createFromUrl

        public static ListenableCompletableFuture<PaymentSession> createFromUrl​(java.lang.String url,
                                                                        boolean verifyPki,
                                                                        @Nullable
                                                                        TrustStoreLoader trustStoreLoader)
                                                                 throws PaymentProtocolException
        Returns a future that will be notified with a PaymentSession object after it is fetched using the provided url. url is an address where the Protos.PaymentRequest object may be fetched. If the payment request object specifies a PKI method, then the system trust store will be used to verify the signature provided by the payment request. An exception is thrown by the future if the signature cannot be verified. If trustStoreLoader is null, the system default trust store is used.
        Throws:
        PaymentProtocolException

      • getOutputs

        public java.util.List<PaymentProtocol.Output> getOutputs()
        Returns the outputs of the payment request.

      • getMemo

        @Nullable
public java.lang.String getMemo()
        Returns the memo included by the merchant in the payment request, or null if not found.

      • getValue

        public Coin getValue()
        Returns the total amount of bitcoins requested.

      • time

        public java.time.Instant time()
        Returns the time that the payment request was generated.

      • getDate

        @Deprecated
public java.util.Date getDate()
        Deprecated.
        use time()

      • expires

        public java.util.Optional<java.time.Instant> expires()
        Returns the expires time of the payment request, or empty if none.

      • getExpires

        @Nullable
@Deprecated
public java.util.Date getExpires()
        Deprecated.
        use expires()

      • isExpired

        public boolean isExpired()
        This should always be called before attempting to call sendPayment.

      • getPaymentUrl

        @Nullable
public java.lang.String getPaymentUrl()
        Returns the payment url where the Payment message should be sent. Returns null if no payment url was provided in the PaymentRequest.

      • getMerchantData

        @Nullable
public byte[] getMerchantData()
        Returns the merchant data included by the merchant in the payment request, or null if none.

      • getSendRequest

        public SendRequest getSendRequest()
        Returns a SendRequest suitable for broadcasting to the network.

      • sendPayment

        public ListenableCompletableFuture<PaymentProtocol.Ack> sendPayment​(java.util.List<Transaction> txns,
                                                                    @Nullable
                                                                    Address refundAddr,
                                                                    @Nullable
                                                                    java.lang.String memo)
        Generates a Payment message and sends the payment to the merchant who sent the PaymentRequest. Provide transactions built by the wallet. NOTE: This does not broadcast the transactions to the bitcoin network, it merely sends a Payment message to the merchant confirming the payment. Returns an object wrapping PaymentACK once received. If the PaymentRequest did not specify a payment_url, completes exceptionally.
        Parameters:
        txns - list of transactions to be included with the Payment message.
        refundAddr - will be used by the merchant to send money back if there was a problem.
        memo - is a message to include in the payment message sent to the merchant.
        Returns:
        a future for the PaymentACK

      • getPayment

        @Nullable
public Protos.Payment getPayment​(java.util.List<Transaction> txns,
                                 @Nullable
                                 Address refundAddr,
                                 @Nullable
                                 java.lang.String memo)
                          throws java.io.IOException,
                                 PaymentProtocolException.InvalidNetwork
        Generates a Payment message based on the information in the PaymentRequest. Provide transactions built by the wallet.
        Parameters:
        txns - list of transactions to be included with the Payment message.
        refundAddr - will be used by the merchant to send money back if there was a problem.
        memo - is a message to include in the payment message sent to the merchant.
        Returns:
        Payment message or null (if the PaymentRequest did not specify a payment_url)
        Throws:
        java.io.IOException
        PaymentProtocolException.InvalidNetwork

      • getNetworkParameters

        public NetworkParameters getNetworkParameters()
        Gets the params as read from the PaymentRequest.network field: main is the default if missing.

      • getPaymentRequest

        public Protos.PaymentRequest getPaymentRequest()
        Returns the protobuf that this object was instantiated with.

      • getPaymentDetails

        public Protos.PaymentDetails getPaymentDetails()
        Returns the protobuf that describes the payment to be made.