Creating wallet passes

Please make sure you read the Conventions before continuing with this guide.

Requirements

You will need an X-API-KEY for all steps.

Choosing the right endpoint for the target Wallet App

For creating a Wallet Pass for Google Wallet app, for a single ticket, use /notifications/wallet-passes/google-pass.

For creating a Wallet Pass for Apple Wallet app, for a single ticket, use /notifications/wallet-passes/apple-pass/{{ticketId}}.pkpass.

For creating a Wallet Passes bundle for Apple Wallet app, for all the tickets in a Journey, use /notifications/wallet-passes/apple-pass/{{ticketId}}.pkpasses.

All endpoints will require an encoded querystring parameter documented below, and also accept a querystring parameter lang to set the language of the pass contents, for example en-us.

Encoding the ticket information

First create a JSON with the required ticket information:

{
  "ticketId": "6834db2a07b67a053817b4df",
  "orderId": "6834db2907b67a053817b4de",
  "customerNumber": "259-122-727"
}


Make sure it's valid JSON, for example by running it through a JSON linter.

Select an Application. Betterez uses a particular Application named "external-wallets" for this, which is advised but not required. Then JWT encode that JSON using algorithm HS256 and the Application's PRIVATE KEY as the secret. You could use the online JWT site for this.

That should generate a JWT token string like this:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWNrZXRJZCI6IjY4MzRkYjJhMDdiNjdhMDUzODE3YjRkZiIsIm9yZGVySWQiOiI2ODM0ZGIyOTA3YjY3YTA1MzgxN2I0ZGUiLCJjdXN0b21lck51bWJlciI6IjI1OS0xMjItNzI3In0.-r5rhAIAPYYRPpU8XDeC7m50_pykep9r6SRmA1pnBrg


Include that string as the value of the u querystring parameter.

Testing the endpoints

The Google Wallet Pass endpoint will result in a redirect to a Google site that will handle adding the pass.

The Apple Wallet Pass endpoint will download a .pkpass (a ZIP file).

Consider each endpoint expected result when testing. For example using CURL with the .pkpass endpoint will require the proper handling of the binary response. It's advised to test manually in the browser at first.

Assuming the encoded parameter u was created using the PRIVATE KEY of an Application that has the following PUBLIC KEY: 36f52b3d-fa5a-1234-9245-860ae74e870d

For testing we could send that as an x-api-key querystring parameter.

Then the URL for testing the Google Wallet endpoint would be:

https://api.betterez.com/notifications/wallet-passes/google-pass?u=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWNrZXRJZCI6IjY4MzRkYjJhMDdiNjdhMDUzODE3YjRkZiIsIm9yZGVySWQiOiI2ODM0ZGIyOTA3YjY3YTA1MzgxN2I0ZGUiLCJjdXN0b21lck51bWJlciI6IjI1OS0xMjItNzI3In0.-r5rhAIAPYYRPpU8XDeC7m50_pykep9r6SRmA1pnBrg&x-api-key=36f52b3d-fa5a-1234-9245-860ae74e870d


And for Apple Wallet:

https://api.betterez.com/notifications/wallet-passes/apple-pass/6834db2a07b67a053817b4df.pkpass?u=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWNrZXRJZCI6IjY4MzRkYjJhMDdiNjdhMDUzODE3YjRkZiIsIm9yZGVySWQiOiI2ODM0ZGIyOTA3YjY3YTA1MzgxN2I0ZGUiLCJjdXN0b21lck51bWJlciI6IjI1OS0xMjItNzI3In0.-r5rhAIAPYYRPpU8XDeC7m50_pykep9r6SRmA1pnBrg&x-api-key=36f52b3d-fa5a-1234-9245-860ae74e870d


And using the lang parameter for french for example:

https://api.betterez.com/notifications/wallet-passes/apple-pass/6834db2a07b67a053817b4df.pkpass?lang=fr-fr&u=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aWNrZXRJZCI6IjY4MzRkYjJhMDdiNjdhMDUzODE3YjRkZiIsIm9yZGVySWQiOiI2ODM0ZGIyOTA3YjY3YTA1MzgxN2I0ZGUiLCJjdXN0b21lck51bWJlciI6IjI1OS0xMjItNzI3In0.-r5rhAIAPYYRPpU8XDeC7m50_pykep9r6SRmA1pnBrg&x-api-key=36f52b3d-fa5a-1234-9245-860ae74e870d


The general form then would be for Google Wallet:

https://api.betterez.com/notifications/wallet-passes/google-pass?u={{jwt}}&x-api-key={{publicApiKey}}&lang={{lang}}


And the general form for Apple Wallet:

https://api.betterez.com/notifications/wallet-passes/apple-pass/{{ticketId}}.pkpass?u={{jwt}}&x-api-key={{publicApiKey}}&lang={{lang}}