RESTful API

The digital passes are becoming incresingly common use around the world to substitute paper passes, reach wider audiences and speed deliveries up. The API described in this documentation allows you to create a single template to deliver multiple passes and bind information with any data server to write on them specific data. Once your end-users have accepted the passes you sent, you can update each single pass or all the passes delivered simultaneously according to your needs.

The two main digital wallets in the market are supported: Apple Wallet and Android Pay. You can use the same single template to reach both platforms and their respective protocols.

This API allows you to manipulate in many ways your wallet campaigns: you can create a template and, later on, retrive it, modify it or delete it; you order the creation of the passes by building their delivery URLs and matching their variable fields with the external source data origin of your preference. The delivery endpoint checks the platform of your end-users with your directives to know what kind of pass it will deliver. Apple Wallet format file .pkpass can be also read by several Android Apps; this platform has support for Attido Passwallet Push update service if you order Android to get that format instead of Android Pay.

The server sets up the proper endpoints to accomplish with Apple Wallet Push update protocol. You only have to order the updates and the platform will do the rest backstage. In Android Pay the passes are updated in the cloud and the devices synchronize to the last information stored.

This API follows the RESTful principles, therefore the endpoints have noun names, they have to be called with the proper HTTP verb (GET, POST, PUT or DELETE) and the larger information is sent via payload. The transactional results are sent in XML while the objects can be defined in XML or JSON. The endpoints where you interact to the server directly are signed, while those called by devices are not, due to Apple's protocol path structure.

To start a Wallet campaign you need to be registered in Messangi platform. If you are not registered, please conntact with our support team. When registered you can check your company name using Get organization name, used inside passes' metadata. The campaign requires the following resources and steps:

  1. Create a Wallet template: call the Create Wallet Template endpoint and send on payload the Wallet Template object in JSON format.
  2. Upload passes images: you have to provide from 2 up to 6 images to fill in the template. These images will be used in all the passes delivered from the server. Call the Store image file for Wallet to upload one by one.
  3. Querying: If you want to check the information you stored in the Wallet template use Get Wallet Template. Also, if you want to check the images you uploaded to support that template, use Get Wallet image file. And if you want to get a list of all the templates you created use Get Wallet Templates list.
  4. If you want to add custom data inside the passes, you must set the matches between your source data origin fields and the template fields using Set template-to-data attribute matches. Your source data origin server has to provide an endpoint to query the custom data everytime.
  5. To create and enable the final passes in the server just call Get Wallet URL list with the recipients list (phone number list only or email address list only) and you will get in response a JSON object, mapping the URL for each one of them. With that URLs your end-users will get the passes with the art of the template and the information of the template matched with your data origin according to your commands in the previous step.
  6. The URLs you get in the previous step are shortened URLs to the enpoint Wallet passes Delivery. You must not call it directly, the valid calls are just made by the previous endpoint.
  7. In order to track your campaign broadcasts you can use the Register Wallet Campaign. There you can store important metadata of each broadcast you made. To retrieve the previous information use Get Wallet broadcast.
  8. When you need to make changes to the template itself use Update Wallet template and send in the payload the Wallet Template object in JSON format.
  9. Apple requires from Wallet developers set up several endpoints to manage the protocol to register and unregister devices and passes in order to enable Apple Push Notification Service. All that work is already made inside this server with the endpoints in Register Device for Wallet updates, Register Device for PassWallet updates, Send New Pass to Wallet apps, Get changed passes list, Remove Wallet Registration and Logging errors from device to server. You only have to provide the information of your template fields, images and recipients and the server will manage all the protocol process.
  10. To send dynamic updates to your end-users' passes, use Send massive push updates for passes when changes has been made in template. But if you just want to reach a single end-user use Send single pass push update instead.
  11. Once you consider your campaign is over and you don't want your customers to get new passes from that campaign, use Delete Wallet Template to delete all the information in the server.

Overview

Given a client identificator code, returns the Organization name used as parameter in some endpoints in this API

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/organization/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Response

A String text with the Organization name related with the clientId

Overview

Stores a Wallet template in the server using a JSON object data.

URL

POST https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/{templateName}/{clientId}/{timeStamp}/{signature}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

POST https://api.messangi.com/messangi-staging/rest/message/Passbook64/templates/{templateNameEncoded}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName The name for the new template
templateNameEncoded The name for the new template encoded using base64
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Payload

A json object with proper structure of a Wallet template object. You can build this object using our java beans available herepassbookbeans.rar

	{
	"transitType":null,
	"thumbnail":null,
        "thumbnailFixed":null,
	"footer":null,
        "footerFixed":null,
	"templateName":Demo Passes for customers",
	"organization":"Company Name",
	"iBeacons":[{"major":100,"minor":10,"fixed":"f","text":"This is a beacon","status":"","uuid":"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0"}],
	"logo":"31345fa5b31a87c0590eb50d77add0975649139a",
        "logoFixed":"f",
	"passTypeId":"pass.com.messangi.passbook",
	"templateSHA1":"90c382c79b7534a58c87f27e97ef1ce541831197",
	"strip":null,
        "stripFixed":null,
	"background":null,
        "backgroundFixed":null,
	"lastUpdated":"30-08-2015 12:11:25",
	"expirationDate":"2017-02-07T12:10:00-05:00",
	"description":"Test wallet",
	"serial":"LYWcpB3nzMX1Cpmx6OFcfK1GlZNtm_FnnOeFY7CONvlZuBpcL5BWHoa3xKAd7bxqKBhD1OM2Hh45TGnEb6MFi6pIu58wp-cIzzeAx3BQboQ*",
	"relevantDate":"2017-01-04T12:10:00-05:00",
	"barcodeContent":"https://www.google.com/",
	"barcodeLabel":"Google Official Web Page",
	"backgroundColor":"#2255ff",
	"labelColor":"#ab45b0",
	"foreColor":"#38aab1",
	"descriptionFixed":"f",
	"logoTextFixed":"f",
	"relevantDateFixed":"f",
	"expirationDateFixed":"f",
	"barcodeContentFixed":"f",
	"barcodeLabelFixed":"f",
	"icon":"31345fa5b31a87c0590eb50d77add0975649139a",
        "iconFixed":"f",
	"maximumDistance":100,
	"barcodeType":"QR",
	"locations":[{"latitude":37.43900253544606,"longitude":-122.1458918105788,"status":"","label":"Boulevard Arturo Uslar Pietri, Caracas, Miranda, Venezuela"}],
	"logoText":"testqa",
	"passbookType":"storecard",
	"fields":[{"fixed":"f","status":"","label":"Label Auxiliary","place":"AUXILIARY","value":"Content Auxiliary"},{"fixed":"f","status":"","label":"Label Back Side","place":"BACK","value":"Content Back Side"},{"fixed":"f","status":"","label":"Label Header","place":"HEADER","value":"Content Header"},{"fixed":"f","status":"","label":"Label Primary","place":"PRIMARY","value":"Ogangi"},{"fixed":"f","status":"","label":"Label Secondary","place":"SECONDARY","value":"Content Secondary"}]
	}


Simple attributes

Attribute Name Description Possible Values
organization Your company name string as registered in the server Can be empty, written by server
templateName Name of the template you assigned Any non-null string lesser than 150 characters
serial The serial identificator of the template. Assigned by the server Can be empty, this field is written only by server
passbookType The Apple Wallet format used in the template One of the following: “boarding”, “storecard”, “coupon”, “event”, “generic”
transitType Applies only if passbookType is “boarding” One of the following: “air”, “boat”, “bus”, “train”, “generic”
logo SHA1 of the logo image Hexadecimal string of 40 chars
logoFixed Defines if logo image is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
icon SHA1 of the thumbnail image Hexadecimal string of 40 chars
iconFixed Defines if icon image is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
strip SHA1 of the thumbnail image Hexadecimal string of 40 chars or null if not present
stripFixed Defines if strip image is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
background SHA1 of the thumbnail image Hexadecimal string of 40 chars or null if not present
backgroundFixed Defines if background image is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
thumbnail SHA1 of the thumbnail image Hexadecimal string of 40 chars or null if not present
thumbnailFixed Defines if thumbnail image is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
footer SHA1 of the footer image Hexadecimal string of 40 chars or null if not present
footerFixed Defines if footer image is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
labelColor RGB for labels color (the captions of fields) Hexadecimal color string of 6 chars with character # at the beggining
foreColor RGB for texts color (the content of fields) Hexadecimal color string of 6 chars with character # at the beggining
backgroundColor RGB for background color of the pass (if no background image available) Hexadecimal color string of 6 chars with character # at the beginning
description Brief text that describes the purpose of the passes Any non-null string lesses than 1000 characters
descriptionFixed Defines if description text is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
logoText The title text in the upper center of the passes Any string lesser than 20 characters
logoTextFixed Defines if description text is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
barcodeType Passes barcode format One of the following: “QR”, “PDF-417”, “Aztec”
barcodeContent The text codified on barcode Any string lesser than 500 characters
barcodeContentFixed Defines if barcode content is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
barcodeLabel Label below barcode Any string lesser than 50 characters
barcodeLabelFixed Defines if barcode label is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
maximumDistance The maximum distance to show notifications of geolocation A non-negative integer number
relevantDate The metadata relevant date to store in passes. Used to show notifications. W3C date format “YYYY-MM-DD'T'hh:mm:ss(+/-)hh:mm”
relevantDateFixed Defines if relevant date is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
expirationDate The metadata expiration date to store in passes. When a pass is expired, the barcode is blurred W3C date format “YYYY-MM-DD'T'hh:mm:ss(+/-)hh:mm”
expirationDateFixed Defines if expiration date is fixed (all passes) or variable (specific per pass) One of the following: “f”, “v”
templateSHA1 A control SHA1 checksum of the template. Written by server Can be empty
passTypeId Apple Developer Certificate Wallet Type. Written by server Can be empty
lastUpdated Timestamp of the last moment when the template was edited. Written by server Can be empty. Format used “DD-MM-YYYY hh:mm:ss”

Array attributes

Attribute Name Description Possible Values
fields JSON array of template text fields, with keys: label (caption), place (place name in the layout), value (content of field), fixed (fixed of variable), status (empty) label: non-null string lesser than 50 chars; place: one of the following: “HEADER”, “PRIMARY”, “SECONDARY”, “AUXILIARY”, “BACK”; value: non-null string lesser than 1000 chars; fixed: one of the following: “f”, “v; status: must always be empty (used for internal control only)
iBeacons JSON array of iBeacons ids for indoor notifications, with keys: uuid(string), major (numeric), minor (numeric), fixed (string) and text (string), status (empty) uuid uses only valid strings used on iBeacons identification; major and minor must be integer values between 0 and 65535; fixed indicates if the notification for the beacon will be a fixed text or variable (using source data origin) use literal “f” for fixed and “v” for variable; status must always be empty (used for internal control only)
locations JSON array of geolocation places for notifications with keys: latitude (long), longitude (long), label (string), status(empty) latitude: a long number between -90 and 90; longitude: a long number between -180 and 180; label: a non-null string lesser than 100 chars; status must always be empty (used for internal control only)

Response

	<TransactionResult>
		<successful>true</successful>
		<message>
			Template: Successful operation - Fields: Successful operation - Locations: Successful operation - iBeacons: Successful operation 
		</message>
		<extraInfo></extraInfo>
	</TransactionResult>

The response XML above will have as many repetitions as fields, locations and / or iBeacons the template had

Overview

Sends a specific image of a Wallet template stored on server. It's useful to verify if an image is available and check the image art itself.

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/image/{templateName}/{filename}/{clientId}/{timeStamp}/{signature}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

GET https://api.messangi.com/messangi-staging/rest/message/Passbook64/templates/image/{templateNameEncoded}/{filename}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName The name of the Wallet template
templateNameEncoded The name of the Wallet template encoded using base64
filename Role name for the file according to Wallet specification (must include file extension .png)
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The requested PNG image file.

Overview

Creates a new file for a support Wallet image. It stores the image in three different sizes automatically, to comply Apple Wallet standard (non-retina, retina and retina HD).

URL

POST https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/image/{templateName}/{filename}/{clientId}/{timeStamp}/{signature}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

POST https://api.messangi.com/messangi-staging/rest/message/Passbook64/templates/image/{templateNameEncoded}/{filename}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName The name of the Wallet template
templateNameEncoded The name of the Wallet template encoded using base64
filename Name for the file according to Wallet specification (without file extension)
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

The Apple Wallet specification has only this 6 names allowed: logo, icon, strip, background, thumbnail and footer. The first 2 are mandatory, while the others are optional and their use depends on Wallet type

Payload

The Input Stream of Multipart data from the original file.

Response

Returns HTTP Status 200 if the file is successfully stored, HTTP Status 500 otherwise

Overview

Lists the main information about all templates related to a specific organization.

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/{filter}/{initialRow}/{finalRow}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
initialRow First row number in the list
finalRow Last row number in the list
filter The expression to filter list names
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Response

A list with data of the tenmplates: template name, Wallet type, number of images uploaded, barcode type, number of locations associated and number of iBeacons associated. All other properties are ignored and presented as null

Example response XML:

	<PassbookTemplateList>
		<records>16</records>
		<listPassbook>
			<organization xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<templateName>Demo pass for customers</templateName>
			<passbookType>storecard</passbookType>
			<transitType xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<logo>31345fa5b31a87c0590eb50d77add0975649139a</logo>
			<icon>31345fa5b31a87c0590eb50d77add0975649139a</icon>
			<strip xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<background xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<footer xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<thumbnail xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<backgroundColor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<labelColor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<foreColor xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<description xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<descriptionFixed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<serial>
				LYWcpB3nzMX1Cpmx6OFcfK1GlZNtm_FnnOeFY7CONvlZuBpcL5BWHoa3xKAd7bxqKBhD1OM2Hh45TGnEb6MFi6pIu58wp-cIzzeAx3BQboQ*
			</serial>
			<logoText xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<logoTextFixed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<relevantDate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<relevantDateFixed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<barcodeType>QR</barcodeType>
			<barcodeContent xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<barcodeContentFixed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<barcodeLabel xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<barcodeLabelFixed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<maximumDistance>0</maximumDistance>
			<expirationDate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<expirationDateFixed xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<templateSHA1 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<passTypeId xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<lastUpdated xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:nil="true"/>
			<fields/>
			<locations>
				<locations>
					<label/>
					<latitude>0.0</latitude>
					<longitude>0.0</longitude>
				<status/>
				</locations>
			</locations>
			<iBeacons>
				<iBeacons>
					<fixed/>
					<major>0</major>
					<minor>0</minor>
					<status/>
					<text/>
					<uuid/>
				</iBeacons>
			</iBeacons>
		</listPassbook>	
		<listPassbook>
			(...)	
		</listPassbook>
	</PassbookTemplateList>

The list will contain as much templates' previews as the selected range. The shorter that range be, the faster will be the server response.

Don't try to pick more attributes than the listed above from each template (template name, Wallet type, number of images uploaded, barcode type, number of locations associated and number of iBeacons associated); to get the full information of a template request it via getPassbookTemplate endpoint.

Overview

Deletes a Wallet template from the server and all its descendent data.

URL

DELETE https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/{templateName}/{clientId}/{timeStamp}/{signature}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

DELETE https://api.messangi.com/messangi-staging/rest/message/Passbook64/templates/{templateNameEncoded}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName The name of the template to delete
templateNameEncoded The name of the template to delete encoded using base64
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Response

	<TransactionResult>
		<successful>true</successful>
		<message>Successful operation</message>
		<extraInfo></extraInfo>
	</TransactionResult>

Overview

Returns a JSON object with a whole template data with its dependecies (fields, locations and iBeacons)

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/{templateName}/{clientId}/{timeStamp}/{signature}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

GET https://api.messangi.com/messangi-staging/rest/message/Passbook64/templates/{templateNameEncoded}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName The name for the template to be sent
templateNameEncoded The name for the template to be sent encoded using base64
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Response

The JSON Object of the requested Template

	{
	"transitType":null,
	"thumbnail":null,
	"footer":null,
	"templateName":Demo Passes for customers",
	"organization":"Company Name",
	"iBeacons":[{"major":100,"minor":10,"fixed":"f","text":"testqa","status":"","uuid":"E2C56DB5-DFFB-48D2-B060-D0F5A71096E0"}],
	"logo":"31345fa5b31a87c0590eb50d77add0975649139a",
	"passTypeId":"pass.com.messangi.passbook",
	"templateSHA1":"90c382c79b7534a58c87f27e97ef1ce541831197",
	"strip":null,
	"background":null,
	"lastUpdated":"30-09-2016 12:11:25",
	"expirationDate":"2017-02-07T12:10:00-05:00",
	"description":"Test wallet",
	"serial":"LYWcpB3nzMX1Cpmx6OFcfK1GlZNtm_FnnOeFY7CONvlZuBpcL5BWHoa3xKAd7bxqKBhD1OM2Hh45TGnEb6MFi6pIu58wp-cIzzeAx3BQboQ*",
	"relevantDate":"2017-01-04T12:10:00-05:00",
	"barcodeContent":"https://www.ogangi.com/",
	"barcodeLabel":"Ogangi Official Web Page",
	"backgroundColor":"#2255ff",
	"labelColor":"#ab45b0",
	"foreColor":"#38fab1",
	"descriptionFixed":"f",
	"logoTextFixed":"f",
	"relevantDateFixed":"f",
	"expirationDateFixed":"f",
	"barcodeContentFixed":"f",
	"barcodeLabelFixed":"f",
	"icon":"31345fa5b31a87c0590eb50d77add0975649139a",
	"maximumDistance":100,
	"barcodeType":"QR",
	"locations":[{"latitude":37.43900253544606,"longitude":-122.1458918105788,"status":"","label":"Boulevard Arturo Uslar Pietri, Caracas, Miranda, Venezuela"}],
	"logoText":"testqa",
	"passbookType":"storecard",
	"fields":[{"fixed":"f","status":"","label":"Label Auxiliary","place":"AUXILIARY","value":"Content Auxiliary"},{"fixed":"f","status":"","label":"Label Back Side","place":"BACK","value":"Content Back Side"},{"fixed":"f","status":"","label":"Label Header","place":"HEADER","value":"Content Header"},{"fixed":"f","status":"","label":"Label Primary","place":"PRIMARY","value":"Ogangi"},{"fixed":"f","status":"","label":"Label Secondary","place":"SECONDARY","value":"Content Secondary"}]
	}

Overview

Edits a Wallet template data from a JSON object data.

URL

PUT https://api.messangi.com/messangi-staging/rest/message/Passbook/templates/{templateName}/{clientId}/{timeStamp}/{signature}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

PUT https://api.messangi.com/messangi-staging/rest/message/Passbook64/templates/{templateNameEncoded}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName The name for the template to modify
templateNameEncoded The name for the template to modify encoded using base64
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Payload

A json object with proper structure of a Wallet template object. You can build this object using our java beans available here<INSERTE AQUI ZIP DE BEANS>

Response

	<TransactionResult>
		<successful>true</successful>
		<message>Successful operation</message>
		<extraInfo></extraInfo>
	</TransactionResult>

Overview

Returns the Wallet URL list in a JSON object for passes distribution

URL

POST https://api.messangi.com/messangi-staging/rest/message/Passbook/urlList/{templateName}/{listId}/{sourceDataOrigin}/{timezone}/{campaignName}/{clientId}/{timeStamp}/{signature}?androidPkpass={true|false}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

POST https://api.messangi.com/messangi-staging/rest/message/Passbook64/urlList/{templateNameEncoded}/{listId}/{sourceDataOrigin}/{timezone}/{campaignName}/{clientId}/{timeStamp}/{signature}?androidPkpass={true|false}

Parameters

Parameter Name Description
templateName The name for the template to modify
listId A numeric identificator for the source list
sourceDataOrigin The URL where specific data for passes is available. It must be BASE64 encoded.
timezone Timezone used
campaignName An identificator name for the Wallet campaign
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example
androidPkpass Use this query param in true to force the delivery of .pkpass file in Android devices. In false or absence, Android Pay passes are delivered to Android devices

Payload

A JSON array with all the target recipients. For example if you deliver by SMS:

	[
		"15417543010",
		"15572681217",
		"15671638489",
		(...)
	]

If you deliver by email:

	[
		"rosesmith@gmail.com",
		"johndoe@gmail.com",
		"danielroberts@outlook.com",
		"bmontgomery@yahoo.com",
		(...)
	]

Response

A JSON object with recipients as keys and urls as values. If you deliver by SMS:

	{
		"15417543010": "http://your_shortener.com/r/60c71492-e",
		"15572681217": "http://your_shortener.com/r/986a118b-c",
		"15671638489": "http://your_shortener.com/r/9bb40219-9",
		(...)
	}

If you deliver by email:

	{
		"rosesmith@gmail.com": "http://your_shortener.com/r/3ba4ee97-2",
		"johndoe@gmail.com": "http://your_shortener.com/r/e2c83f97-4",
		"danielroberts@outlook.com": "http://your_shortener.com/r/d576d2ac-e",
		"bmontgomery@yahoo.com": "http://your_shortener.com/r/08b5e4e0-1"
		(...)
	}

The base URL your_shortener.com will be set up at Messangi registration. You can rebrand that URL whenever you want contacting support team before you deliver your passes

Overview

Stores in the server the mathes (mapping) between the Wallet template and the source data origin list attributes.

You can edit the mapping between template and origin list as many times as needed

URL

POST https://api.messangi.com/messangi-staging/rest/message/Passbook/matches/{templateName}/{sourceDataOrigin}/{listId}/{clientId}/{timeStamp}/{signature}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

POST https://api.messangi.com/messangi-staging/rest/message/Passbook64/matches/{templateNameEncoded}/{sourceDataOrigin}/{listId}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName Name of the Wallet template you are using to match with your data origin
templateNameEncoded Name of the Wallet template you are using to match with your data origin encoded using base64
sourceDataOrigin The URL where specific data for passes is available. It must be BASE64 encoded.
listId A numeric identificator for the source list
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Your source data origin server has to have the following endpoint signature for SMS broadcasts: your_server_base_url/rest/internal/getSMSListValues/{idList}/{mobileNumber}. And the following endpoint signature for Email broadcasts: your_server_base_url/rest/internal/getEmailListValues/{idList}/{email}.

IMPORTANT: your endpoints have to answer only with a JSON object, with the id names as keys and fields content as values. For instance:

Call to https://www.example.com/rest/internal/getSMSListValues/2530/584161234578

Response:

	{
	"Name":"John Doe", 
	"Department": "Sales", 
	"Points", 100, 
	"Code": "1B487-4GT"
	}

Payload

A JSON object with template variable attributes as keys and soure data origin list attributes as values. Every template sector has a specific notation, use only those that applies to your template:

Wallet template sector Notation to use in matches keyset
Pass field, header fields.HEADER.{field_label}
Pass field, primary fields.PRIMARY.{field_label}
Pass field, secondary fields.SECONDARY.{field_label}
Pass field, auxiliary fields.AUXILIARY.{field_label}
Pass field, back side fields.BACK.{field_label}
Pass barcode label barcode.label
Pass barcode content barcode.content
Pass logo image pictures.logo
Pass icon image pictures.icon
Pass strip image pictures.strip
Pass background image pictures.background
Pass footer image pictures.footer
Pass thumbnail image pictures.thumbnail
Pass logo text logoText
Metadata relevant date date.relevant
Metadata expiration date.expiration
Metadata for iBeacons ibeacons.{uuid}.{major}.{minor}
Metadata description description

Please when sending your matches JSON follow strictly the notation above. If not your passes will be delivered misformed.

Response

	<TransactionResult>
		<successful>true</successful>
		<message>Successful operation</message>
		<extraInfo></extraInfo>
	</TransactionResult>

Overview

Stores in the server a record of your broadcast, with some useful metadata. It's a record only function, it does not fire a broadcast itself.

URL

POST https://api.messangi.com/messangi-staging/rest/message/Passbook/broadcast/{beginDate}/{serial}/{sourceDataOrigin}/{listType}/{listId}/{pushMode}/{pushText}/{attachment}/{recipientsNumber}/{changedField}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
beginDate A timestamp of control in this format: HH-mm-ss_dd-MM-yyyy
serial The serial assigned to your template by the server. You can consult it by calling getPassbookTemplate and taking the serial attribute
sourceDataOrigin The URL where specific data for passes is available. It must be BASE64 encoded.
listType Set 1 for SMS broadcast, 2 for Email broadcast
listId A numeric identificator for the source list
pushMode Set true if your broadcast was to deliver a push update, set false otherwise
pushText If the broadcast was to deliver a push update, set a reference text to know the purpose of the update, otherwise set null
attachment Set true if you sent to your customers the pass attached, false if you sent an URL.
recipientsNumber The number of recipients that your broadcast list has
changedField For the push updates, name of one of the fields changed if you want to trigger notifications
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Response

	<TransactionResult>
		<successful>true</successful>
		<message>Successful operation</message>
		<extraInfo></extraInfo>
	</TransactionResult>

Overview

Returns a list with all the Wallet broadcasts registered using the registration endpoint.

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/broadcast/{templateName}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName The name for the template to modify
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Response

A JSON array with all the broadcast that were registered before. For example:

	[
		{"id":133,"beginDate":"11-09-52_27-01-2016","serial":"od283XOROduIF0o5r1-2S0e_NZInA124pySdvsTiDl0ERdmwEtHc-iD_D57AhYA3","listType":2,"listIndex":"https://www.messangi.com/messangi_mmc","listId":281,"pushMode":false,"pushText":"null","attachment":false,"recipientsNumber":3, "changedField":null},
		{"id":281,"beginDate":"04-40-42_29-02-2016","serial":"od283XOROduIF0o5r1-2S0e_NZInA124pySdvsTiDl0ERdmwEtHc-iD_D57AhYA3","listType":1,"listIndex":"http://test.me.syniverse.com/messangi_mmc","listId":4433,"pushMode":false,"pushText":"null","attachment":false,"recipientsNumber":3, "changedField":null},
		(...)
 
	]

Overview

Sends the .pkpass file for Apple devices (iPhone and iPod) or gives the Android Pay button for Android devices and iPads. This endpoint is called with the URL created in Get Wallet URL list

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/delivery/{organization}?{templateID=...}&{authenticationToken=...}&{androidPkpass=...}&{clientId=...}

Parameters

Parameter Name Description
organization Your organization name as registered in the server. Can be retrieved using getOrganization endpoint
templateID The template name encrypted with internal algorithms inside the server
authenticationToken The single pass identificator assigned by the server to each pass
androidPkpass When true delivers .pkpass file in Android, otherwise delivers Android Pay pass
clientId Your client Id assigned to access the platform

You must NOT call this endpoint directly. All the valid calls are build in the Get Wallet URL list step. These URLs point to this endpoint with the proper arguments.

Response

The response of this endpoint will depend on the platform and kind of the end-user device:

  • Delivers .pkpass file of the Apple Wallet pass if the end-user device is an iPhone or an iPod, or if androidPkpass parameter is true.
  • Delivers Save to Android Pay Button to deliver Android Pay pass if the end-user device has Android OS or is an iPad (Apple iPad hasn't Apple Wallet available).

Overview

Fires massive updates in the end-users devices that have already downloaded the passes. The server sends APNS to Apple Devices and updates the Android Pay passes in the cloud for Android Devices.

When your customers get the passes and add them in their devices, the server tracks their platform, then when you order a massive update the server will know what will be the right action to perform for each pass.

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/update/sendPush/{templateName}/{clientId}/{timeStamp}/{signature}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

GET https://api.messangi.com/messangi-staging/rest/message/Passbook64/update/sendPush/{templateNameEncoded}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName The name for the base template of the passes you want to update
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Response

	<TransactionResult>
		<successful>true</successful>
		<message>Successful operation</message>
		<extraInfo></extraInfo>
	</TransactionResult>

Overview

Fires APNS to every Apple device that registered a specific pass and updates the pass in Android Pay cloud.

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/update/sendPushPass/{templateName}/{recipient}/{listId}/{sourceDataOrigin}/{clientId}/{timeStamp}/{signature}

If you want to use special characters in template name just encode it using base64 and call this endpoint instead of the previous one:

GET https://api.messangi.com/messangi-staging/rest/message/Passbook64/update/sendPushPass/{templateNameEncoded}/{recipient}/{listId}/{sourceDataOrigin}/{clientId}/{timeStamp}/{signature}

Parameters

Parameter Name Description
templateName The name for the base template of the passes you want to update
recipient The identifier of the recipient that is intended to get the updates. It can be a phone number (when sent via SMS) or email address (when sent via Email)
listId A numeric identificator for the source list
sourceDataOrigin The URL where specific data for passes is available. It must be BASE64 encoded.
clientId Your client Id assigned to access the platform
timeStamp The number of milliseconds since January 1, 1970. You can easly produce it in Java with getTime() method on a Date object
signature The unique SHA256 signature for this call, it involves all input parameters. To learn about generating the correct signature please visit our Java Example

Response

	<TransactionResult>
		<successful>true</successful>
		<message>Successful operation</message>
		<extraInfo></extraInfo>
	</TransactionResult>

Overview

Follows the Apple Wallet URL protocol to set up the proper end point that is called by Apple devices when a pass is added to the wallet app. Once a pass is registered, the app registers the device on the server.

URL

POST https://api.messangi.com/messangi-staging/rest/message/Passbook/update/v1/devices/{deviceLibraryId}/registrations/{passTypeId}/{serial}

Parameters

Parameter Name Description
deviceLibraryId A unique identifier that is used to identify and authenticate this device in future requests.
passTypeId
serial The serial assigned to the pass's template by the server. You can consult it by calling getPassbookTemplate and taking the serial attribute

The Authorization header is supplied; its value is the word ApplePass, followed by a space, followed by the pass’s authentication token as asigned by the server.

Payload

The POST payload is a JSON dictionary containing a single key and value:

pushToken: The push token that the server can use to send push notifications to this device.

Response

  • If the serial number is already registered for this device, returns HTTP status 200.
  • If registration succeeds, returns HTTP status 201.
  • If the request is not authorized, returns HTTP status 401.
  • Otherwise, returns the appropriate standard HTTP status.

Overview

Follows the Attido PassWallet URL protocol to set up the proper end point that is called by Android devices when a pass is added to the Passwallet app. This Android app reads and renders properly the .pkpass file format of Apple Wallet passes. Once a pass is registered, the app registers the device on the server.



URL

POST https://api.messangi.com/messangi-staging/rest/message/Passbook/update/v1/devices/{deviceLibraryId}/registrations_attido/{passTypeId}/{serial}

Parameters

Parameter Name Description
deviceLibraryId A unique identifier that is used to identify and authenticate this device in future requests.
passTypeId The pass's type, as specified in the server.
serial The serial assigned to the pass's template by the server. You can consult it by calling getPassbookTemplate and taking the serial attribute

Header

The Authorization header is supplied; its value is the word “Attido Pass”, followed by a space, followed by the pass's authentication token as specified in the pass.

Payload

The POST payload is a JSON dictionary, containing two key and value pairs:

  1. pushToken: The pushtoken that the server can use to send push notifications to this device.
  2. pushServiceUrl: The URL of Attido’s web service for posting update notifications to devices.

Response

  • If the serial number is already registered for this device, return HTTP status 200.
  • If registration succeeds, return HTTP status 201.
  • If the request is not authorized, return HTTP status 401.
  • Otherwise, return the appropriate standard HTTP status.

Overview

The endpoint that is called by the devices to ask for the new .pkpass file when updating process is activated. Follows the Apple Wallet URL protocol to set up the proper endpoint that is called by Apple devices when a new version of a pass is requested.

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/update/v1/passes/{passTypeId}/{serial}

Parameters

Parameter Name Description
passTypeId The pass's type, as specified in the server.
serial The serial assigned to the pass's template by the server. You can consult it by calling getPassbookTemplate and taking the serial attribute

Header

The Authorization header is supplied; its value is the word ApplePass, followed by a space, followed by the pass's authentication token as specified in the pass.

Response

  • If request is authorized, returns HTTP status 200 with a payload of the pass data.
  • If the request is not authorized, returns HTTP status 401.
  • Otherwise, returns the appropriate standard HTTP status.

Overview

Sends to devices the list of all the passes that have changed on the same server sionce

URL

GET https://api.messangi.com/messangi-staging/rest/message/Passbook/update/v1/devices/{deviceLibraryId}/registrations/{passTypeId}?{passesUpdatedSince=...}

Parameters

Parameter Name Description
deviceLibraryId A unique identifier that is used to identify and authenticate the device.
passTypeId The pass's type, as specified in the server.
passesUpdatedSince A tag from a previous request. (optional)

Response

If the passesUpdatedSince parameter is present, returns only the passes that have been updated since the time indicated by tag. Otherwise, returns all passes.

Exmaple:

	{"lastUpdated":"30-06-2016 14:25:02", "serialNumbers":["Gizk4PDHPN64TjIOjuDRczu99ngU_ZBb71Cfp43qHqqrQBcIdLpU9JeU7FQUnaLJTc_RGF-N3UsZokZ91F_fQpuDmVfy4fqqjPqDagXVIFQ*", "kuofjNEweWz9oFdbhtyAKPc7W9ldCIAiDnlsow7FbbLxc71TMdgBnXGZreQMy1gK", (...)]}

Overview

Deletes from the server the registration of a Wallet pass.

URL

DELETE https://api.messangi.com/messangi-staging/rest/message/Passbook/update/v1/devices/{deviceLibraryId}/registrations/{passTypeId}/{serial}

Parameters

Parameter Name Description
deviceLibraryId A unique identifier that is used to identify and authenticate the device.
passTypeId The pass's type, as specified in the server.
serial The serial assigned to the pass's template by the server. You can consult it by calling getPassbookTemplate and taking the serial attribute

Header

The Authorization header is supplied; its value is the word ApplePass, followed by a space, followed by the pass's authentication token as specified in the pass.

Response

  • If disassociation succeeds, returns HTTP status 200.
  • If the request is not authorized, returns HTTP status 401.
  • Otherwise, returns the appropriate standard HTTP status

Overview

When some error occurs in Wallet app, the device calls this endpoint to notify the server the description of the malfunction.

URL

POST https://api.messangi.com/messangi-staging/rest/message/Passbook/update/v1/log

Payload

The POST payload is a JSON dictionary, containing a single key and value:

logs (string): An array of log messages as strings.

Response

Returns HTTP status 200.