Package com.bitpay.sdk

Class Client

  • public class Client
extends java.lang.Object
    Version:
    5.2.2011 See bitpay.com/api for more information. date 03.11.2020
    Author:
    Antonio Buedo

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.util.ArrayList<java.lang.Object> _currenciesInfo  

    • Constructor Summary

      Constructors 
      Constructor Description
      Client​(java.lang.String environment, java.lang.String privateKey, Env.Tokens tokens, org.apache.http.HttpHost proxy)
      Constructor for use if the keys and SIN are managed by this library.
      Client​(java.lang.String configFilePath, org.apache.http.HttpHost proxy)
      Constructor for use if the keys and SIN are managed by this library.

    • Method Summary

      Modifier and Type Method Description
      void authorizeClient​(java.lang.String pairingCode)
      Authorize (pair) this client with the server using the specified pairing code.
      void BuildConfig​(java.lang.String privateKey, Env.Tokens tokens)
      Builds the configuration object
      PayoutBatch cancelPayoutBatch​(java.lang.String batchId)
      Cancel a BitPay Payout batch.
      java.lang.Boolean cancelRefund​(Invoice invoice, java.lang.String refundId)
      Cancel a previously submitted refund request on a BitPay invoice.
      java.lang.Boolean cancelRefund​(java.lang.String invoiceId, Refund refund)
      Cancel a previously submitted refund request on a BitPay invoice.
      java.lang.Boolean cancelRefund​(java.lang.String invoiceId, java.lang.String refundId)
      Cancel a previously submitted refund request on a BitPay invoice.
      Bill createBill​(Bill bill)
      Create a BitPay bill using the POS facade.
      Bill createBill​(Bill bill, java.lang.String facade, boolean signRequest)
      Create a BitPay Bill.
      Invoice createInvoice​(Invoice invoice)
      Create a BitPay invoice using the Merchant facade.
      Invoice createInvoice​(Invoice invoice, java.lang.String facade, java.lang.Boolean signRequest)
      Create a BitPay invoice.
      java.lang.Boolean createRefund​(Invoice invoice, java.lang.String refundEmail, java.lang.Double amount, java.lang.String currency)
      Create a refund for a BitPay invoice.
      java.lang.String deliverBill​(java.lang.String billId, java.lang.String billToken)
      Deliver a BitPay Bill.
      java.lang.String deliverBill​(java.lang.String billId, java.lang.String billToken, boolean signRequest)
      Deliver a BitPay Bill.
      org.apache.http.HttpResponse get​(java.lang.String uri)  
      org.apache.http.HttpResponse get​(java.lang.String uri, java.util.List<org.apache.http.message.BasicNameValuePair> parameters)  
      org.apache.http.HttpResponse get​(java.lang.String uri, java.util.List<org.apache.http.message.BasicNameValuePair> parameters, boolean signatureRequired)  
      java.lang.String getAccessToken​(java.lang.String key)
      Retrieve a token associated with a known resource.
      Bill getBill​(java.lang.String billId)
      Retrieve a BitPay bill by bill id using the public facade.
      Bill getBill​(java.lang.String billId, java.lang.String facade, boolean signRequest)
      Retrieve a BitPay bill by bill id using the specified facade.
      java.util.List<Bill> getBills()
      Retrieve a collection of BitPay bills.
      java.util.List<Bill> getBills​(java.lang.String status)
      Retrieve a collection of BitPay bills.
      void GetConfig()
      Loads the configuration file (JSON)
      static java.util.Map getCurrencyInfo​(java.lang.String currencyCode)
      Gets info for specific currency.
      Invoice getInvoice​(java.lang.String invoiceId)
      Retrieve a BitPay invoice by invoice id using the public facade.
      Invoice getInvoice​(java.lang.String invoiceId, java.lang.String facade, java.lang.Boolean signRequest)
      Retrieve a BitPay invoice by invoice id using the specified facade.
      java.util.List<Invoice> getInvoices​(java.lang.String dateStart, java.lang.String dateEnd, java.lang.String status, java.lang.String orderId, java.lang.Integer limit, java.lang.Integer offset)
      Retrieve a collection of BitPay invoices.
      Ledger getLedger​(java.lang.String currency, java.lang.String dateStart, java.lang.String dateEnd)
      Retrieve a list of ledgers by date range using the merchant facade.
      java.util.List<Ledger> getLedgers()
      Retrieve a list of ledgers using the merchant facade.
      PayoutBatch getPayoutBatch​(java.lang.String batchId)
      Retrieve a BitPay payout batch by batch id using.
      java.util.List<PayoutBatch> getPayoutBatches()
      Retrieve a collection of BitPay payout batches.
      java.util.List<PayoutBatch> getPayoutBatches​(java.lang.String status)
      Retrieve a collection of BitPay payout batches.
      PayoutRecipient getPayoutRecipient​(java.lang.String recipientId)
      Retrieve a BitPay payout recipient by batch id using.
      java.util.List<PayoutRecipient> getPayoutRecipients​(java.lang.String status, java.lang.Integer limit)
      Retrieve a collection of BitPay Payout Recipients.
      Rates getRates()
      Retrieve the exchange rate table maintained by BitPay.
      Refund getRefund​(Invoice invoice, java.lang.String refundId)
      Retrieve a previously made refund request on a BitPay invoice.
      java.util.List<Refund> getRefunds​(Invoice invoice)
      Retrieve all refund requests on a BitPay invoice.
      Settlement getSettlement​(java.lang.String settlementId)
      Retrieves a summary of the specified settlement.
      Settlement getSettlementReconciliationReport​(Settlement settlement)
      Gets a detailed reconciliation report of the activity within the settlement period.
      java.util.List<Settlement> getSettlements​(java.lang.String currency, java.lang.String dateStart, java.lang.String dateEnd, java.lang.String status, java.lang.Integer limit, java.lang.Integer offset)
      Retrieves settlement reports for the calling merchant filtered by query.
      java.lang.String GetTokenByFacade​(java.lang.String facade)
      Returns the token for the specified facade.
      org.apache.http.HttpResponse post​(java.lang.String uri, java.lang.String json)  
      org.apache.http.HttpResponse post​(java.lang.String uri, java.lang.String json, boolean signatureRequired)  
      java.lang.String requestClientAuthorization​(java.lang.String facade)
      Request a pairing code from the BitPay server.
      java.lang.String responseToJsonString​(org.apache.http.HttpResponse response)  
      void setLoggerLevel​(int loggerLevel)
      Sets the logger level of reporting.
      PayoutBatch submitPayoutBatch​(PayoutBatch batch)
      Submit a BitPay Payout batch.
      java.util.List<PayoutRecipient> submitPayoutRecipients​(PayoutRecipients recipients)
      Submit BitPay Payout Recipients.
      boolean tokenExist​(java.lang.String facade)
      Specified whether the client has authorization (a token) for the specified facade.
      org.apache.http.HttpResponse update​(java.lang.String uri, java.lang.String json)  
      Bill updateBill​(Bill bill, java.lang.String billId)
      Update a BitPay Bill.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • _currenciesInfo

        public static java.util.ArrayList<java.lang.Object> _currenciesInfo

    • Constructor Detail

      • Client

        public Client​(java.lang.String environment,
              java.lang.String privateKey,
              Env.Tokens tokens,
              org.apache.http.HttpHost proxy)
       throws BitPayException
        Constructor for use if the keys and SIN are managed by this library.
        Parameters:
        environment - Target environment. Options: Env.Test / Env.Prod
        privateKey - The full path to the securely located private key or the HEX key value.
        tokens - Env.Tokens containing the available tokens.
        proxy - HttpHost Optional Proxy setting (set to NULL to ignore)
        Throws:
        BitPayException - BitPayException class

      • Client

        public Client​(java.lang.String configFilePath,
              org.apache.http.HttpHost proxy)
       throws BitPayException
        Constructor for use if the keys and SIN are managed by this library.
        Parameters:
        configFilePath - The path to the configuration file.
        proxy - HttpHost Optional Proxy setting (set to NULL to ignore)
        Throws:
        BitPayException - BitPayException class

    • Method Detail

      • authorizeClient

        public void authorizeClient​(java.lang.String pairingCode)
                     throws BitPayException
        Authorize (pair) this client with the server using the specified pairing code.
        Parameters:
        pairingCode - A code obtained from the server; typically from bitpay.com/api-tokens.
        Throws:
        BitPayException - BitPayException class

      • requestClientAuthorization

        public java.lang.String requestClientAuthorization​(java.lang.String facade)
                                            throws BitPayException
        Request a pairing code from the BitPay server.
        Parameters:
        facade - Defines the level of API access being requested
        Returns:
        A pairing code for claim at https://bitpay.com/dashboard/merchant/api-tokens.
        Throws:
        BitPayException - BitPayException class

      • tokenExist

        public boolean tokenExist​(java.lang.String facade)
        Specified whether the client has authorization (a token) for the specified facade.
        Parameters:
        facade - The facade name for which authorization is tested.
        Returns:
        True if this client is authorized, false otherwise.

      • GetTokenByFacade

        public java.lang.String GetTokenByFacade​(java.lang.String facade)
        Returns the token for the specified facade.
        Parameters:
        facade - The facade name for which the token is requested.
        Returns:
        The token for the given facade.

      • createInvoice

        public Invoice createInvoice​(Invoice invoice)
                      throws InvoiceCreationException
        Create a BitPay invoice using the Merchant facade.
        Parameters:
        invoice - An Invoice object with request parameters defined.
        Returns:
        A BitPay generated Invoice object.
        Throws:
        InvoiceCreationException - InvoiceCreationException class

      • createInvoice

        public Invoice createInvoice​(Invoice invoice,
                             java.lang.String facade,
                             java.lang.Boolean signRequest)
                      throws BitPayException,
                             InvoiceCreationException
        Create a BitPay invoice.
        Parameters:
        invoice - An Invoice object with request parameters defined.
        facade - The facade used to create it.
        signRequest - Signed request.
        Returns:
        A BitPay generated Invoice object.
        Throws:
        BitPayException - BitPayException class
        InvoiceCreationException - InvoiceCreationException class

      • getInvoice

        public Invoice getInvoice​(java.lang.String invoiceId)
                   throws InvoiceQueryException
        Retrieve a BitPay invoice by invoice id using the public facade.
        Parameters:
        invoiceId - The id of the invoice to retrieve.
        Returns:
        A BitPay Invoice object.
        Throws:
        InvoiceQueryException - InvoiceQueryException class

      • getInvoice

        public Invoice getInvoice​(java.lang.String invoiceId,
                          java.lang.String facade,
                          java.lang.Boolean signRequest)
                   throws BitPayException,
                          InvoiceQueryException
        Retrieve a BitPay invoice by invoice id using the specified facade. The client must have been previously authorized for the specified facade (the public facade requires no authorization).
        Parameters:
        invoiceId - The id of the invoice to retrieve.
        facade - The facade used to create it.
        signRequest - Signed request.
        Returns:
        A BitPay Invoice object.
        Throws:
        BitPayException - BitPayException class
        InvoiceQueryException - InvoiceQueryException class

      • getInvoices

        public java.util.List<Invoice> getInvoices​(java.lang.String dateStart,
                                           java.lang.String dateEnd,
                                           java.lang.String status,
                                           java.lang.String orderId,
                                           java.lang.Integer limit,
                                           java.lang.Integer offset)
                                    throws BitPayException,
                                           InvoiceQueryException
        Retrieve a collection of BitPay invoices.
        Parameters:
        dateStart - The first date for the query filter.
        dateEnd - The last date for the query filter.
        status - The invoice status you want to query on.
        orderId - The optional order id specified at time of invoice creation.
        limit - Maximum results that the query will return (useful for paging results).
        offset - Number of results to offset (ex. skip 10 will give you results starting with the 11th
        Returns:
        A list of BitPay Invoice objects.
        Throws:
        BitPayException - BitPayException class
        InvoiceQueryException - InvoiceQueryException class

      • createRefund

        public java.lang.Boolean createRefund​(Invoice invoice,
                                      java.lang.String refundEmail,
                                      java.lang.Double amount,
                                      java.lang.String currency)
                               throws RefundCreationException
        Create a refund for a BitPay invoice.
        Parameters:
        invoice - A BitPay invoice object for which a refund request should be made. Must have been obtained using the merchant facade.
        refundEmail - The email of the buyer to which the refund email will be sent
        amount - The amount of money to refund. If zero then a request for 100% of the invoice value is created.
        currency - The three digit currency code specifying the exchange rate to use when calculating the refund bitcoin amount. If this value is "BTC" then no exchange rate calculation is performed.
        Returns:
        True if the refund was successfully canceled, false otherwise.
        Throws:
        RefundCreationException - RefundCreationException class

      • getRefunds

        public java.util.List<Refund> getRefunds​(Invoice invoice)
                                  throws RefundQueryException
        Retrieve all refund requests on a BitPay invoice.
        Parameters:
        invoice - The BitPay invoice object having the associated refunds.
        Returns:
        A BitPay invoice object with the associated Refund objects updated.
        Throws:
        RefundQueryException - RefundQueryException class

      • getRefund

        public Refund getRefund​(Invoice invoice,
                        java.lang.String refundId)
                 throws RefundQueryException
        Retrieve a previously made refund request on a BitPay invoice.
        Parameters:
        invoice - The BitPay invoice having the associated refund.
        refundId - The refund id for the refund to be updated with new status.
        Returns:
        A BitPay invoice object with the associated Refund object updated.
        Throws:
        RefundQueryException - RefundQueryException class

      • cancelRefund

        public java.lang.Boolean cancelRefund​(java.lang.String invoiceId,
                                      java.lang.String refundId)
                               throws RefundCancellationException
        Cancel a previously submitted refund request on a BitPay invoice.
        Parameters:
        invoiceId - The BitPay invoiceId having the associated refund to be canceled.
        refundId - The refund id for the refund to be canceled.
        Returns:
        True if the refund was successfully canceled, false otherwise.
        Throws:
        RefundCancellationException - RefundCancellationException class

      • cancelRefund

        public java.lang.Boolean cancelRefund​(Invoice invoice,
                                      java.lang.String refundId)
                               throws RefundCancellationException
        Cancel a previously submitted refund request on a BitPay invoice.
        Parameters:
        invoice - The BitPay invoice having the associated refund to be canceled. Must have been obtained using the merchant facade.
        refundId - The refund Id for the refund to be canceled.
        Returns:
        True if the refund was successfully canceled, false otherwise.
        Throws:
        RefundCancellationException - RefundCancellationException class

      • cancelRefund

        public java.lang.Boolean cancelRefund​(java.lang.String invoiceId,
                                      Refund refund)
                               throws RefundCancellationException
        Cancel a previously submitted refund request on a BitPay invoice.
        Parameters:
        invoiceId - The BitPay invoice Id having the associated refund to be canceled.
        refund - The BitPay refund for the refund to be canceled.
        Returns:
        True if the refund was successfully canceled, false otherwise.
        Throws:
        RefundCancellationException - RefundCancellationException class

      • createBill

        public Bill createBill​(Bill bill)
                throws BillCreationException
        Create a BitPay bill using the POS facade.
        Parameters:
        bill - An Bill object with request parameters defined.
        Returns:
        A BitPay generated Bill object.
        Throws:
        BillCreationException - BillCreationException class

      • createBill

        public Bill createBill​(Bill bill,
                       java.lang.String facade,
                       boolean signRequest)
                throws BitPayException,
                       BillCreationException
        Create a BitPay Bill.
        Parameters:
        bill - A Bill object with request parameters defined.
        facade - The facade used to create it.
        signRequest - Signed request.
        Returns:
        A BitPay generated Bill object.
        Throws:
        BitPayException - BitPayException class
        BillCreationException - BillCreationException class

      • getBill

        public Bill getBill​(java.lang.String billId)
             throws BillQueryException
        Retrieve a BitPay bill by bill id using the public facade.
        Parameters:
        billId - The id of the bill to retrieve.
        Returns:
        A BitPay Bill object.
        Throws:
        BillQueryException - BillQueryException class

      • getBill

        public Bill getBill​(java.lang.String billId,
                    java.lang.String facade,
                    boolean signRequest)
             throws BitPayException,
                    BillQueryException
        Retrieve a BitPay bill by bill id using the specified facade.
        Parameters:
        billId - The id of the bill to retrieve.
        facade - The facade used to retrieve it.
        signRequest - Signed request.
        Returns:
        A BitPay Bill object.
        Throws:
        BitPayException - BitPayException class
        BillQueryException - BillQueryException class

      • updateBill

        public Bill updateBill​(Bill bill,
                       java.lang.String billId)
                throws BitPayException,
                       BillUpdateException
        Update a BitPay Bill.
        Parameters:
        bill - A Bill object with the parameters to update defined.
        billId - The Id of the Bill to udpate.
        Returns:
        An updated Bill object.
        Throws:
        BitPayException - BitPayException class
        BillUpdateException - BillUpdateException class

      • deliverBill

        public java.lang.String deliverBill​(java.lang.String billId,
                                    java.lang.String billToken)
                             throws BillDeliveryException
        Deliver a BitPay Bill.
        Parameters:
        billId - The id of the requested bill.
        billToken - The token of the requested bill.
        Returns:
        A response status returned from the API.
        Throws:
        BillDeliveryException - BillDeliveryException class

      • deliverBill

        public java.lang.String deliverBill​(java.lang.String billId,
                                    java.lang.String billToken,
                                    boolean signRequest)
                             throws BillDeliveryException
        Deliver a BitPay Bill.
        Parameters:
        billId - The id of the requested bill.
        billToken - The token of the requested bill.
        signRequest - Allow unsigned request
        Returns:
        A response status returned from the API.
        Throws:
        BillDeliveryException - BillDeliveryException class

      • getRates

        public Rates getRates()
               throws RateQueryException
        Retrieve the exchange rate table maintained by BitPay. See https://bitpay.com/bitcoin-exchange-rates.
        Returns:
        A Rates object populated with the BitPay exchange rate table.
        Throws:
        RateQueryException - RateQueryException class

      • getLedger

        public Ledger getLedger​(java.lang.String currency,
                        java.lang.String dateStart,
                        java.lang.String dateEnd)
                 throws BitPayException,
                        LedgerQueryException
        Retrieve a list of ledgers by date range using the merchant facade.
        Parameters:
        currency - The three digit currency string for the ledger to retrieve.
        dateStart - The first date for the query filter.
        dateEnd - The last date for the query filter.
        Returns:
        A Ledger object populated with the BitPay ledger entries list.
        Throws:
        BitPayException - BitPayException class
        LedgerQueryException - LedgerQueryException class

      • getPayoutRecipients

        public java.util.List<PayoutRecipient> getPayoutRecipients​(java.lang.String status,
                                                           java.lang.Integer limit)
                                                    throws BitPayException,
                                                           PayoutQueryException
        Retrieve a collection of BitPay Payout Recipients.
        Parameters:
        status - String|null The recipient status you want to query on.
        limit - int|null Maximum results that the query will return (useful for paging results). result).
        Returns:
        array A list of BitPayRecipient objects.
        Throws:
        BitPayException - BitPayException class
        PayoutQueryException - PayoutQueryException class

      • getPayoutRecipient

        public PayoutRecipient getPayoutRecipient​(java.lang.String recipientId)
                                   throws BitPayException,
                                          PayoutQueryException
        Retrieve a BitPay payout recipient by batch id using. The client must have been previously authorized for the payroll facade.
        Parameters:
        recipientId - String The id of the recipient to retrieve.
        Returns:
        PayoutRecipient A BitPay PayoutRecipient object.
        Throws:
        BitPayException - BitPayException class
        PayoutQueryException - PayoutQueryException class

      • getPayoutBatch

        public PayoutBatch getPayoutBatch​(java.lang.String batchId)
                           throws BitPayException,
                                  PayoutQueryException
        Retrieve a BitPay payout batch by batch id using. The client must have been previously authorized for the payroll facade.
        Parameters:
        batchId - The id of the batch to retrieve.
        Returns:
        A BitPay PayoutBatch object.
        Throws:
        BitPayException - BitPayException class
        PayoutQueryException - PayoutQueryException class

      • cancelPayoutBatch

        public PayoutBatch cancelPayoutBatch​(java.lang.String batchId)
                              throws PayoutCancellationException
        Cancel a BitPay Payout batch.
        Parameters:
        batchId - The id of the batch to cancel.
        Returns:
        A BitPay generated PayoutBatch object.
        Throws:
        PayoutCancellationException - PayoutCancellationException class

      • getSettlements

        public java.util.List<Settlement> getSettlements​(java.lang.String currency,
                                                 java.lang.String dateStart,
                                                 java.lang.String dateEnd,
                                                 java.lang.String status,
                                                 java.lang.Integer limit,
                                                 java.lang.Integer offset)
                                          throws BitPayException,
                                                 SettlementQueryException
        Retrieves settlement reports for the calling merchant filtered by query. The `limit` and `offset` parameters specify pages for large query sets.
        Parameters:
        currency - The three digit currency string for the ledger to retrieve.
        dateStart - The start date for the query.
        dateEnd - The end date for the query.
        status - Can be `processing`, `completed`, or `failed`.
        limit - Maximum number of settlements to retrieve.
        offset - Offset for paging.
        Returns:
        A list of BitPay Settlement objects.
        Throws:
        BitPayException - BitPayException class
        SettlementQueryException - SettlementQueryException class

      • getSettlementReconciliationReport

        public Settlement getSettlementReconciliationReport​(Settlement settlement)
                                             throws SettlementQueryException
        Gets a detailed reconciliation report of the activity within the settlement period.
        Parameters:
        settlement - Settlement to generate report for.
        Returns:
        A detailed BitPay Settlement object.
        Throws:
        SettlementQueryException - SettlementQueryException class

      • getAccessToken

        public java.lang.String getAccessToken​(java.lang.String key)
                                throws BitPayException
        Retrieve a token associated with a known resource. The token is used to access other related resources.
        Parameters:
        key - The identifier for the desired resource.
        Returns:
        The token associated with resource.
        Throws:
        BitPayException - BitPayException class

      • get

        public org.apache.http.HttpResponse get​(java.lang.String uri,
                                        java.util.List<org.apache.http.message.BasicNameValuePair> parameters)
                                 throws BitPayException
        Throws:
        BitPayException

      • get

        public org.apache.http.HttpResponse get​(java.lang.String uri,
                                        java.util.List<org.apache.http.message.BasicNameValuePair> parameters,
                                        boolean signatureRequired)
                                 throws BitPayException
        Throws:
        BitPayException

      • post

        public org.apache.http.HttpResponse post​(java.lang.String uri,
                                         java.lang.String json,
                                         boolean signatureRequired)
                                  throws BitPayException
        Throws:
        BitPayException

      • update

        public org.apache.http.HttpResponse update​(java.lang.String uri,
                                           java.lang.String json)
                                    throws BitPayException
        Throws:
        BitPayException

      • responseToJsonString

        public java.lang.String responseToJsonString​(org.apache.http.HttpResponse response)
                                      throws BitPayException
        Throws:
        BitPayException

      • BuildConfig

        public void BuildConfig​(java.lang.String privateKey,
                        Env.Tokens tokens)
                 throws BitPayException
        Builds the configuration object
        Parameters:
        privateKey - The full path to the securely located private key.
        tokens - Env.Tokens object containing the BitPay's API tokens.
        Throws:
        BitPayException - BitPayException class

      • getCurrencyInfo

        public static java.util.Map getCurrencyInfo​(java.lang.String currencyCode)
        Gets info for specific currency.
        Parameters:
        currencyCode - String Currency code for which the info will be retrieved.
        Returns:
        Map|null

      • setLoggerLevel

        public void setLoggerLevel​(int loggerLevel)
        Sets the logger level of reporting.
        Parameters:
        loggerLevel - int BitPayLogger constant (OFF, INFO, WARN, ERR, DEBUG)