Skip to main content

How to use the PassKit Java SDK

The PassKit Java QuickStart provides working examples for creating and managing Apple Wallet and Google Wallet passes using the PassKit Java SDK.

Written by Claudia

The QuickStart includes examples for:

  • Membership and loyalty cards

  • Coupons

  • Event tickets

  • Boarding passes

This guide will help you configure your credentials, run the Java QuickStart and test the included examples.

Before You Start

Before using the Java QuickStart, you will need:

  • A PassKit account.

  • Your PassKit SDK credentials.

  • Java 11 or later.

  • An Apple Wallet certificate if you want to run the flights example.

You do not need to install Gradle separately. The QuickStart includes the Gradle wrapper required to build and run the project.

Download the QuickStart

The Java QuickStart is available from the PassKit Java QuickStart repository.

Clone the repository:

git clone https://github.com/PassKit/passkit-java-quickstart.git 
cd passkit-java-quickstart

Alternatively, download the repository as a ZIP from GitHub, extract it and open a terminal in the extracted folder.

Get Your PassKit SDK Credentials

The PassKit SDK uses SDK credentials to securely authenticate with the PassKit API.

To generate and download your SDK credentials:

  1. Log in to your PassKit account.

  2. Click your account icon in the bottom-left corner, then select Account from the menu.

  3. Select Developer Tools.

  4. Under Account Credentials, locate SDK Credentials.

  5. Follow the on-screen instructions to generate and download your credentials.

When generating your SDK credentials, you will be asked to create a password. This password is separate from your PassKit account password.

For Java, you will need the following credential files:

  • certificate.pem

  • ca-chain.pem

  • key-java.pem

The standard key.pem file is not compatible with the Java SDK. Make sure you use key-java.pem.

Important: Keep your SDK credentials and credential password private. Do not commit or share them through Git or another source control repository.

Add Your SDK Credentials

In the QuickStart repository, locate:

src/main/resources/

Create a folder named:

credentials

Add the three Java-compatible SDK credential files to this folder.

Your project should contain:

passkit-java-quickstart/ 
└── src/     
└── main/         
└── resources/             
└── credentials/                 
├── certificate.pem                 
├── ca-chain.pem                 
└── key-java.pem

The credential files are excluded by .gitignore and should not be committed to source control.

Configure the QuickStart

The recommended way to configure the current Java QuickStart is with a .env file.

Copy .env.example to .env.

On macOS or Linux:

cp .env.example .env

On Windows PowerShell:

Copy-Item .env.example .env

Open .env and add the password you created when generating your SDK credentials, along with any other required configuration.

Environment variables and values in .env take precedence over the legacy passkit.properties configuration.

Both .env and your SDK credential files should remain private and should not be committed to source control.

Configure Your API Region

Your QuickStart must connect to the API region associated with your PassKit account.

You can find your API region under Developer Tools → API Region in your PassKit account.

For gRPC connections, use:

Europe

grpc.pub1.passkit.io

United States

grpc.pub2.passkit.io

European accounts use the Europe endpoint by default.

If your account is in the United States region, add the following to .env:

PASSKIT_GRPC_HOST=grpc.pub2.passkit.io

Make sure the API region matches the region shown in your PassKit account.

Run the QuickStart

Once your credentials and configuration have been added, you can run one of the four guided workflows.

On macOS or Linux:

Membership and Loyalty

./gradlew run --args='membership'

Coupons

./gradlew run --args='coupons'

Event Tickets

./gradlew run --args='event-tickets'

Flights and Boarding Passes

./gradlew run --args='flights'

On Windows, use gradlew.bat instead of ./gradlew.

For example:

gradlew.bat run --args="membership"

Each workflow creates the resources required for the example and performs a series of common PassKit API operations.

Open Your Wallet Pass

The QuickStart outputs URLs for the passes generated by the workflows.

Open a pass URL on a compatible mobile device to add the pass to Apple Wallet or Google Wallet.

If you open the URL on a desktop, you can use the displayed QR code to open the pass on your phone.

What the Examples Demonstrate

Each workflow demonstrates common operations available through the PassKit Java SDK.

Membership and Loyalty

The membership workflow demonstrates operations such as:

  • Creating pass images and templates

  • Creating a membership or loyalty program

  • Creating tiers

  • Enrolling members

  • Retrieving member information

  • Checking members in and out

  • Earning and using loyalty points

  • Managing membership resources

Coupons

The coupons workflow demonstrates operations such as:

  • Creating pass images and templates

  • Creating a coupon campaign

  • Creating offers

  • Issuing coupons

  • Retrieving coupon information

  • Redeeming coupons

  • Managing coupon resources

Event Tickets

The event tickets workflow demonstrates operations such as:

  • Creating pass images and templates

  • Creating a production

  • Creating a venue and event

  • Creating ticket types

  • Issuing event tickets

  • Retrieving ticket information

  • Validating tickets

  • Redeeming tickets

  • Managing event ticket resources

Flights

The flights workflow demonstrates operations such as:

  • Creating boarding pass images and templates

  • Creating or using carriers

  • Creating or using airports

  • Creating flights

  • Creating flight designators

  • Issuing boarding passes

  • Retrieving flight and boarding pass information

Running the Flights Example

The flights workflow requires an Apple Wallet certificate to be uploaded to your PassKit account.

Add the Pass Type Identifier for your Apple Wallet certificate to your .env file using:

PASSKIT_APPLE_CERTIFICATE_ID=

For example:

PASSKIT_APPLE_CERTIFICATE_ID=pass.com.example.airline

Replace the example value with the Pass Type Identifier for your own Apple Wallet certificate.

Keeping Generated Resources

By default, the guided workflows clean up the sample resources they create.

If you want time to inspect the generated passes before they are removed, set:

PASSKIT_CLEANUP_DELAY_SECONDS=

to the number of seconds you want the QuickStart to wait before cleanup.

For example:

PASSKIT_CLEANUP_DELAY_SECONDS=60

This waits for 60 seconds before removing the generated resources.

If you want to keep the generated resources, set:

PASSKIT_CLEANUP_DELAY_SECONDS=-1

When this is set to -1, the generated resources are retained and you will need to remove them manually.

Running Tests

You can run the QuickStart's local tests with:

./gradlew test

Live API tests are skipped by default.

Once your SDK credentials have been configured, you can run the live workflow tests with:

PASSKIT_RUN_LIVE_TESTS=true ./gradlew test

The live tests connect to your PassKit account and can create PassKit resources.

Using the Java SDK in Your Application

Once you have successfully run a QuickStart workflow, you can use its implementation as a reference for your own Java application.

The current QuickStart provides a shared PassKitApi interface for accessing PassKit functionality.

For example:

try (PassKitApi api = new PassKitApi()) {     var loyalty = api.loyalty();     var coupons = api.coupons();     var events = api.eventTickets();     var flights = api.flights(); }

The domain APIs provide methods for common operations such as creating programs, issuing coupons and creating boarding passes.

The underlying generated SDK services are also available when you need functionality beyond the QuickStart examples.

Important: Potentially destructive bulk operations require explicit opt-in. Review the SDK and QuickStart documentation carefully before using bulk update or delete operations in your application.

Troubleshooting

Java is not recognised

Check that Java 11 or later is installed:

java -version

If the command is not recognised, install a supported Java JDK and make sure Java is available in your system path.

Gradle is not installed

You do not need to install Gradle separately.

Use the Gradle wrapper included with the repository:

./gradlew

or on Windows:

gradlew.bat

Credential files cannot be found

Confirm that the following files are located in:

src/main/resources/credentials/

The folder should contain:

certificate.pem 
ca-chain.pem 
key-java.pem

Make sure you are using key-java.pem, not key.pem.

Authentication fails

Check that the SDK credential password in .env matches the password you created when generating your SDK credentials.

This is separate from your PassKit account password.

Also check that all three credential files belong to the same set of SDK credentials.

Connection fails

Check Developer Tools → API Region in your PassKit account and confirm that the configured gRPC host matches your account.

Use:

grpc.pub1.passkit.io

for Europe or:

grpc.pub2.passkit.io

for the United States.

Also check whether a firewall or VPN is blocking outbound HTTPS or gRPC traffic.

Flights do not run

Confirm that an Apple Wallet certificate has been uploaded to PassKit and that its Pass Type Identifier has been added to:

PASSKIT_APPLE_CERTIFICATE_ID

Generated resources remain in your account

Check the terminal output for any cleanup errors.

Also check the value of:

PASSKIT_CLEANUP_DELAY_SECONDS

A value of -1 tells the QuickStart to retain the resources instead of deleting them.

Next Steps

Once you have successfully run the Java QuickStart, you can use the examples as a reference when implementing PassKit in your own Java application.

For additional methods, request fields and response definitions, refer to the PassKit developer documentation.

Related Articles
Did this answer your question?