org.bitcoinj.protocols.payments

Class PaymentProtocol

java.lang.Object

org.bitcoinj.protocols.payments.PaymentProtocol

public class PaymentProtocol
extends Object

Utility methods and constants for working with BIP 70 aka the payment protocol. These are low level wrappers around the protocol buffers. If you're implementing a wallet app, look at PaymentSession for a higher level API that should simplify working with the protocol.

BIP 70 defines a binary, protobuf based protocol that runs directly between sender and receiver of funds. Payment protocol data does not flow over the Bitcoin P2P network or enter the block chain. It's instead for data that is only of interest to the parties involved but isn't otherwise needed for consensus.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PaymentProtocol.Ack Message returned by the merchant in response to a Payment message.
static class	PaymentProtocol.Output Value object to hold amount/script pairs.
static class	PaymentProtocol.PkiVerificationData Information about the X.509 signature's issuer and subject.

Field Summary

Fields

Modifier and Type	Field and Description
static String	MIMETYPE_PAYMENT
static String	MIMETYPE_PAYMENTACK
static String	MIMETYPE_PAYMENTREQUEST

Constructor Summary

Constructors

Constructor and Description
PaymentProtocol()

Method Summary

Modifier and Type	Method and Description
static Protos.PaymentACK	createPaymentAck(Protos.Payment paymentMessage, String memo) Create a payment ack.
static Protos.Payment	createPaymentMessage(List<Transaction> transactions, Coin refundAmount, Address refundAddress, String memo, byte[] merchantData) Create a payment message with one standard pay to address output.
static Protos.Payment	createPaymentMessage(List<Transaction> transactions, List<Protos.Output> refundOutputs, String memo, byte[] merchantData) Create a payment message.
static Protos.PaymentRequest.Builder	createPaymentRequest(NetworkParameters params, Coin amount, Address toAddress, String memo, String paymentUrl, byte[] merchantData) Create a payment request with one standard pay to address output.
static Protos.PaymentRequest.Builder	createPaymentRequest(NetworkParameters params, List<Protos.Output> outputs, String memo, String paymentUrl, byte[] merchantData) Create a payment request.
static Protos.Output	createPayToAddressOutput(Coin amount, Address address) Create a standard pay to address output for usage in createPaymentRequest(org.bitcoinj.core.NetworkParameters, org.bitcoinj.core.Coin, org.bitcoinj.core.Address, java.lang.String, java.lang.String, byte[]) and createPaymentMessage(java.util.List<org.bitcoinj.core.Transaction>, org.bitcoinj.core.Coin, org.bitcoinj.core.Address, java.lang.String, byte[]).
static PaymentProtocol.Ack	parsePaymentAck(Protos.PaymentACK paymentAck) Parse payment ack into an object.
static PaymentSession	parsePaymentRequest(Protos.PaymentRequest paymentRequest) Parse a payment request.
static List<Transaction>	parseTransactionsFromPaymentMessage(NetworkParameters params, Protos.Payment paymentMessage) Parse transactions from payment message.
static void	signPaymentRequest(Protos.PaymentRequest.Builder paymentRequest, X509Certificate[] certificateChain, PrivateKey privateKey) Sign the provided payment request.
static PaymentProtocol.PkiVerificationData	verifyPaymentRequestPki(Protos.PaymentRequest paymentRequest, KeyStore trustStore) 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

MIMETYPE_PAYMENTREQUEST

public static final String MIMETYPE_PAYMENTREQUEST

See Also:

Constant Field Values

MIMETYPE_PAYMENT

public static final String MIMETYPE_PAYMENT

See Also:

Constant Field Values

MIMETYPE_PAYMENTACK

public static final String MIMETYPE_PAYMENTACK

See Also:

Constant Field Values

Constructor Detail

PaymentProtocol

public PaymentProtocol()

Method Detail

createPaymentRequest

public static Protos.PaymentRequest.Builder createPaymentRequest(NetworkParameters params,
                                                                 @Nullable
                                                                 Coin amount,
                                                                 Address toAddress,
                                                                 @Nullable
                                                                 String memo,
                                                                 @Nullable
                                                                 String paymentUrl,
                                                                 @Nullable
                                                                 byte[] merchantData)

Create a payment request with one standard pay to address output. You may want to sign the request using signPaymentRequest(org.bitcoin.protocols.payments.Protos.PaymentRequest.Builder, java.security.cert.X509Certificate[], java.security.PrivateKey). Use Protos.PaymentRequest.Builder#build to get the actual payment request.

Parameters:

params - network parameters

amount - amount of coins to request, or null

toAddress - address to request coins to

memo - arbitrary, user readable memo, or null if none

paymentUrl - URL to send payment message to, or null if none

merchantData - arbitrary merchant data, or null if none

Returns:

created payment request, in its builder form

createPaymentRequest

public static Protos.PaymentRequest.Builder createPaymentRequest(NetworkParameters params,
                                                                 List<Protos.Output> outputs,
                                                                 @Nullable
                                                                 String memo,
                                                                 @Nullable
                                                                 String paymentUrl,
                                                                 @Nullable
                                                                 byte[] merchantData)

Create a payment request. You may want to sign the request using signPaymentRequest(org.bitcoin.protocols.payments.Protos.PaymentRequest.Builder, java.security.cert.X509Certificate[], java.security.PrivateKey). Use Protos.PaymentRequest.Builder#build to get the actual payment request.

Parameters:

params - network parameters

outputs - list of outputs to request coins to

memo - arbitrary, user readable memo, or null if none

paymentUrl - URL to send payment message to, or null if none

merchantData - arbitrary merchant data, or null if none

Returns:

created payment request, in its builder form

parsePaymentRequest

public static PaymentSession parsePaymentRequest(Protos.PaymentRequest paymentRequest)
                                          throws PaymentProtocolException

Parse a payment request.

Parameters:

paymentRequest - payment request to parse

Returns:

instance of PaymentSession, used as a value object

Throws:

PaymentProtocolException

signPaymentRequest

public static void signPaymentRequest(Protos.PaymentRequest.Builder paymentRequest,
                                      X509Certificate[] certificateChain,
                                      PrivateKey privateKey)

Sign the provided payment request.

Parameters:

paymentRequest - Payment request to sign, in its builder form.

certificateChain - Certificate chain to send with the payment request, ordered from client certificate to root certificate. The root certificate itself may be omitted.

privateKey - The key to sign with. Must match the public key from the first certificate of the certificate chain.

verifyPaymentRequestPki

@Nullable
public static PaymentProtocol.PkiVerificationData verifyPaymentRequestPki(Protos.PaymentRequest paymentRequest,
                                                                                    KeyStore trustStore)
                                                                             throws PaymentProtocolException

Uses the provided PKI method to find the corresponding public key and verify the provided signature.

Parameters:

paymentRequest - Payment request to verify.

trustStore - KeyStore of trusted root certificate authorities.

Returns:

verification data, or null if no PKI method was specified in the Protos.PaymentRequest.

Throws:

PaymentProtocolException - if payment request could not be verified.

createPaymentMessage

public static Protos.Payment createPaymentMessage(List<Transaction> transactions,
                                                  @Nullable
                                                  Coin refundAmount,
                                                  @Nullable
                                                  Address refundAddress,
                                                  @Nullable
                                                  String memo,
                                                  @Nullable
                                                  byte[] merchantData)

Create a payment message with one standard pay to address output.

Parameters:

transactions - one or more transactions that satisfy the requested outputs.

refundAmount - amount of coins to request as a refund, or null if no refund.

refundAddress - address to refund coins to

memo - arbitrary, user readable memo, or null if none

merchantData - arbitrary merchant data, or null if none

Returns:

created payment message

createPaymentMessage

public static Protos.Payment createPaymentMessage(List<Transaction> transactions,
                                                  @Nullable
                                                  List<Protos.Output> refundOutputs,
                                                  @Nullable
                                                  String memo,
                                                  @Nullable
                                                  byte[] merchantData)

Create a payment message. This wraps up transaction data along with anything else useful for making a payment.

Parameters:

transactions - transactions to include with the payment message

refundOutputs - list of outputs to refund coins to, or null

memo - arbitrary, user readable memo, or null if none

merchantData - arbitrary merchant data, or null if none

Returns:

created payment message

parseTransactionsFromPaymentMessage

public static List<Transaction> parseTransactionsFromPaymentMessage(NetworkParameters params,
                                                                    Protos.Payment paymentMessage)

Parse transactions from payment message.

Parameters:

params - network parameters (needed for transaction deserialization)

paymentMessage - payment message to parse

Returns:

list of transactions

createPaymentAck

public static Protos.PaymentACK createPaymentAck(Protos.Payment paymentMessage,
                                                 @Nullable
                                                 String memo)

Create a payment ack.

Parameters:

paymentMessage - payment message to send with the ack

memo - arbitrary, user readable memo, or null if none

Returns:

created payment ack

parsePaymentAck

public static PaymentProtocol.Ack parsePaymentAck(Protos.PaymentACK paymentAck)

Parse payment ack into an object.

createPayToAddressOutput

public static Protos.Output createPayToAddressOutput(@Nullable
                                                     Coin amount,
                                                     Address address)

Create a standard pay to address output for usage in createPaymentRequest(org.bitcoinj.core.NetworkParameters, org.bitcoinj.core.Coin, org.bitcoinj.core.Address, java.lang.String, java.lang.String, byte[]) and createPaymentMessage(java.util.List<org.bitcoinj.core.Transaction>, org.bitcoinj.core.Coin, org.bitcoinj.core.Address, java.lang.String, byte[]).

Parameters:

amount - amount to pay, or null

address - address to pay to

Returns:

output