SDK Libraries

Java SDK

Install the official MakePay Java SDK for payment links, settings, and webhook verification.

MakePay Java SDK

Overview

io.makecrypto:makepay is the official Java SDK for MakePay server-side integrations. It wraps API-key authentication, payment and donation links, anonymous public links, customers, subscriptions, invoices, bookkeeping, POS terminals, product catalogs, Simple Shop, branded domains, operational APIs, and signed webhook verification.

Package:

io.makecrypto:makepay

Installation

Gradle:

dependencies {
    implementation("io.makecrypto:makepay:0.3.0")
}

Maven:

<dependency>
  <groupId>io.makecrypto</groupId>
  <artifactId>makepay</artifactId>
  <version>0.3.0</version>
</dependency>

The SDK targets Java 11 or newer and uses the standard JDK HTTP client.

Authentication

Create a MakePay API key from the MakeCrypto merchant developer area and store the key secret only on your server.

import io.makecrypto.makepay.MakePayClient;
import io.makecrypto.makepay.MakePayClientOptions;

MakePayClient makepay = new MakePayClient(
    MakePayClientOptions.builder()
        .keyId(System.getenv("MAKEPAY_KEY_ID"))
        .keySecret(System.getenv("MAKEPAY_KEY_SECRET"))
        .build()
);

The SDK sends X-MakeCrypto-Key-Id and X-MakeCrypto-Key-Secret headers to the MakePay partner API. You can pass baseUrl for a non-production MakeCrypto API origin, and checkoutBaseUrl for a custom MakePay checkout origin.

Create Payment Link

import com.fasterxml.jackson.databind.JsonNode;
import java.util.Map;

JsonNode response = makepay.createPaymentLink(Map.of(
    "title", "Order #1042",
    "description", "Checkout for order #1042",
    "amount", "129.99",
    "currency", "USDT",
    "orderId", "order_1042",
    "customerEmail", "buyer@example.com",
    "returnUrl", "https://merchant.example/orders/1042",
    "successUrl", "https://merchant.example/orders/1042/success",
    "failureUrl", "https://merchant.example/orders/1042/pay",
    "expirationTime", "12h"
));

String publicUrl = response.path("paymentLink").path("publicUrl").asText();

Send a payment request email during creation:

import io.makecrypto.makepay.CreatePaymentLinkOptions;

makepay.createPaymentLink(
    payload,
    CreatePaymentLinkOptions.builder()
        .sendPaymentRequestEmail(true)
        .build()
);

Read and manage existing links:

makepay.listPaymentLinks();
makepay.getPaymentLink("PAYMENT_LINK_UID");
makepay.updatePaymentLink("PAYMENT_LINK_UID", Map.of("status", "paused"));
makepay.sendPaymentRequestEmail("PAYMENT_LINK_UID", "buyer@example.com");

Donation Links

Donation links use the same settlement and checkout infrastructure as payment links, but they publish a public donation slug and allow flexible donor amounts.

JsonNode donation = makepay.createDonationLink(Map.of(
    "title", "Spring campaign",
    "description", "Support the 2026 spring fundraiser.",
    "defaultAmountUsd", "25",
    "minimumAmountUsd", "5",
    "donationSlug", "spring-campaign"
));

String donationUrl = donation.path("paymentLink").path("publicUrl").asText();

makepay.listDonationLinks();
makepay.getDonationLink("DONATION_UID");
makepay.updateDonationLink("DONATION_UID", Map.of("status", "paused"));

Anonymous Payment Links

Use anonymous links when a payment page should be created without a MakePay API key. Because there is no authenticated merchant account, the request must include settlement routing.

import java.util.List;

JsonNode response = MakePayClient.createAnonymousPaymentLink(Map.of(
    "amount", "25",
    "settlement", Map.of(
        "currency", "USDT",
        "priorities", List.of(Map.of(
            "chain", "ETH",
            "address", "0xYourSettlementWallet",
            "asset", "ETH.USDT-0xdAC17F958D2ee523a2206206994597C13D831ec7"
        ))
    ),
    "title", "Invoice #1042",
    "customerEmail", "buyer@example.com",
    "webhookUrl", "https://merchant.example/webhooks/makepay"
));

Anonymous link payloads support title, description, orderId, clientId, customerEmail, returnUrl, successUrl, failureUrl, metadata, branding, webhookUrl, and expirationTime values from 15 minutes to 72 hours.

Hosted And Embedded Checkout

Use hosted checkout URLs for full-page redirects, or the embed helpers when your frontend keeps the shopper on the merchant page.

String paymentUid = response.path("paymentLink").path("uid").asText();

String hostedUrl = makepay.hostedCheckoutUrl(paymentUid);
String embedUrl = makepay.embeddedCheckoutUrl(
    paymentUid,
    "https://merchant.example"
);
String buttonHtml = makepay.embedButtonHtml(paymentUid, "Pay with crypto");
String iframeHtml = makepay.iframeHtml(paymentUid, "Secure MakePay checkout");

Donation pages have hosted and embedded URL helpers too:

makepay.hostedDonationUrl("spring-campaign");
makepay.embeddedDonationUrl("spring-campaign", "https://merchant.example");

For static CMS pages, MakePayClient.buildEmbedButtonHtml(paymentUid, baseUrl, label) returns a button snippet that loads the MakePay modal script.

Customers

makepay.upsertCustomer(Map.of(
    "email", "buyer@example.com",
    "name", "Buyer Example",
    "clientId", "crm_123",
    "metadata", Map.of("plan", "pro")
));

makepay.listCustomers();

makepay.createCustomerPortal("CUSTOMER_ID", Map.of(
    "returnUrl", "https://merchant.example/account"
));

Subscriptions

makepay.createSubscription(Map.of(
    "amountUsd", "29",
    "customerEmail", "buyer@example.com",
    "label", "Monthly plan",
    "billingIntervalUnit", "month",
    "billingIntervalCount", 1,
    "sendPaymentRequestEmail", true
));

makepay.listSubscriptions();

Subscription invoice payment links are generated by the subscription API. Do not create subscription_invoice links directly through createPaymentLink.

POS Terminals

JsonNode terminal = makepay.createPosTerminal(Map.of(
    "name", "Front counter",
    "pin", "1234",
    "allowedAssets", List.of(
        "ETH.USDT-0xdAC17F958D2ee523a2206206994597C13D831ec7"
    ),
    "emailCollectionMode", "optional_after_deposit",
    "catalogEnabled", true
));

makepay.listPosTerminals();
makepay.getPosTerminal("TERMINAL_UID");
makepay.updatePosTerminal("TERMINAL_UID", Map.of(
    "name", "Front counter",
    "pin", "5678",
    "catalogEnabled", true
));

Products

Products power POS catalogs and Simple Shop storefronts.

makepay.createProduct(Map.of(
    "name", "Digital guide",
    "productType", "digital",
    "basePriceUsd", "19",
    "shopSlug", "digital-guide",
    "images", List.of(Map.of(
        "url", "https://merchant.example/guide.png",
        "alt", "Guide cover"
    )),
    "variants", List.of(Map.of("name", "PDF", "priceUsd", "19"))
));

makepay.listProducts();
makepay.getProduct("PRODUCT_UID");
makepay.updateProduct("PRODUCT_UID", Map.of(
    "name", "Digital guide",
    "status", "active"
));

Digital products can include downloads:

makepay.createProductDownload("PRODUCT_UID", Map.of(
    "fileName", "guide.pdf",
    "contentType", "application/pdf",
    "url", "https://merchant.example/downloads/guide.pdf"
));

makepay.listProductDownloads("PRODUCT_UID");

Simple Shop

makepay.updateShop(Map.of(
    "slug", "merchant-shop",
    "displayCurrency", "USD",
    "checkoutMode", "hosted",
    "billingDetailsRequired", true,
    "flatShippingFeeUsd", "5",
    "freeShippingThresholdUsd", "100"
));

makepay.getShop();
makepay.updateShopBuilder(Map.of("blocks", List.of()));
makepay.getShopBuilder();

Connect and verify a shop domain:

makepay.updateShopDomain("shop.merchant.example");
makepay.getShopDomain();
makepay.refreshShopDomain();

Manage coupons and orders:

makepay.createShopCoupon(Map.of(
    "code", "SPRING10",
    "discountType", "percent",
    "value", "10"
));

makepay.listShopCoupons();
makepay.updateShopCoupon("COUPON_UID", Map.of("status", "archived"));
makepay.archiveShopCoupon("COUPON_UID");
makepay.listShopOrders(Map.of("status", "paid", "limit", 25));

Invoices And Bookkeeping

Bookkeeping APIs manage merchant invoices, expenses, supporting documents, OCR, and reconciliation links.

JsonNode invoice = makepay.createBookkeepingInvoice(Map.of(
    "title", "Invoice #1042",
    "currency", "USD",
    "issueDate", "2026-05-15",
    "dueDate", "2026-05-30",
    "counterparty", Map.of(
        "name", "Buyer Example",
        "email", "buyer@example.com",
        "clientId", "crm_123"
    ),
    "lineItems", List.of(Map.of(
        "description", "Implementation services",
        "quantity", "1",
        "unitAmount", "500",
        "taxAmount", "0"
    )),
    "metadata", Map.of("orderId", "order_1042")
));

makepay.createBookkeepingInvoicePaymentLink("INVOICE_UID", Map.of(
    "sendPaymentRequestEmail", true
));

makepay.listBookkeepingInvoices();
makepay.getBookkeepingInvoice("INVOICE_UID");
makepay.updateBookkeepingInvoice("INVOICE_UID", Map.of("status", "open"));

Create and reconcile expenses manually or from wallet activity:

makepay.createBookkeepingExpense(Map.of(
    "title", "Hosting",
    "amount", "49",
    "currency", "USD",
    "incurredOn", "2026-05-15",
    "category", "Infrastructure"
));

makepay.createBookkeepingExpenseFromActivity(Map.of(
    "walletActivityEventKey", "CHAIN_EVENT_KEY",
    "category", "Settlement"
));

makepay.createBookkeepingReconciliation(Map.of(
    "invoiceId", "INVOICE_UID",
    "paymentSessionId", "PAYMENT_SESSION_ID",
    "linkType", "payment"
));

Document uploads use multipart form data through a Path or byte array.

import java.nio.file.Path;

makepay.uploadBookkeepingDocument(
    Path.of("receipt.pdf"),
    "receipt.pdf",
    "receipt",
    null,
    "EXPENSE_UID"
);

makepay.listBookkeepingDocuments();
makepay.getBookkeepingDocumentDownloadUrl("DOCUMENT_UID");
makepay.runBookkeepingDocumentOcr("DOCUMENT_UID");
makepay.getBookkeepingSummary();

Branding And Domains

Branding controls merchant display details, checkout theme colors, payment-link domains, and email-sending domains.

makepay.updateBranding(Map.of(
    "brandName", "Merchant",
    "businessDescription", "Digital products and services.",
    "websiteUrl", "https://merchant.example",
    "supportEmail", "support@merchant.example",
    "brandingAccentColor", "#14b8a6",
    "paymentLinkDomain", "pay.merchant.example",
    "emailSendingDomain", "mail.merchant.example"
));

makepay.getBranding();
makepay.refreshBrandingDomains("all");

Use refreshBrandingDomains("payment-link") or refreshBrandingDomains("email-sending") when you only need one domain check.

Operational APIs

makepay.getSettings();
makepay.updateSettings(Map.of(
    "callbackUrl", "https://merchant.example/webhooks/makepay"
));

makepay.listDestinationAssets();
makepay.listWebhookRequests(Map.of("limit", 25));

listDestinationAssets is useful before configuring settlement overrides or anonymous settlement routes.

Webhook Verification

MakePay signs the exact raw request body. Read the body before parsing JSON.

import io.makecrypto.makepay.MakePayWebhook;

String rawBody = requestBodyString;
String signature = request.getHeader("x-makepay-signature");

JsonNode event = MakePayWebhook.parse(
    rawBody,
    signature,
    System.getenv("MAKEPAY_WEBHOOK_SECRET")
);

if ("status_changed".equals(event.path("event").path("type").asText())) {
    // Update the local order.
}

Use MakePayWebhook.verify(...) when you only need a boolean result.

SDK Method Coverage

Area	Methods
Payment links	`createPaymentLink`, `listPaymentLinks`, `getPaymentLink`, `updatePaymentLink`, `sendPaymentRequestEmail`
Donations	`createDonationLink`, `listDonationLinks`, `getDonationLink`, `updateDonationLink`
Anonymous links	`createAnonymousPaymentLink`, `createAnonymousMakePayPaymentLink`
Checkout	hosted, embedded, modal, button, iframe, and donation URL helpers
Customers	`listCustomers`, `upsertCustomer`, `createCustomerPortal`
Subscriptions	`listSubscriptions`, `createSubscription`
POS terminals	`listPosTerminals`, `createPosTerminal`, `getPosTerminal`, `updatePosTerminal`
Products	`listProducts`, `createProduct`, `getProduct`, `updateProduct`, `listProductDownloads`, `createProductDownload`
Simple Shop	`getShop`, `updateShop`, `getShopBuilder`, `updateShopBuilder`, `getShopDomain`, `updateShopDomain`, `refreshShopDomain`, coupon and order methods
Bookkeeping	summary, invoice, expense, document upload/OCR, and reconciliation methods
Branding	`getBranding`, `updateBranding`, `refreshBrandingDomains`
Operations	`getSettings`, `updateSettings`, `listDestinationAssets`, `listWebhookRequests`
Webhooks	`MakePayWebhook.verify`, `MakePayWebhook.parse`

Payloads And Response Models

Java payloads are Map<String, ?> values so the SDK can track MakePay API growth without forcing a Java model release for every field. Use the same camelCase payload names as the npm SDK.

Model conventions:

Use strings for decimal money values when precision matters, for example "129.99" instead of 129.99.
Dates are ISO strings. Date-only fields, such as invoice issueDate, should use YYYY-MM-DD.
IDs are usually public uid values. Bookkeeping detail endpoints accept an internal UUID or public UID.
API methods throw MakePayError for non-2xx responses.
Successful API calls return Jackson JsonNode envelopes so production can add fields without breaking JVM consumers.

Accepted Payload Models

Payload surface	Used by	Required fields	Common optional fields
Payment link	`createPaymentLink`	`amount`	`title`, `description`, `currency`, `asset`, `orderId`, `customerEmail`, `clientId`, redirect URLs, `metadata`
Donation link	`createDonationLink`	none	`defaultAmountUsd`, `minimumAmountUsd`, `donationSlug`, payment-link display and redirect fields
Anonymous payment link	`createAnonymousPaymentLink`	`amount`, `settlement.currency`, `settlement.priorities`	`title`, `customerEmail`, `orderId`, `metadata`, `branding`, `webhookUrl`, checkout redirect URLs
Customer	`upsertCustomer`	one of `email`, `customerEmail`, `name`, `clientId`	`metadata`
Subscription	`createSubscription`	plan amount/customer fields for your billing flow	`amountUsd`, `customerEmail`, `label`, `billingIntervalUnit`, `billingIntervalCount`, `startAt`, `sendPaymentRequestEmail`
POS terminal	`createPosTerminal`, `updatePosTerminal`	`name`	`pin`, `status`, `allowedAssets`, `emailCollectionMode`, `catalogEnabled`, `displaySettings`, `metadata`
Product	`createProduct`, `updateProduct`	`name`	`description`, `sku`, `status`, `productType`, `basePriceUsd`, `shopSlug`, `images`, `variants`, `taxRates`, `metadata`
Simple Shop	`updateShop`	none	`slug`, `status`, `displayCurrency`, `checkoutMode`, shipping fields, links, SEO, tracking, branding
Branding	`updateBranding`	none	brand name, support email, website URL, theme colors, `paymentLinkDomain`, `emailSendingDomain`
Bookkeeping invoice	`createBookkeepingInvoice`, `updateBookkeepingInvoice`	none; blank invoices are allowed as drafts	`invoiceNumber`, `status`, `paymentStatus`, `currency`, `issueDate`, `dueDate`, `counterparty`, `lineItems`, `documentIds`
Bookkeeping expense	`createBookkeepingExpense`, `createBookkeepingExpenseFromActivity`, `updateBookkeepingExpense`	none; amount defaults to zero if no activity is used	`amount`, `currency`, `category`, `incurredOn`, wallet activity IDs, `counterparty`, `metadata`
Document upload	`uploadBookkeepingDocument`	`file`	`fileName`, `documentType`, `invoiceId`, `expenseId`
Reconciliation	`createBookkeepingReconciliation`	one target and one source	target: `invoiceId` or `expenseId`; source: payment, subscription cycle, or wallet activity; `amount`, `assetSymbol`, `metadata`
Open-ended maps	product downloads, shop builder, coupons, settings, customer portal	route-specific	these advanced surfaces stay open-ended while their server schemas evolve

Error Handling

API calls throw MakePayError. It includes the HTTP status and decoded response body.

import io.makecrypto.makepay.MakePayError;

try {
    makepay.getPaymentLink("PAYMENT_LINK_UID");
} catch (MakePayError error) {
    logger.warn("MakePay failed with status {}", error.getStatus());
}

Source Layout

The canonical monorepo source lives in apps/plugins/java-sdk. The published Maven package contains the compiled jar, sources jar, javadocs jar, signed POM, and Central Portal checksums.

Release Notes

The package is published as io.makecrypto:makepay on Maven Central through the Central Portal Publisher API. Release publishing uses a Central Portal user token and an in-memory PGP signing key in GitHub Actions.