Payper - Unofficial Java SDK for PayPal REST API

Payper is an unofficial Java SDK for the PayPal REST API. It is tested and fully supported on current Java LTS releases (17, 21 and 25) and compatible with later Java 17+ runtimes. The library is built for multithreaded, high-concurrency environments: it uses immutable domain models and exposes a fluent API for concise, readable code.

Features

A concise, scannable summary of Payper's main capabilities. The table below helps you scan features quickly — expand the details if you want more context.

| Feature | Summary | |---|---| | 🧭 Java LTS compatibility (17, 21, 25) | Tested and supported on current Java LTS releases — 17, 21 and 25 — and compatible with Java 17+ runtimes. | | ⚡ Modern Java HTTP client | Uses the platform's modern HTTP client for HTTP/2, improved TLS and efficient connection handling. | | 🔒 Immutable, thread-safe models | Domain objects are immutable and safe to share across threads. | | ✨ Fluent, expressive API | Builder patterns and method chaining for concise, readable call flows. | | 🔑 Automatic OAuth 2.0 token management | Automatic acquisition, caching and refresh of OAuth 2.0 tokens. | | 🚀 Asynchronous & non-blocking support | CompletableFuture-based async APIs for non-blocking integrations. | | ⚙️ Flexible configuration | Configure via env vars, system properties or builders; specify executor, timeouts and proxies. | | 🏎️ Performance-oriented design | Low-overhead, connection management and retry policies for high concurrency. | | 🛠️ Response helpers & centralized error handling | Utilities to map responses, inspect status codes and centralize error handling. | | 📚 Hands-on examples | Ready-to-run examples and quickstarts: https://github.com/eealba/payper-examples |

<details> <summary><strong>More about key features</strong></summary>

Modern Java HTTP client

Payper leverages the platform HTTP client to benefit from HTTP/2, modern TLS improvements, connection pooling and non-blocking I/O. This yields better performance, reduced resource usage and simpler integration with Java networking features.

Flexible configuration (executor / timeouts / proxies)

You can tune networking and concurrency for your environment by providing a custom executor for request dispatching, configuring connection/read timeouts, and routing requests through a proxy. These options make it easy to adapt Payper to different deployment constraints.

Response helpers & error handling

The SDK provides helpers to convert raw HTTP responses into domain entities, inspect status codes and extract error details so you can centralize how your application handles API errors.

</details>

Supported PayPal REST APIs

| API Name | Version | Links | |-----------------------|---------|-----------------------------------------------------------------------------| | Catalog Products | v1 | API Reference |
| Subscriptions | v1 | API Reference | | Orders | v2 | API Reference | | Payments | v2 | API Reference | | Invoices | v2 | API Reference | | Webhooks Management | v1 | API Reference |

Installation

To use Payper in your project, add the appropriate dependency for the paypal service you want to consume in your pom.xml, in the table below the corresponding payper module appears for each service:

Subscriptions API

<dependency>
    <groupId>io.github.eealba.payper</groupId>
    <artifactId>payper-subscriptions-v1</artifactId>
    <version>1.0.0</version>
</dependency>

Catalog Products API

<dependency>
    <groupId>io.github.eealba.payper</groupId>
    <artifactId>payper-catalog-products-v1</artifactId>
    <version>1.0.0</version>
</dependency>

Orders API

<dependency>
    <groupId>io.github.eealba.payper</groupId>
    <artifactId>payper-orders-v2</artifactId>
    <version>1.0.0</version>
</dependency>

Payments API

<dependency>
    <groupId>io.github.eealba.payper</groupId>
    <artifactId>payper-payments-v2</artifactId>
    <version>1.0.0</version>
</dependency>

Invoices API

<dependency>
    <groupId>io.github.eealba.payper</groupId>
    <artifactId>payper-invoices-v2</artifactId>
    <version>1.0.0</version>
</dependency>

Webhooks Management API

<dependency>
    <groupId>io.github.eealba.payper</groupId>
    <artifactId>payper-webhooks-v1</artifactId>
    <version>1.0.0</version>
</dependency>

Coming Soon

| API Name | Version | Links | |-----------------------|---------|----------------------------------------------------------------------------------------| | Add Tracking | v1 | API Reference | | Disputes | v1 | API Reference | | Partner Referrals | v2 | API Reference | | Payment Experience | v1 | API Reference | | Payment Method Tokens | v3 | API Reference | | Payouts | v1 | API Reference | | Transaction Search | v1 | API Reference |

Examples

This project maintains a separate repository with runnable examples showing how to use the Payper SDK: https://github.com/eealba/payper-examples

| Example | Summary | Link | |-----------------------|-------------------------------------------------------------------------|------| | payper-5-minutes | 5-minute quickstart to validate sandbox credentials and perform a simple Catalog Products API call. | Open | | payper-orders-basic | Demonstrates Orders API v2: create, retrieve, confirm payment source, capture. | Open | | subscriptions-app | Demonstrates product and subscription plan creation (sync App.java and async AppAsync.java). | Open | | webstore | Spring Boot demo webstore showcasing catalog, ch