Package 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.

  • Field Details

    • MIMETYPE_PAYMENTREQUEST

      public static final String MIMETYPE_PAYMENTREQUEST
      See Also:

    • MIMETYPE_PAYMENT

      public static final String MIMETYPE_PAYMENT
      See Also:

    • MIMETYPE_PAYMENTACK

      public static final String MIMETYPE_PAYMENTACK
      See Also:

    • PAYMENT_PROTOCOL_ID_MAINNET

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

    • PAYMENT_PROTOCOL_ID_TESTNET

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

    • PAYMENT_PROTOCOL_ID_SIGNET

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

    • PAYMENT_PROTOCOL_ID_UNIT_TESTS

      public static final 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:

    • PAYMENT_PROTOCOL_ID_REGTEST

      public static final String PAYMENT_PROTOCOL_ID_REGTEST
      See Also:

  • Constructor Details

    • PaymentProtocol

      public PaymentProtocol()

  • Method Details

    • createPaymentRequest

      public static org.bitcoinj.protobuf.payments.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.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, List<org.bitcoinj.protobuf.payments.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.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

    • parsePaymentRequest

      public static PaymentSession parsePaymentRequest(org.bitcoinj.protobuf.payments.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(org.bitcoinj.protobuf.payments.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(org.bitcoinj.protobuf.payments.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 org.bitcoinj.protobuf.payments.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 org.bitcoinj.protobuf.payments.Protos.Payment createPaymentMessage(List<Transaction> transactions, @Nullable List<org.bitcoinj.protobuf.payments.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, 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 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.

    • createPayToAddressOutput

      public static org.bitcoinj.protobuf.payments.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.base.Coin, org.bitcoinj.base.Address, java.lang.String, java.lang.String, byte[]) and createPaymentMessage(java.util.List<org.bitcoinj.core.Transaction>, org.bitcoinj.base.Coin, org.bitcoinj.base.Address, java.lang.String, byte[]).
      Parameters:
      amount - amount to pay, or null
      address - address to pay to
      Returns:
      output

    • paramsFromPmtProtocolID

      @Nullable public static BitcoinNetworkParams paramsFromPmtProtocolID(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 String protocolIdFromParams(NetworkParameters params)