org.bitcoinj.protocols.payments

Class PaymentSession

java.lang.Object

org.bitcoinj.protocols.payments.PaymentSession

public class PaymentSession
extends Object

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

A PaymentSession can be initialized from one of the following:

• A BitcoinURI object that conforms to BIP 0072
• A url where the Protos.PaymentRequest can be fetched
• Directly with a Protos.PaymentRequest object

If initialized with a BitcoinURI or a url, a network request is made for the payment request object and a ListenableFuture 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 ListenableFuture 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 Summary

Fields

Modifier and Type	Field and Description
PaymentProtocol.PkiVerificationData	pkiVerificationData Stores the calculated PKI verification data, or null if none is available.

Constructor Summary

Constructors

Constructor and Description
PaymentSession(Protos.PaymentRequest request) Creates a PaymentSession from the provided Protos.PaymentRequest.
PaymentSession(Protos.PaymentRequest request, boolean verifyPki) Creates a PaymentSession from the provided Protos.PaymentRequest.
PaymentSession(Protos.PaymentRequest request, boolean verifyPki, TrustStoreLoader trustStoreLoader) Creates a PaymentSession from the provided Protos.PaymentRequest.

Method Summary

Modifier and Type	Method and Description
static ListenableFuture<PaymentSession>	createFromBitcoinUri(BitcoinURI uri) Returns a future that will be notified with a PaymentSession object after it is fetched using the provided uri.
static ListenableFuture<PaymentSession>	createFromBitcoinUri(BitcoinURI uri, boolean verifyPki) Returns a future that will be notified with a PaymentSession object after it is fetched using the provided uri.
static ListenableFuture<PaymentSession>	createFromBitcoinUri(BitcoinURI uri, boolean verifyPki, TrustStoreLoader trustStoreLoader) Returns a future that will be notified with a PaymentSession object after it is fetched using the provided uri.
static ListenableFuture<PaymentSession>	createFromUrl(String url) Returns a future that will be notified with a PaymentSession object after it is fetched using the provided url.
static ListenableFuture<PaymentSession>	createFromUrl(String url, boolean verifyPki) Returns a future that will be notified with a PaymentSession object after it is fetched using the provided url.
static ListenableFuture<PaymentSession>	createFromUrl(String url, boolean verifyPki, TrustStoreLoader trustStoreLoader) Returns a future that will be notified with a PaymentSession object after it is fetched using the provided url.
Date	getDate() Returns the date that the payment request was generated.
Date	getExpires() Returns the expires time of the payment request, or null if none.
String	getMemo() Returns the memo included by the merchant in the payment request, or null if not found.
byte[]	getMerchantData() Returns the merchant data included by the merchant in the payment request, or null if none.
NetworkParameters	getNetworkParameters() Gets the params as read from the PaymentRequest.network field: main is the default if missing.
List<PaymentProtocol.Output>	getOutputs() Returns the outputs of the payment request.
Protos.Payment	getPayment(List<Transaction> txns, Address refundAddr, String memo) Generates a Payment message based on the information in the PaymentRequest.
Protos.PaymentDetails	getPaymentDetails() Returns the protobuf that describes the payment to be made.
Protos.PaymentRequest	getPaymentRequest() Returns the protobuf that this object was instantiated with.
String	getPaymentUrl() Returns the payment url where the Payment message should be sent.
SendRequest	getSendRequest() Returns a SendRequest suitable for broadcasting to the network.
Coin	getValue() Returns the total amount of bitcoins requested.
boolean	isExpired() This should always be called before attempting to call sendPayment.
ListenableFuture<PaymentProtocol.Ack>	sendPayment(List<Transaction> txns, Address refundAddr, String memo) Generates a Payment message and sends the payment to the merchant who sent the PaymentRequest.
protected ListenableFuture<PaymentProtocol.Ack>	sendPayment(URL url, Protos.Payment payment)
PaymentProtocol.PkiVerificationData	verifyPki() Returns the value of pkiVerificationData or null if it wasn't verified at construction time.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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.

Constructor Detail

PaymentSession

public PaymentSession(Protos.PaymentRequest request)
               throws PaymentProtocolException

Creates a PaymentSession from the provided Protos.PaymentRequest. Verifies PKI by default.

Throws:

PaymentProtocolException

PaymentSession

public PaymentSession(Protos.PaymentRequest request,
                      boolean verifyPki)
               throws PaymentProtocolException

Creates a PaymentSession from the provided Protos.PaymentRequest. If verifyPki is true, also validates the signature and throws an exception if it fails.

Throws:

PaymentProtocolException

PaymentSession

public PaymentSession(Protos.PaymentRequest request,
                      boolean verifyPki,
                      @Nullable
                      TrustStoreLoader trustStoreLoader)
               throws PaymentProtocolException

Creates a PaymentSession from the provided Protos.PaymentRequest. If verifyPki is true, also validates the signature and throws an exception if it fails. If trustStoreLoader is null, the system default trust store is used.

Throws:

PaymentProtocolException

Method Detail

createFromBitcoinUri

public static ListenableFuture<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 ListenableFuture<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 ListenableFuture<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 ListenableFuture<PaymentSession> createFromUrl(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 ListenableFuture<PaymentSession> createFromUrl(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 ListenableFuture<PaymentSession> createFromUrl(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 List<PaymentProtocol.Output> getOutputs()

Returns the outputs of the payment request.

getMemo

@Nullable
public 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.

getDate

public Date getDate()

Returns the date that the payment request was generated.

getExpires

@Nullable
public Date getExpires()

Returns the expires time of the payment request, or null if none.

isExpired

public boolean isExpired()

This should always be called before attempting to call sendPayment.

getPaymentUrl

@Nullable
public 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

@Nullable
public ListenableFuture<PaymentProtocol.Ack> sendPayment(List<Transaction> txns,
                                                                   @Nullable
                                                                   Address refundAddr,
                                                                   @Nullable
                                                                   String memo)
                                                            throws PaymentProtocolException,
                                                                   VerificationException,
                                                                   IOException

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, returns null and does nothing.

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.

Throws:

PaymentProtocolException

VerificationException

IOException

getPayment

@Nullable
public Protos.Payment getPayment(List<Transaction> txns,
                                           @Nullable
                                           Address refundAddr,
                                           @Nullable
                                           String memo)
                                    throws IOException,
                                           PaymentProtocolException.InvalidNetwork

Generates a Payment message based on the information in the PaymentRequest. Provide transactions built by the wallet. If the PaymentRequest did not specify a payment_url, returns null.

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.

Throws:

IOException

PaymentProtocolException.InvalidNetwork

sendPayment

protected ListenableFuture<PaymentProtocol.Ack> sendPayment(URL url,
                                                            Protos.Payment payment)

verifyPki

@Nullable
public PaymentProtocol.PkiVerificationData verifyPki()

Returns the value of pkiVerificationData or null if it wasn't verified at construction time.

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.