Cryptopay Java Library

Cryptopay - the official Java client for the Cryptopay API.

Cryptopay is a payment gateway and business wallet that allows merchants to automate the processes of accepting cryptocurrency payments and payouts from their customers, as well as making currency exchange transactions and receiving data on the transaction history and account balance statuses for reporting.

For more information, please visit Cryptopay API docs.

Table of contents

• Installation
• Configuration
• Usage
  • Complete examples
  • Accounts
  • Channels
  • CoinWithdrawals
  • Coins
  • Customers
  • ExchangeTransfers
  • Invoices
  • Rates
  • Subscriptions
  • Transactions
• Callbacks
• Development
  • Local build
  • Unit tests
  • Coding conventions
• Contributing
• License

Installation

For Maven, add the following dependency to your pom.xml:

<dependency>
<groupId>me.cryptopay</groupId>
<artifactId>cryptopay-java</artifactId>
<version>3.0.0</version>
</dependency>

For Gradle, add the following dependency to your build.gradle:

implementation group: 'me.cryptopay', name: 'cryptopay-java', version: '3.0.0'

Requirements

• Java 11+

Configuration

Create API credentials

Learn mode about API credentials at Developers guide.

Configure library

importme.cryptopay.Cryptopay;
Cryptopaycryptopay = Cryptopay.builder()
.apiUrl(Cryptopay.API_URL_SANDBOX)
.apiKey(System.getenv("CRYPTOPAY_API_KEY"))
.apiSecret(System.getenv("CRYPTOPAY_API_SECRET"))
.callbackSecret(System.getenv("CRYPTOPAY_CALLBACK_SECRET"))
.build()

Usage

Complete examples

Examples of usage of the library can be found here.

Accounts

List accounts

AccountListResultresult = cryptopay.accounts().list().execute();

List account transactions

UUIDaccountId = UUID.fromString("31804390-d44e-49e9-8698-ca781e0eb806");
TransactionListResultresult = cryptopay.accounts().listTransactions(accountId).execute();

Channels

A channel is a static cryptocurrency address that may be assigned to each one of your customers.

Channels API docs

Create a channel

ChannelParamschannelParams = newChannelParams();
channelParams.setName("Channel name");
channelParams.setPayCurrency("ETH");
channelParams.setReceiverCurrency("BTC");
ChannelResultresult = cryptopay.channels().create(channelParams).execute();

List channels

ChannelListResultresult = cryptopay.channels().list().execute();

List channel payments

UUIDchannelId = UUID.fromString("15d0bb11-1e9f-4295-bec5-abd9d5a906a1");
ChannelPaymentListResultresult = cryptopay.channels().listPayments(channelId).execute();

Retrieve a channel

UUIDchannelId = UUID.fromString("15d0bb11-1e9f-4295-bec5-abd9d5a906a1");
ChannelResultresult = cryptopay.channels().retrieve(channelId).execute();

Retrieve a channel by custom id

StringcustomId = "CHANNEL-123";
ChannelResultresult = cryptopay.channels().retrieveByCustomId(customId).execute();

Retrieve a channel payment

UUIDchannelId = UUID.fromString("15d0bb11-1e9f-4295-bec5-abd9d5a906a1");
UUIDchannelPaymentId = UUID.fromString("704291ec-0b90-4118-89aa-0c9681c3213c");
ChannelPaymentResultresult = cryptopay.channels().retrievePayment(channelId, channelPaymentId).execute();

Update a channel

UUIDchannelId = UUID.fromString("15d0bb11-1e9f-4295-bec5-abd9d5a906a1");
ChannelUpdateParamschannelUpdateParams = newChannelUpdateParams();
channelUpdateParams.setStatus(ChannelStatus.DISABLED);
ChannelResultresult = cryptopay.channels().update(channelId, channelUpdateParams).execute();

CoinWithdrawals

In addition to accepting payments through the Cryptopay payment gateway, it is also possible to make payments to your customers in any of the cryptocurrency currently supported by Cryptopay. In Cryptopay, these payments are called “Coin Withdrawal”. The process of requesting coin withdrawal is almost the same for a customer in Cashier as the process of making a deposit with one exception - the customer will need to specify the address of the wallet he wants to send the cryptocurrency to.

Coin withdrawals API docs

Commit a withdrawal

CoinWithdrawalParamscoinWithdrawalParams = newCoinWithdrawalParams();
coinWithdrawalParams.setAddress("2Mz3bcjSVHG8uQJpNjmCxp24VdTjwaqmFcJ");
coinWithdrawalParams.setChargedAmount(BigDecimal.valueOf(100.0));
coinWithdrawalParams.setChargedCurrency("EUR");
coinWithdrawalParams.setReceivedCurrency("BTC");
coinWithdrawalParams.setForceCommit(false);
CoinWithdrawalcoinWithdrawal = cryptopay.coinWithdrawals().create(coinWithdrawalParams).execute().getData();
CoinWithdrawalResultresult = cryptopay.coinWithdrawals().commit(coinWithdrawal.getId()).execute();

Create a withdrawal

Documentation

CoinWithdrawalParamscoinWithdrawalParams = newCoinWithdrawalParams();
coinWithdrawalParams.setAddress("2Mz3bcjSVHG8uQJpNjmCxp24VdTjwaqmFcJ");
coinWithdrawalParams.setChargedAmount(BigDecimal.valueOf(100.0));
coinWithdrawalParams.setChargedCurrency("EUR");
coinWithdrawalParams.setReceivedCurrency("BTC");
coinWithdrawalParams.setForceCommit(false);
CoinWithdrawalResultresult = cryptopay.coinWithdrawals().create(coinWithdrawalParams).execute();

List withdrawals

CoinWithdrawalListResultresult = cryptopay.coinWithdrawals().list().execute();

List network fees

NetworkFeeListResultresult = cryptopay.coinWithdrawals().listNetworkFees().execute();

Retrieve a withdrawal

UUIDcoinWithdrawalId = UUID.fromString("3cf9d1c4-6191-4826-8cae-2c717810c7e9");
CoinWithdrawalResultresult = cryptopay.coinWithdrawals().retrieve(coinWithdrawalId).execute();

Retrieve a withdrawal by custom id

StringcustomId = "PAYMENT-123";
CoinWithdrawalResultresult = cryptopay.coinWithdrawals().retrieveByCustomId(customId).execute();

Coins

List supported coins

CoinListResultresult = cryptopay.coins().list().execute();

Customers

Customer objects allow you to reject High-Risk transactions automatically, and to track multiple transactions, that are associated with the same customer.

Create a customer

CustomerAddresscustomerAddress = newCustomerAddress();
customerAddress.setAddress("2NGPwyaRTrKpjf9njHQDfXAReb2iwbYkZrg");
customerAddress.setCurrency("BTC");
customerAddress.setNetwork("bitcoin");
CustomerParamscustomerParams = newCustomerParams();
customerParams.setId("CUSTOMER-123");
customerParams.setCurrency("BTC");
customerParams.setAddresses(List.of(customerAddress));
CustomerResultresult = cryptopay.customers().create(customerParams).execute();

List customers

CustomerListResultresult = cryptopay.customers().list().execute();

Retrieve a customer

StringcustomerId = "CUSTOMER-123";
CustomerResultresult = cryptopay.customers().retrieve(customerId).execute();

Update a customer

StringcustomerId = "CUSTOMER-123";
CustomerAddresscustomerAddress = newCustomerAddress();
customerAddress.setAddress("2N9wPGx67zdSeAbXi15qHgoZ9Hb9Uxhd2uQ");
customerAddress.setCurrency("BTC");
customerAddress.setNetwork("bitcoin");
CustomerUpdateParamscustomerUpdateParams = newCustomerUpdateParams();
customerUpdateParams.setAddresses(List.of(customerAddress));
CustomerResultresult = cryptopay.customers().update(customerId, customerUpdateParams).execute();

ExchangeTransfers

Commit an exchange transfer

ExchangeTransferParamsexchangeTransferParams = newExchangeTransferParams();
exchangeTransferParams.setChargedAmount(BigDecimal.valueOf(10));
exchangeTransferParams.setChargedCurrency("EUR");
exchangeTransferParams.setReceivedCurrency("BTC");
exchangeTransferParams.setForceCommit(false);
ExchangeTransferexchangeTransfer = cryptopay.exchangeTransfers().create(exchangeTransferParams)
.execute()
.getData();
ExchangeTransferResultresult = cryptopay.exchangeTransfers().commit(exchangeTransfer.getId()).execute();

Create an exchange transfer

ExchangeTransferParamsexchangeTransferParams = newExchangeTransferParams();
exchangeTransferParams.setChargedAmount(BigDecimal.valueOf(10));
exchangeTransferParams.setChargedCurrency("EUR");
exchangeTransferParams.setReceivedCurrency("BTC");
exchangeTransferParams.setForceCommit(false);
ExchangeTransferResultresult = cryptopay.exchangeTransfers().create(exchangeTransferParams).execute();

Retrieve an exchange transfer

UUIDexchangeTransferId = UUID.fromString("2c090f99-7cc1-40da-9bca-7caa57b4ebfb");
ExchangeTransferResultresult = cryptopay.exchangeTransfers().retrieve(exchangeTransferId).execute();

Invoices

An invoice is a request for a cryptocurrency payment which contains a unique BTC, LTC, ETH or XRP address and the amount that has to be paid while the invoice is valid.

Invoices API docs

Commit invoice recalculation

UUIDinvoiceId = UUID.fromString("2738682a-11ff-4013-8380-6a70df995ea9");
InvoiceRecalculationParamsinvoiceRecalculationParams = newInvoiceRecalculationParams();
invoiceRecalculationParams.setForceCommit(false);
InvoiceRecalculationrecalculation = cryptopay.invoices()
.createRecalculation(invoiceId, invoiceRecalculationParams)
.execute()
.getData();
InvoiceRecalculationResultresult = cryptopay.invoices()
.commitRecalculation(invoiceId, recalculation.getId())
.execute();

Create an invoice

InvoiceParamsinvoiceParams = newInvoiceParams();
invoiceParams.setCustomId("PAYMENT-123");
invoiceParams.setPayCurrency("BTC");
invoiceParams.setPriceAmount(BigDecimal.valueOf(100.0));
invoiceParams.setPriceCurrency("EUR");
invoiceParams.setMetadata(Map.of("custom-key", "custom-value"));
invoiceParams.setSuccessRedirectUrl(URI.create("https://success.example.com"));
invoiceParams.setUnsuccessRedirectUrl(URI.create("https://unsuccess.example.com"));
InvoiceResultresult = cryptopay.invoices().create(invoiceParams).execute();

Create invoice recalculation

UUIDinvoiceId = UUID.fromString("2738682a-11ff-4013-8380-6a70df995ea9");
InvoiceRecalculationParamsinvoiceRecalculationParams = newInvoiceRecalculationParams();
invoiceRecalculationParams.setForceCommit(false);
InvoiceRecalculationResultresult = cryptopay.invoices()
.createRecalculation(invoiceId, invoiceRecalculationParams)
.execute();

Create invoice refund

UUIDinvoiceId = UUID.fromString("7e274430-e20f-4321-8748-20824287ae44");
InvoiceRefundResultresult = cryptopay.invoices().createRefund(invoiceId).execute();

List invoices

InvoiceListResultresult = cryptopay.invoices().list().execute();

List invoice refunds

UUIDinvoiceId = UUID.fromString("7e274430-e20f-4321-8748-20824287ae44");
InvoiceRefundListResultresult = cryptopay.invoices().listRefunds(invoiceId).execute();

Retrieve an invoice

UUIDinvoiceId = UUID.fromString("c8233d57-78c8-4c36-b35e-940ae9067c78");
InvoiceResultresult = cryptopay.invoices().retrieve(invoiceId).execute();

Retrieve an invoice by custom_id

StringcustomId = "PAYMENT-123";
InvoiceResultresult = cryptopay.invoices().retrieveByCustomId("PAYMENT-123").execute();

Rates

Retrieve all rates

RatesResultresult = cryptopay.rates().all().execute();

Retrieve a pair rate

StringbaseCurrency = "BTC";
StringquoteCurrency = "EUR";
RateResultresult = cryptopay.rates().retrieve(baseCurrency, quoteCurrency).execute();

Subscriptions

Cancel a subscription

UUIDsubscriptionId = UUID.fromString("64249ede-8969-4d5c-a042-806f9c3e7db3");
SubscriptionResultresult = cryptopay.subscriptions().cancel(subscriptionId).execute();

Create a subscription

SubscriptionParamssubscriptionParams = newSubscriptionParams();
subscriptionParams.setName("Subscription name");
subscriptionParams.setAmount(BigDecimal.valueOf(100.0));
subscriptionParams.setCurrency("EUR");
subscriptionParams.setPeriod(SubscriptionPeriod.MONTH);
subscriptionParams.setPeriodQuantity(3);
subscriptionParams.setPayerEmail("user@example.com");
subscriptionParams.setStartsAt(OffsetDateTime.now().plusWeeks(1));
SubscriptionResultresult = cryptopay.subscriptions().create(subscriptionParams).execute();

List subscriptions

SubscriptionListResultresult = cryptopay.subscriptions().list().execute();

Retrieve a subscription

UUIDsubscriptionId = UUID.fromString("64249ede-8969-4d5c-a042-806f9c3e7db3");
SubscriptionResultresult = cryptopay.subscriptions().retrieve(subscriptionId).execute();

Retrieve a subscription by custom_id

StringcustomId = "PAYMENT-123";
SubscriptionResultresult = cryptopay.subscriptions().retrieveByCustomId("PAYMENT-123").execute();

Transactions

Transactions API docs

List transactions

TransactionListResultresult = cryptopay.transactions()
.list()
.referenceType(TransactionReferenceType.INVOICE)
.execute();

Callbacks

Documentation

Every callback request contains a X-Cryptopay-Signature header which is needed to verify webhook body

Stringbody = "{\"event\":\"transaction_created\",\"data\":{\"id\":\"cc75b958-5780-4b34-a33a-cf63b349fbab\",\"custom_id\":\"209584732\",\"customer_id\":null,\"status\":\"new\",\"status_context\":null,\"address\":\"2NG8f2EVxN8XJ4DHriRt9q9LkdVCpQZ2UGB\",\"uri\":null,\"price_amount\":100.0,\"price_currency\":\"EUR\",\"fee\":null,\"fee_currency\":\"EUR\",\"pay_amount\":0.02038328,\"pay_currency\":\"BTC\",\"paid_amount\":0.02038328,\"exchange\":{\"pair\":\"BTCEUR\",\"rate\":4905.9838,\"fee\":null,\"fee_currency\":\"EUR\"},\"transactions\":[{\"txid\":\"502e6de0c3b1d129974c55e6cd127fd548e4501ff8e8d9330ea9a30a83dbd16e\",\"risk\":{\"score\":3.1,\"level\":\"low\",\"resource_name\":\"Bitstamp\",\"resource_category\":\"Exchange\"}}],\"name\":\"invoice name\",\"description\":\"invoice description\",\"metadata\":{\"foo\":\"bar\"},\"success_redirect_url\":null,\"unsuccess_redirect_url\":null,\"hosted_page_url\":\"https://hosted-business.cryptopay.me/invoices/cc75b958-5780-4b34-a33a-cf63b349fbab\",\"created_at\":\"2019-05-02T13:56:56Z\",\"expires_at\":\"2019-05-02T14:06:56Z\"},\"type\":\"Invoice\"}";
Stringsignature = "cd6ab5292630005bb79d299bdc64cbe69eedcc8dfd60ff615b5ed40923c23821";
booleanvalid = cryptopay.callbacks().validate(signature, body);
if (valid) {
Callbackcallback = cryptopay.callbacks().parse(body);
if (callbackinstanceofChannelPaymentCallback) {
process((ChannelPaymentCallback) callback);
} elseif (callbackinstanceofCoinWithdrawalCallback) {
process((CoinWithdrawalCallback) callback);
} elseif (callbackinstanceofInvoiceCallback) {
process((InvoiceCallback) callback);
} else {
}
}

Complete example of usage is available here: client-side, server-side.

Development

Local build

Check out the source code and run the following command to download all the dependencies and build the library:

mvn clean install

Coding conventions

checkstyle.xml file describes coding conventions. Based on sun_checks.xml with some adjustments. Rules are enforced by maven-checkstyle-plugin during the build process.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/cryptopay-dev/cryptopay-java.

License

The library is available as open source under the terms of the MIT License.