Package org.bitcoinj.protocols.payments

Class PaymentProtocol

  • public class PaymentProtocol
extends java.lang.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.

    • Field Detail

      • MIMETYPE_PAYMENTREQUEST

        public static final java.lang.String MIMETYPE_PAYMENTREQUEST
        See Also:
        Constant Field Values

      • MIMETYPE_PAYMENT

        public static final java.lang.String MIMETYPE_PAYMENT
        See Also:
        Constant Field Values

      • MIMETYPE_PAYMENTACK

        public static final java.lang.String MIMETYPE_PAYMENTACK
        See Also:
        Constant Field Values

      • PAYMENT_PROTOCOL_ID_MAINNET

        public static final java.lang.String PAYMENT_PROTOCOL_ID_MAINNET
        The string used by the payment protocol to represent the main net.
        See Also:
        Constant Field Values

      • PAYMENT_PROTOCOL_ID_TESTNET

        public static final java.lang.String PAYMENT_PROTOCOL_ID_TESTNET
        The string used by the payment protocol to represent the test net.
        See Also:
        Constant Field Values

      • PAYMENT_PROTOCOL_ID_SIGNET

        public static final java.lang.String PAYMENT_PROTOCOL_ID_SIGNET
        The string used by the payment protocol to represent signet (note that this is non-standard).
        See Also:
        Constant Field Values

      • PAYMENT_PROTOCOL_ID_UNIT_TESTS

        public static final java.lang.String PAYMENT_PROTOCOL_ID_UNIT_TESTS
        The string used by the payment protocol to represent unit testing (note that this is non-standard).
        See Also:
        Constant Field Values

      • PAYMENT_PROTOCOL_ID_REGTEST

        public static final java.lang.String PAYMENT_PROTOCOL_ID_REGTEST
        See Also:
        Constant Field Values

    • Constructor Detail

      • PaymentProtocol

        public PaymentProtocol()

    • Method Detail

      • createPaymentRequest

        public static org.bitcoinj.protobuf.payments.Protos.PaymentRequest.Builder createPaymentRequest​(NetworkParameters params,
                                                                                                @Nullable
                                                                                                Coin amount,
                                                                                                Address toAddress,
                                                                                                @Nullable
                                                                                                java.lang.String memo,
                                                                                                @Nullable
                                                                                                java.lang.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.bitcoinj.protobuf.payments.Protos.PaymentRequest.Builder, java.security.cert.X509Certificate[], java.security.PrivateKey). Use GeneratedMessageLite.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 org.bitcoinj.protobuf.payments.Protos.PaymentRequest.Builder createPaymentRequest​(NetworkParameters params,
                                                                                                java.util.List<org.bitcoinj.protobuf.payments.Protos.Output> outputs,
                                                                                                @Nullable
                                                                                                java.lang.String memo,
                                                                                                @Nullable
                                                                                                java.lang.String paymentUrl,
                                                                                                @Nullable
                                                                                                byte[] merchantData)
        Create a payment request. You may want to sign the request using signPaymentRequest(org.bitcoinj.protobuf.payments.Protos.PaymentRequest.Builder, java.security.cert.X509Certificate[], java.security.PrivateKey). Use GeneratedMessageLite.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

      • signPaymentRequest

        public static void signPaymentRequest​(org.bitcoinj.protobuf.payments.Protos.PaymentRequest.Builder paymentRequest,
                                      java.security.cert.X509Certificate[] certificateChain,
                                      java.security.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​(org.bitcoinj.protobuf.payments.Protos.PaymentRequest paymentRequest,
                                                                          java.security.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 org.bitcoinj.protobuf.payments.Protos.Payment createPaymentMessage​(java.util.List<Transaction> transactions,
                                                                                 @Nullable
                                                                                 Coin refundAmount,
                                                                                 @Nullable
                                                                                 Address refundAddress,
                                                                                 @Nullable
                                                                                 java.lang.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 org.bitcoinj.protobuf.payments.Protos.Payment createPaymentMessage​(java.util.List<Transaction> transactions,
                                                                                 @Nullable
                                                                                 java.util.List<org.bitcoinj.protobuf.payments.Protos.Output> refundOutputs,
                                                                                 @Nullable
                                                                                 java.lang.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 java.util.List<Transaction> parseTransactionsFromPaymentMessage​(NetworkParameters params,
                                                                              org.bitcoinj.protobuf.payments.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 org.bitcoinj.protobuf.payments.Protos.PaymentACK createPaymentAck​(org.bitcoinj.protobuf.payments.Protos.Payment paymentMessage,
                                                                                @Nullable
                                                                                java.lang.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​(org.bitcoinj.protobuf.payments.Protos.PaymentACK paymentAck)
        Parse payment ack into an object.

      • paramsFromPmtProtocolID

        @Nullable
public static BitcoinNetworkParams paramsFromPmtProtocolID​(java.lang.String pmtProtocolId)
        Return network parameters for a paymentProtocol ID string
        Parameters:
        pmtProtocolId - paymentProtocol ID string
        Returns:
        network parameters for the given string paymentProtocolID or NULL if not recognized

      • protocolIdFromParams

        public static java.lang.String protocolIdFromParams​(NetworkParameters params)