mpp-java

Java SDK for the Machine Payments Protocol

Note: This is an experimental SDK and the API is subject to change.

Installation

Gradle

implementation 'com.stripe:mpp-java:0.1.3'

Maven

<dependency>
<groupId>com.stripe</groupId>
<artifactId>mpp-java</artifactId>
<version>0.1.3</version>
</dependency>

Usage

Testnet

// Token contract address for the currency you acceptStringcurrency = TempoDefaults.TESTNET_PATH_USD;
// Your server's realm — identifies this API in payment challengesStringrealm = "api.example.com";
// Secret used to secure payment challenges// https://mpp.dev/protocol/challenges#challenge-bindingStringmppSecret = System.getenv("MPP_SECRET_KEY");
TempoMethodtempo = TempoMethod.of().testnet().build();
MppHandlermppHandler = Mpp.create(tempo, realm, mppSecret);
// In your HTTP handler: verify if MPP payment has been providedVerifyResultresult = mppHandler.charge(
request.getHeader("Authorization"),
ChargeRequest.of(tempo.chargeIntent(), "0.50", currency, "0xYourWalletAddress")
.description("Paid endpoint")
);
if (resultinstanceofVerifyResult.Challenged) {
response.setHeader("WWW-Authenticate",
((VerifyResult.Challenged) result).challenge().toWwwAuthenticate());
response.setStatus(402);
} else {
VerifyResult.Verifiedverified = (VerifyResult.Verified) result;
response.setHeader("Payment-Receipt", verified.receipt().toPaymentReceipt());
// serve your content
}

Test the endpoint using the Tempo CLI:

tempo request https://your-api.com/your-endpoint

Tempo API relay

Delegate Moderato charge validation and broadcast to Tempo API by adding the server-side API key to the method builder:

TempoMethodtempo = TempoMethod.of()
.testnet()
.relay(System.getenv("TEMPO_API_KEY"))
.build();

MppHandler.charge(...) validates immediately before broadcast. Applications that expose those phases separately can use validateCredential(...) for a non-mutating pre-check and broadcastCredential(...) when accepting the payment. The latter always re-validates first.

See the runnable Tempo relay example.

Mainnet

// Token contract address for the currency you acceptStringcurrency = TempoDefaults.MAINNET_USDC;
// Your server's realm — identifies this API in payment challengesStringrealm = "api.example.com";
// Secret used to secure payment challenges// https://mpp.dev/protocol/challenges#challenge-bindingStringmppSecret = System.getenv("MPP_SECRET_KEY");
TempoMethodtempo = TempoMethod.of().build(); // mainnet is the defaultMppHandlermppHandler = Mpp.create(tempo, realm, mppSecret);
// In your HTTP handler: verify if MPP payment has been providedVerifyResultresult = mppHandler.charge(
request.getHeader("Authorization"),
ChargeRequest.of(tempo.chargeIntent(), "0.50", currency, "0xYourWalletAddress")
.description("Paid endpoint")
);
if (resultinstanceofVerifyResult.Challenged) {
response.setHeader("WWW-Authenticate",
((VerifyResult.Challenged) result).challenge().toWwwAuthenticate());
response.setStatus(402);
} else {
VerifyResult.Verifiedverified = (VerifyResult.Verified) result;
response.setHeader("Payment-Receipt", verified.receipt().toPaymentReceipt());
// serve your content
}

Releasing

1. Create a release branch and update VERSION_NAME in gradle.properties and the version references in this README.
2. Open a PR and let CI pass.
3. Merge the PR to main.
4. Tag the merge commit and push the tag:

   git checkout main && git pull
   git tag v<version>
   git push origin v<version>

5. The Publish workflow will automatically build, test across Java 11/17/21, and publish to Maven Central.
6. Verify the artifact appears on Maven Central.