com.google.bitcoin.protocols.payments

Class PaymentSession

java.lang.Object

com.google.bitcoin.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. sendPayment 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.

Author:

Kevin Greene, Andreas Schildbach

See Also:

BIP 0070

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	PaymentSession.Ack Message returned by the merchant in response to a Payment message.
static class	PaymentSession.PkiVerificationData Information about the X509 signature's issuer and subject.

Field Summary

Fields

Modifier and Type	Field and Description
PaymentSession.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, String trustStorePath) Creates a PaymentSession from the provided Protos.PaymentRequest.

Method Summary

Methods

Modifier and Type	Method and Description
static com.google.common.util.concurrent.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 com.google.common.util.concurrent.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 com.google.common.util.concurrent.ListenableFuture<PaymentSession>	createFromBitcoinUri(BitcoinURI uri, boolean verifyPki, String trustStorePath) Returns a future that will be notified with a PaymentSession object after it is fetched using the provided uri.
static com.google.common.util.concurrent.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 com.google.common.util.concurrent.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 com.google.common.util.concurrent.ListenableFuture<PaymentSession>	createFromUrl(String url, boolean verifyPki, String trustStorePath) 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.
String	getMemo() Returns the memo included by the merchant in the payment request, or null if not found.
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.
Wallet.SendRequest	getSendRequest() Returns a Wallet.SendRequest suitable for broadcasting to the network.
BigInteger	getValue() Returns the total amount of bitcoins requested.
boolean	isExpired() This should always be called before attempting to call sendPayment.
com.google.common.util.concurrent.ListenableFuture<PaymentSession.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 com.google.common.util.concurrent.ListenableFuture<PaymentSession.Ack>	sendPayment(URL url, Protos.Payment payment)
PaymentSession.PkiVerificationData	verifyPki() Uses the provided PKI method to find the corresponding public key and verify the provided signature.

Methods inherited from class java.lang.Object

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

Field Detail

pkiVerificationData

public PaymentSession.PkiVerificationData pkiVerificationData

Stores the calculated PKI verification data, or null if none is available. Only valid after the session is created with verifyPki set to true, or verifyPki() is manually called.

Constructor Detail

PaymentSession

public PaymentSession(Protos.PaymentRequest request)
               throws PaymentRequestException

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

Throws:

PaymentRequestException

PaymentSession

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

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

Throws:

PaymentRequestException

PaymentSession

public PaymentSession(Protos.PaymentRequest request,
              boolean verifyPki,
              @Nullable
              String trustStorePath)
               throws PaymentRequestException

Creates a PaymentSession from the provided Protos.PaymentRequest. If verifyPki is true, also validates the signature and throws an exception if it fails. If trustStorePath is not null, the trust store used for PKI verification will be loaded from the given location instead of using the system default trust store location.

Throws:

PaymentRequestException

Method Detail

createFromBitcoinUri

public static com.google.common.util.concurrent.ListenableFuture<PaymentSession> createFromBitcoinUri(BitcoinURI uri)
                                                                                               throws PaymentRequestException

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:

PaymentRequestException

createFromBitcoinUri

public static com.google.common.util.concurrent.ListenableFuture<PaymentSession> createFromBitcoinUri(BitcoinURI uri,
                                                                                      boolean verifyPki)
                                                                                               throws PaymentRequestException

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:

PaymentRequestException

createFromBitcoinUri

public static com.google.common.util.concurrent.ListenableFuture<PaymentSession> createFromBitcoinUri(BitcoinURI uri,
                                                                                      boolean verifyPki,
                                                                                      @Nullable
                                                                                      String trustStorePath)
                                                                                               throws PaymentRequestException

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 trustStorePath is not null, the trust store used for PKI verification will be loaded from the given location instead of using the system default trust store location.

Throws:

PaymentRequestException

createFromUrl

public static com.google.common.util.concurrent.ListenableFuture<PaymentSession> createFromUrl(String url)
                                                                                        throws PaymentRequestException

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:

PaymentRequestException

createFromUrl

public static com.google.common.util.concurrent.ListenableFuture<PaymentSession> createFromUrl(String url,
                                                                               boolean verifyPki)
                                                                                        throws PaymentRequestException

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:

PaymentRequestException

createFromUrl

public static com.google.common.util.concurrent.ListenableFuture<PaymentSession> createFromUrl(String url,
                                                                               boolean verifyPki,
                                                                               @Nullable
                                                                               String trustStorePath)
                                                                                        throws PaymentRequestException

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 trustStorePath is not null, the trust store used for PKI verification will be loaded from the given location instead of using the system default trust store location.

Throws:

PaymentRequestException

getMemo

@Nullable
public String getMemo()

Returns the memo included by the merchant in the payment request, or null if not found.

getValue

public BigInteger getValue()

Returns the total amount of bitcoins requested.

getDate

public Date getDate()

Returns the date that the payment request was generated.

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.

getSendRequest

public Wallet.SendRequest getSendRequest()

Returns a Wallet.SendRequest suitable for broadcasting to the network.

sendPayment

@Nullable
public com.google.common.util.concurrent.ListenableFuture<PaymentSession.Ack> sendPayment(List<Transaction> txns,
                                                                                          @Nullable
                                                                                          Address refundAddr,
                                                                                          @Nullable
                                                                                          String memo)
                                                                                   throws PaymentRequestException,
                                                                                          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:

PaymentRequestException

VerificationException

IOException

getPayment

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

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

sendPayment

protected com.google.common.util.concurrent.ListenableFuture<PaymentSession.Ack> sendPayment(URL url,
                                                                                 Protos.Payment payment)

verifyPki

@Nullable
public PaymentSession.PkiVerificationData verifyPki()
                                             throws PaymentRequestException

Uses the provided PKI method to find the corresponding public key and verify the provided signature. Returns null if no PKI method was specified in the Protos.PaymentRequest.

Throws:

PaymentRequestException

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.