MicroMacro Mobile Inc.

Pass API User Guide

Version 2.2.1

July 22, 2019

Version History

Version UpdatedAt Note

1.0 June 16, 2015 The first Pass API documentation

2.0 February 1, 2018 Rebuild Pass API from the ground up to be

simpler, more consistent, and truly RESTful

2.1 December 10, 2018 Add pass issue and installation event
callbacks to webhook urls

2.2 Jan 24, 2019 Add get pass status API

2.2.1 July 22, 2019 Correct several typos

1
Get Started with the Pass API
With Pass2U Pass API v2, we’ve rebuilt this API from the ground up to be simpler,
more consistent, and truly RESTful style without binding to any programming
language. Retailers, marketing companies, advertisers, third party ticket/coupon
providers, or travel agencies, can easily use Pass API to automate the process of
creating and updating mobile coupons, membership cards, punch cards, event
tickets, and travel passes in existing platforms or systems.

Before You Start

As a Pass2U Enterprise client or pay to activate API, you are allowed to gain all
Pass API access. If you'd like to apply API key, please contact with Pass2U Support
via ​contact@micromacro.com.tw and provide the details below. We’re excited to
learn about what you’ve built.

● Register​ and provide Pass2U account.

● What kind of pass type you are using (e.g. coupons, loyalty cards, tickets...)?
● How to distribute the passes to your customers? (e.g. email, message, official
website, app, facebook...)
● Are you going to use Pass2U Checkout Service for redemption?

2
Fundamental Concepts
The primary concept is that passes are created from issued models. All created
passes are located at unique download URLs which are in form of
https://www.pass2u.net/d/passId

Pass API can be used for :

● Create passes with custom data (e.g. ticket/card number, customer name,
email, individual discount...).
● Update passes with specified field changes, so the user’s pass would be
updated automatically via push notification.
● Delete customized attributes or fields of generated passes

Generated download URLs for passes from API can be distributed through your own
channels to customers(e.g. email, SMS, official website, app, facebook...).

How Does It Work?

1. Log in to ​Dashboard​, and click ​Create a Model​.

2. Click to select a style you want to distribute to customers. The model’s style
determines the overall default visual appearance of the passes.

3
3. On Model Designer page, you can quickly configure model appearance and
the barcode type. About field type, only ​Dynamic ​field (e.g. member name,
email, Individual discount, points, balances, and etc.) can be customized and
used in Pass API. In order to identify and customize this field via Pass API,
the dynamic field should be named with a unique key. ​Fixed field means all
passes of the model use the same data. ​Fixed​, ​Points ​and Credits ​fields
can’t be used in Pass API.

About barcode type, ​Dynamic – assigned by CSV file or API (duplicable) or

Dynamic – assigned by CSV file or API (not duplicable) can be used to
specify barcode. ​Dynamic – unique random 8-digit number ​is used to

4
 generate unique 8-digit number barcode for every pass automatically by
Pass2U platform, you needn’t specify barcode in Pass2U API.

4. After completing model design, please click ​Next ​until the model is issued.
The model appears ​on the ​Issuing tab within dashboard ​and you will get the
Model ID​ of the model.

5. Use the ​Model ID to manipulate Pass API. After the pass is created, you will
get the ​passId in the API response. Please keep it in your system so that
pass can be managed individually.

API Overview

All API URLs referred in the documentation starting with the following endpoint:

https://api.pass2u.net/v2

HTTP Path Function

Method

POST /models/{modelId}/passes?source={sourceId} Create pass

PUT /models/{modelId}/passes/{passId} Update pass

DELETE /models/{modelId}/passes/{passId}/attributes/{attrib Reset pass attribute

5
 uteName}

DELETE /models/{modelId}/passes/{passId}/fields/{fieldKey} Reset custom field

DELETE /models/{modelId}/passes/{passId}/fields/{fieldKey} Reset field​ ​attribute

/attributes/{attributeName}

GET /models/{modelId}/passes/{passId} Get pkpass file

GET /models/{modelId}/passes/{passId}/status Get pass status

POST /images Upload pass image

Authentication
Pass2U uses 32-characters length of Base64 encoded string as API key to
authenticate request. The API key must be included in all API requests to Pass2U
server in header ''x-api-key'' like the following sample:

x-api-key: e6a45207817bb8e9b1f3e67bb696067c

API key allows access to your private data in Pass2U. ​It should be kept strictly

confidential and not share with others​. If you have to change the API key, please

contact Pass2U Support.

RESTful HTTP Methods

We do our best to use standard HTTP Methods in Pass API:

● Only JSON format is supported as payload of request / response

● Responds with standard HTTP response codes to indicate errors
● Pass2U runs a series of services on AWS
● Pass2U takes PCI DSS (Payment Card Industry Data Security Standard
Standard) to protect your data

API Rate Limits

To help prevent strain on Pass2U’s servers, Pass API imposes rate limits per API
key. There is a limit of 100 requests per second per API for each API key. If a

6
request exceeds the limit, Pass2U will return a 429 error along with a message
corresponding to which limit was exceeded.

About API Parameters

All API parameters of requesting payload are listed in the following tables. Please
read ​Apple Wallet Package Format Reference and ​Apple Wallet Pass
Programming Guide​ before using Pass API.

Top-Level Key attributes

These attributes can be customized and updated when using ​"​Create pass​"​ or
"​Update pass​"​ API. Followings are replacement rules of visual appearance:
● If you don’t specify any attributes (e.g. logoText) in request payload, the
attributes will be set by model attributes.
● If you specify attributes in request payload, the attributes will be customized
for the pass.
● "​Delete pass attribute​" API is used to reset pass attribute to the default
attribute of the model.

(1) Standard Keys

Type (max
Name Description
length)

string description​ is what you describe the campaign about the

description
(1000) pass.

organizationName​ will be shown on the lock screen while the

organizationName string (100) pass holder is near the specific locations or receives the push
notification.

passcode​ is used to protect pass download page. If passcode

passcode string (100) is assigned, pass download page visitors must input correct
passcode to get the pass

7
(2) Associated App Keys

Name Type Description

A list of iTunes Store item identifiers for the associated iOS

apps. Only one item is allowed—the item identifier for an iOS
associatedStoreId array of app compatible with the current device. If the app is not
entifiers number (11) installed, clicking the link opens the App Store and shows the
app. If the app is already installed, clicking the link launches
the app.

A URL to be passed to the associated iOS app when

appLaunchURL string (255)
launched.

A list of Google Play identifiers for the associated android

apps. Only one item is allowed—the item identifier for an
associatedPlayIde array of android app compatible with the current device. If the app is
ntifiers string (255) not installed, clicking the link opens the Google Play and
shows the app. If the app is already installed, clicking the link
launches the app.

androidAppLaunch A URL to be passed to the associated android app when

string (255)
URL launched.

(3) Expiration Keys

Name Type Description

The date and time in ​ISO 8601 format to indicate ​when the
expirationDate string (30) pass expires. The value must be a complete date with hours,
minutes, and seconds with time zone. ​Example:

8
 2018-10-18T16:53:00+08:00

Indicates if the pass is void—for example, when a one time

voided boolean use coupon that has been redeemed, this key should be set as
true . The default value is false.

(4) Relevance Keys

Name Type Description

Maximum distance in meters from a relevant latitude and

longitude that the pass will be treated as relevant. This number
maxDistance number
is compared to the pass’s default distance and the smaller
value is used.

For event tickets and boarding passes; otherwise optional.

Date and time in ​ISO 8601 format to indicate ​when the pass
becomes relevant. For example, the start time of a movie.
relevantDate string (30)

The value must be a complete date with hour, minute, and

second with time zone.​ ​Example: 2018-10-18T16:53:00+08:00

(5) Visual Appearance Keys

Name Type Description

backgroundColor string (18) Background color of the pass, specified as an CSS-style RGB

9
 ​ xample: rgb(23, 187, 82)
triple.​ E

Foreground color of the pass, specified as a CSS-style RGB

foregroundColor string (18)
triple.​ Example: rgb(100, 10, 110)

For event tickets and boarding passes used to group related

passes; otherwise not allowed. Identifier. If a grouping identifier
groupingIdentifier string (50) is specified, passes with the same style, pass type identifier,
and grouping identifier are displayed in a group. Otherwise,
passes are grouped by style and pass type identifier.

Color of the label text, specified as a CSS-style RGB triple.

labelColor string (18)
Example: rgb(255, 255, 255)

logoText string (35) The logoText displayed next to the logo on the pass.

Lower-Level Key attributes

These attributes can be updated by ​"​Create pass​"​ or ​"​Update pass​"​ API.

Followings are replacement rules of visual appearance. For example,
● If you don’t specify an image array in JSON, the pass will use the default
model image.
● Remember to provide all types of images that you want to display on the
pass. If not all images are specified, missing images won’t be displayed event
if default model images are set in Model Designer.

(1) Image Dictionary Keys (Array)

The model style controls which images can be used. The table shows the images
supported by each model style. For details, see ​Apple Wallet Developer Guide​.

Name Type Description

an array of An array of image objects. Different model style allows

images JSON different image types. Please refer to ​Apple Wallet Developer
objects Guide​.

10
 Image types. Must be one of the following values: ​icon​
type string (35)
(required), logo​, strip​, background​, thumbnail​, footer​.

A hexadecimal hash string responded by ​Upload Pass

hex string (50) image​ API. For example, a hexadecimal hash string could be:
01474ead01d4b4ee6ad3bda2b15013888e74c866

(2) Pass Structure Dictionary Keys

Name Type Description

Required for boarding passes; otherwise not allowed. Type of

transit must be one of the following values: ​PKTransitTypeAir,
transitType string (20)
PKTransitTypeBoat, PKTransitTypeBus,
PKTransitTypeGeneric,PKTransitTypeTrain.

(3) Beacon Dictionary Keys (Array)

You can specify an array of data for up to 10 iBeacons per pass. When the card
holder enters within range of a defined iBeacon, a notification will show on the lock
screen.

Name Type Description

array of
An array of beacon objects. Apple Wallet limits the pass to 10
beacons JSON
beacon objects.
objects

Major identifier of a Bluetooth Low Energy location beacon. It

major number (16)
should be a 16-bit unsigned integer.

Minor identifier of a Bluetooth Low Energy location beacon. It

minjor number (16)
should be a 16-bit unsigned integer.

proximityUUID string (36) Unique identifier of a Bluetooth Low Energy location beacon.

Text displayed on the lock screen when the pass is currently

relevantText string (255) relevant. For example, a description of the nearby location
such as “Store nearby on 1st and Main.”

11
(4) Location Dictionary Keys (Array)

You can specify an array of data for up to 10 locations per pass. When the card
holder enters within range of a defined location, a notification will show on the lock
screen.

Pass Type Relevant locations

Boarding Pass With a large radius, on the order of a thousand meters or closer.

With a small radius, the current location must be on the order of a hundred
Coupon
meters or closer.

Event Ticket With a large radius, on the order of a thousand meters or closer.

With a small radius, the current location must be on the order of a hundred
Store Card
meters or closer.

With a small radius, the current location must be on the order of a hundred
Generic
meters or closer.

Name Type Description

array of
An array of location objects. Apple Wallet limits the pass to 10
locations JSON
location objects.
objects

altitude double Altitude, in meters, of the location.

latitude double Latitude, in degrees, of the location.

longitude double Longitude, in degrees, of the location.

12
 Text displayed on the lock screen when the pass is currently
relevantText string (255) relevant. For example, a description of the nearby location
such as "Store nearby on 1st and Main."

(5) Barcode Dictionary Keys

Name Type Description

an JSON
barcode A JSON object of barcode.
object

Text displayed under the barcode. For example, a

altText string (50) human-readable version of the barcode data in case the
barcode can’t be scanned.

message string (255) Message or payload to be displayed as a barcode.

Field Dictionary Keys

Every field has its own attributes. Attributes of a field can be given values when
using ​"​Create pass​"​ or ​"​Update pass​"​ API. Followings are replacement rules of
fields:

● Only ​Dynamic​ fields can be given values. A field which is configured as ​Dynamic
when designing the model is a ​Dynamic​ field.

13
 ● If you don’t specify custom data to fields in API, the default data of the fields
of the model will be used.
● If you don’t specify data to attributes of a field in API, the default attributes of
the field of the model will be used.
● If you specify custom data for a field in API, API will set the custom data to the
field and keep the field data as customized. The field data will not be updated
even if updating the model unless you use "​Update pass​" API to update the
field data.
● If you want to remove the customized data of the field and reset to the default
field data of the model, please use "​Delete custom field​" API.
● If you specify an empty value to an attribute of a field (ex: "fields":[
{"key":"field1","label":""} ] "), API will give empty value to the attribute.

Name Type Description

an array of An array of field objects. ​Y​ou can specify an array of field

fields JSON objects that configured to be ​Dynamic​ when designing the

objects model.

14
 string
This is a unique identifier for the specified model field that can
key
(100) be defined on Model Designer.

string
label Label text for the field.
(150)

string
Value of the field. It can be a ​string, ISO 8601 date format as a
value
(5000) string, or number​.

Format string for the alert text that is displayed when the pass is
updated. The format string must contain the escape ​%@​, which
changeMessage string (80) is replaced by the field’s new value. For example, "​Get changed
to %@​"​. ​If you don’t specify a change message, the user isn’t
notified when the field changes.

Create pass
Create a unique pass from the specified model by customizing attributes and
Dynamic​ fields of the model.

URL Structure

Method URL

POST https://api.pass2u.net/v2/models/{modelId}/passes?source={sourceId}

Name Type Required Description

The unique ID for the specified model you are using to

modelId string Yes
create the pass. You can find modelId in ​Dashboard​.

The sourceId is the name you give to track issuing

amount of the interested channel. For example, if you
sourceId string No have a campaign on social media, on an official website /
app, you can use a separate sourceId for each to get
record the issuing amount automatically in ​Dashboard​.

HTTP Request Header

x-api-key: {​ x-api-key}
Accept:​ application/json

15
Content-Type:​ application/json

Example Request Body

Following is an example of the JSON payload used to create a membership card
from the specified model:

The membership card have the member’s name, date of birth, member level, profile
photo, expiration date and relevant locations that the member preferred. In addition,
configuring background color to distinguish different member level that are intended
to enhance users' experience. All values provided will replace default values of the
model.

{
"expirationDate"​:​"2018-12-31T23:00:15+08:00"​,
"foregroundColor"​:​"rgb(51, 50, 46)"​,
"backgroundColor"​:​"rgb(237, 219, 21)"​,
"labelColor"​:​"rgb(196, 54, 39)"​,
"sharingProhibited"​:​true​,
"fields"​:​[
{
"key"​:​"name"​,
"label"​:​"Name"​,
"value"​:​"Fi-Lin,Chen"
}​,​{
"key"​:​"birth"​,
"label"​:​"Birth"​,
"value"​:​"Dec’10 1999"
}​,
{
"key"​:​"level"​,
"label"​:​"Level"​,
"value"​:​"GOLD"
}
]​,
"barcode"​:​{
"message"​:​"1234567890"​,
"altText"​:​"1234567890"
}​,
"images"​:​[
{

16
 "type"​:​"thumbnail"​,
"hex"​:​"d33b9f1426d363340c2946557f173c402cd74014"
}
]​,
"locations"​:​[
{
"latitude"​:​25.0413093​,
"longitude"​:​121.55269329999999​,
"relevantText"​:​"Store nearby on 1st and Main."
}​,
{
"latitude"​:​12.0413093​,
"longitude"​:​181.3226​,
"relevantText"​:​"Take a break with Bistro Coffee"
}
]​}

HTTP Response Header

Content-Type:​ application/json

Example Response Body

If the call is successful, ​Pass2U ​returns ​passId​ and created time.

{
"barcodeMessage"​:​"1234567890"​,
"modelId"​:​1919​,
"passId"​:​"VT-2I77F5ADz"​,
"createdTime"​:​"2018-01-25T16:19:36+08:00"​,
"expirationDate"​:​"2018-12-31T23:00:15+08:00"
}

Name Description

barcodeMessage The ​Information specified to the pass’s barcode.

modelId The unique ID of the model this pass created from.

The unique ID of the created pass you should keep. When updating this
passId
pass, please provide this passId​.

createdTime The date and time when the pass is created.

expirationDate The date and time when a pass expires and whether it is still valid. After

17
 the expiration date, the pass is automatically voided.

The publicly accessible URL for downloading the pass:

https://www.pass2u.net/d/{passId}

Update pass
Update a generated pass by adding or changing customizable attributes and
dynamic fields of the model. A notification message will be sent to mobile devices of
the pass holders and shown on lock screens (e.g. latest news, balances, points,
special discount, customer information, records...).

URL Structure

Method URL

PUT https://api.pass2u.net/v2/models/{modelId}/passes/{passId}

Name Type Required Description

The unique ID of the specified model you want to update

modelId string Yes the specified pass from. You can find modelId in
Dashboard​.

passId string Yes The unique ID of the specified pass you want to update.

HTTP Request Header

x-api-key: {​ x-api-key}
Accept:​ application/json
Content-Type:​ application/json

Example Request Body

18
 {
"expirationDate"​:​"2019-12-31T23:00:15+08:00"​,
"foregroundColor"​:​"rgb(51, 50, 46)"​,
"backgroundColor"​:​"rgb(211, 79, 46)"​,
"labelColor"​:​"rgb(196, 54, 39)"​,
"fields"​:​[
{
"key"​:​"level"​,
"label"​:​"Level"​,
"value"​:​"DIAMON"​,
"changeMessage"​:​"You get highest and most rewarding level %@"
}
]​,
}

HTTP Response Header

Content-Type:​ application/json

Example Response Body

If the call is successful, passId and updated time will be returned.

{
"barcodeMessage"​:​"1234567890"​,
"modelId"​:​1919​,
"passId"​:​"VT-2I77F5ADz"​,
"updatedTime"​:​"2018-01-25T16:19:36+08:00"​,
"expirationDate"​:​"2018-12-31T23:00:15+08:00"
}

Name Description

barcodeMessage The ​information specified to the pass’s barcode.

modelId The unique ID of the model this pass created from.

The unique ID of the created pass you should keep. Use this passId​ to
passId
manipulate the pass hereafter.

updatedTime The date and time when the pass is updated.

expirationDate The date and time when the pass expires.

19
Reset pass attribute
Reset a customized​ Top-Level Key​ or ​Lower-Level Key​ attribute of the specified
pass to use the default value of the model (e.g. logo text, colors, relevant date,
expiration date...).

URL Structure

Method URL

DELETE https://api.pass2u.net/v2/models/{modelId}/passes/{passId}/attributes/{att
ributeName}

Name Type Required Description

The unique ID of the specified model you want to reset

modelId string Yes the custom attributes of the pass from. You can find
modelId in ​Dashboard​.

The unique ID of the specified pass you want to reset the

passId string Yes
custom attributes from.

The unique ​Top-Level Key​ or ​Lower-Level Key​ attribute

attributeName string Yes
of the pass you want to reset.

HTTP Request Header

x-api-key: {​ x-api-key}
Accept:​ application/json
Content-Type:​ application/json

HTTP Request Body

none

HTTP Response Header

20
Content-Type:​ application/json

HTTP Response Body

Returns an HTTP status of 200 if the call is successful.

none

Reset custom field

Reset a custom field of the specified pass to use the default field data of the model.

URL Structure

Method URL

DELETE https://api.pass2u.net/v2/models/{modelId}/passes/{passId}/fields/{fieldK
ey}

Name Type Required Description

The unique ID of the specified model you want to reset

modelId string Yes the custom field of the pass from. You can find modelId
in ​Dashboard​.

The unique ID of the specified pass you want to reset the

passId string Yes
field from.

The unique key of the customized field you want to reset.

fieldKey string Yes
It must be defined in the model.

HTTP Request Header

x-api-key: {​ x-api-key}
Accept:​ application/json
Content-Type:​ application/json

HTTP Request Body

none

21
HTTP Response Header
Content-Type:​ application/json

HTTP Response Body

Returns an HTTP status of 200 if the call is successful.

none

Reset field attribute

Reset an attribute of the customized field to use the default field attribute of the
model.

URL Structure

Method URL

DELETE https://api.pass2u.net/v2/models/{modelId}/passes/{passId}/fields/{fieldK
ey}/attributes/{attributeName}

Name Type Required Description

The unique ID of the specified model you want to reset

modelId string Yes the custom field attribute of the pass from. You can find
modelId in ​Dashboard​.

The unique ID of the specified pass you want to reset the

passId string Yes
field attributes from.

The unique key of the customized field you want to reset

fieldKey string Yes
the field attributes from.

The name of field attribute of the specified pass you want

attributeName string Yes
to reset.

HTTP Request Header

x-api-key: {​ x-api-key}

22
Accept:​ application/json
Content-Type:​ application/json

HTTP Request Body

none

HTTP Response Header

Content-Type:​ application/json

HTTP Response Body

Returns an HTTP status of 200 if the call is successful.

none

Get pkpass file

If you want to distribute a pass via web page or app other than Pass2U web page,
you can use this API get the pkpass file directly.

URL Structure

Method URL

GET https://api.pass2u.net/v2/models/{modelId}/passes/{passId}

Name Type Required Description

The unique ID of the specified model you want to get the

modelId string Yes
specified pass from.

passId string Yes The unique ID of the specified pass you want to get.

HTTP Request Header

x-api-key: {​ x-api-key}
Accept:​ application/vnd.apple.pkpass

23
Content-Disposotion:​ attachment; filename=pass.pkpass

HTTP Response Header

Content-Type:​ application/vnd.apple.pkpass

HTTP Response Body

Returns an HTTP status of 200 if the call is successful.

MIME type .pkpass file binary stream.

Get pass status

URL Structure

Method URL

GET https://api.pass2u.net/v2/models/{modelId}/passes/{passId}/status

Name Type Required Description

The unique ID of the specified model you want to query

modelId string Yes
the specified pass from.

passId string Yes The unique ID of the specified pass you want to query.

HTTP Request Header

x-api-key: {​ x-api-key}
Accept:​ application/json

HTTP Request Body

none

HTTP Response Header

Content-Type:​ application/json

HTTP Response Body

24
Returns an HTTP status of 200 if the call is successful.

{
"passId"​:​"VT-2I77F5ADz"​,
"devices"​:​[
{
"brand"​:​"iPhone"​,
"model"​:​"XR"​,
"installedATime"​:​"2019-12-31T23:00:15+08:00"
}
]​,
"redemptions"​:​[
{
"campaignId"​:​ 2455​,
"campaignName"​:​"NIKE Run"​,
"checkoutAccount"​:​"Betty",
"storeName"​:​"HK No.1",
"redeemedTime"​:​"2019-12-31T23:00:15+08:00"
}
]​,
}

Name Description

passId The unique ID of the created pass you query.

devices An array to indicate which devices ever install the pass

brand The brand name of the installed device

model The model name of the installed device

installedTime The date and time when the pass installed in the device

An array to indicate which one-time redemption campaigns redeem the

redemptions
pass

campaignId The ID of the redemption campaign

campaignName The name of the redemption campaign

checkoutAccount The Pass2U Checkout account name who redeemed the pass

The name of the store which Pass2U Checkout account who redeemed
storeName
the pass belongs to

redeemedTime The date and time when the pass is redeemed

25
Upload pass image
When creating or updating the pass, you may want to replace the default model
image with a new image. The model style defines which types of images can be
assigned. Please refer to ​Apple Wallet Developer Guide to learn more about image
types for different styles.

Pass Type Supported images

Boarding Pass Icon, Logo, Footer

Coupon Icon, Logo, Strip

Eventicket - Layout 1 Icon, Logo, Background, Thumbnail

Eventtickrt - Layout 2 Icon, Logo, Strip

Store Card Icon, Logo, Strip

Generic Icon, Logo, Thumbnail

URL Structure

Method URL

POST https://api.pass2u.net/v2/images

26
HTTP Request Header
x-api-key: {​ x-api-key}
Accept:​ application/json
Content-Type:​ image/png

HTTP Request Body

The image binary data.

Upload limitations

● Format supported: png

● Maximum file size is: 4MB
● Maximum image dimensions are: 1024 px х 1024 px

Recommended Image dimensions

Image Type Width Height

Icon 58 58

Logo 320 100

Strip 750 288

Thumbnail 180 180

Background 360 440

Footer 572 30

HTTP Response Header

Content-Type:​ image/png
Content-Disposition:​ attachment; filename={imageName}.png

Example Response Body

{
"hex"​:​"89b9a6edb1132bae969711230ef63e3fb367f34e"

27
}

Name Description

The unique hex for the image you may use if the pass have to be
hex
customized the image.

Error Codes

HTTP Status Code Error Code Retry

400 Bad Request Exception No

403 Access Denied Exception No

404 Not Found Exception No

405 Bad Method No

405 HTTP Not Acceptable No

409 Conflict Exception No

415 HTTP Unsupportted Type No

429 Too Many Requests Exception Yes

503 Service Unavailable Exception Yes

504 Endpoint Request Timed-out Exception Yes

Sample Error Response

{
"message"​:​"error"
}

Callback to Webhook Url

If you generated a pass which is not created by API or a pass is installed in a user

28
device, you can get the notification by HTTP POST when the relevant webhook urls
are specified. You can assign pass generating and installation webhook urls in step
3 “Configure Model Issuing Settings” in model issuing process.

Or edit “Issuing Settings” after the model is issued

29
Pass Generated Event

URL Structure

Method URL

POST Your pass generating webhook url (HTTPS is required) and will be called
by Pass2U

Name Type Description

The unique ID of the specified model which the generated pass

modelId string
belongs to. You can find modelId in ​Dashboard​.

passId string The unique ID of the generated pass.

30
 distributedAt string The date and time when pass is generated in ​ISO 8601 format.

HTTP Request Header

Content-Type​: application/json

Example Request Body

{
"passId": "fjnUGLFqLst9",
"distributedAt": "2018-12-10T09:41:50+08:00",
"modelId": 2126

Pass Installed Event

URL Structure

Method URL

POST Your pass installation webhook url (HTTPS is required) and will be called
by Pass2U

Name Type Description

The unique ID of the specified model which the installed pass belongs
modelId string
to. You can find modelId in ​Dashboard​.

passId string The unique ID of the installed pass.

installedAt string The date and time when pass is installed in ​ISO 8601 format.

HTTP Request Header

Content-Type​: application/json

Example Request Body

31
{
"passId": "fjnUGLFqLst9",
"installedAt": "2018-12-10T09:41:50+08:00",
"modelId": 2126

32