Apple Wallet. What is it and how to integrate your card into it

It is generally accepted that Wallet is not the most popular service in the CIS. But for the second project in a row, the customer sets the task “Make integration with Wallet.” Therefore, I decided to write this article to talk about the service as a whole and show how to integrate your product into it.

What is Wallet? It allows you to keep various types of cards (tickets, discount cards, etc.) in your phone, making life easier for product users. Moreover, it is possible to update card information via push notifications, but this is a topic for a separate article. But if you have a card/ticket/pass that can be integrated into your phone, then there is a solution for this! How to do this - read below.

Typically, your server is responsible for creating the map. The application receives the card in the form of a .pkpass file and through the application the user can add the card to Wallet.

Map structure

What is a map from a developer's point of view? The map is an archive with the extension .pkpass. It contains all the data necessary to display and operate the map. The contents of the archive are in the table below.

The following types of cards exist:

• Boarding pass:
  for plane or train. Usually the coupon is valid for one trip;
• Coupon:
  for coupons and special offers;
• Event Ticket:
  Can be used for one event or an entire season;
• Discount card:
  loyalty cards, discount or gift cards;
• General card:
  If none of the above applies to your case: for example, a card for subway travel or a gym pass.

Let's take a schematic look at the appearance of different cards. It is better to name the pictures as indicated in the table above.

Boarding card

Coupon

Event ticket

General Map

Discount card

Required fields. Contains Pass Type ID, Team ID, organization name, etc. Keys for related applications. Needed to display applications that need to be “associated” with the card. Keys to the “expiration date” of the card. Relevance keys. For example, the coordinates of the area where the map can be used, or the beginning of the event for which it is intended. Style key. At the beginning of the article, 5 types of cards for Wallet were listed. Each of them has its own style. There must be exactly one such key. Keys to the visual design of the map. In addition to the obvious, they contain information about the barcode displayed on the card. Web service keys. You can use web services to interact with the map, for example, to update it automatically. NFC keys. Contains additional information for Apple Pay transactions.

Now about everything in more detail.

What is Apple Wallet

Wallet on iPhone is a pre-installed application that stores electronic copies of various cards. This innovative service becomes a salvation for those who are against carrying large sums and dozens of cards with them.

The program allows you to link 8-10 payment instruments (depending on the model) to your smartphone and present them in various places for contactless payment. But payments are not the only thing where Apple Wallet is used. The program is popular among businessmen, drivers and students. This is due to the fact that IDs, passes, tickets, etc. are easily loaded into the service. There is no need to carry them with you, because you can use your phone at any time.

Required fields

Style Keys

JSON in this case looks like this:

"key" : "value1", "label" : "value2", "value" : "value3"

The value of the value key can be either numeric or string. However, currencyCode cannot be used together with a string value. As for auxiliaryFields and secondaryFields, there can be several of them, and it is worth keeping an eye on the length of the lines that are used in them.

Other analogues

A full-fledged analogue of WalletPasses for Android devices should not only have a Russian-language user interface, but also allow you to track current promotions, accumulate cashback using loyalty cards and make online purchases. Similar apps exist, although most still don't have all the features available in WalletPasses. Such applications include official mobile wallets from large domestic banks (Sberbank, AlfaBank), as well as the StoCard mobile program.

Visual keys

Barcode

The most important part of the map. The card identification number (for example, the physical card number or ticket number) is sewn into it. It is important that the scanner or any other tool can read codes in the required encoding.

Application Features

What's so special about the Wallet phone app: discounts and bonuses? We will present to you all the main advantages and uniqueness of this application below:

Having the application installed, as well as your club and plastic bank cards connected to it, you will never miss a single discount or profitable application from the services and stores that interest you. Also, by managing the Wallet: discounts and bonuses application, you can register for loyalty programs in all well-known online stores and well-known brand stores. With this function, you will be notified in a timely manner about the most profitable sales and promotions for you. Get a cumulative system of bonus points; it will also be convenient for you to keep track of their number and the total balance in your account;

Add all the discount cards in your wallet or pocket to the Wallet: Discounts and Bonuses application on your phone. Free yourself from excess space in your inventory;

Now you have the opportunity to issue coupons for the best deals in the city where you live or are located;

In this article, we presented you with the main advantages and capabilities of the Wallet application: discounts and bonuses for you and your smartphone.

Also, it is worth mentioning that through this application you can not only manage cards, certificates, pay in stores, etc., but also pay for all necessary services. Including traffic police fines, online purchases in online games and payments for housing and communal services.

Location

These keys are responsible for the location within which the card can be used.

How to pay with Apple Wallet

You can start using Apple Wallet immediately after linking your active card. It is important that there is a positive balance on it and that the amount in the account is sufficient to pay for a particular purchase.

Attention! In order for the payment to be approved in the store, check whether the NFS module is enabled on the device.

For contactless payment, the user must:

1. Come to the checkout with your purchase.
2. Warn the cashier about your intention to pay with your smartphone.
3. Bring the device to the terminal.
4. Click on Touch ID.
5. Wait for a notification about a successful transaction.

Keep in mind! If you have an iPhone with Face ID, then you first need to look at the screen (pass identification) and only then bring the phone to the reader.

In addition to traditional purchases, the owner of an iPhone can easily shop online and pay through the Vallet app. There is one condition - all actions must take place only through the Safari browser.

At the time of payment, you need to find Apple Pay in the list. After clicking on this service, you will have to log in to your Apple account and identify yourself using a fingerprint, face scan, or enter a PIN code.

Reverse side

On the back information part you can place additional information: terms of use, auto-renewal policy, contact information and a link to the application to which the card belongs. The figure shows the correspondence between the fields in pass.json and the appearance of the back side of the card. If the value field contains links, phone numbers, etc., they will be highlighted automatically.

So, the pictures are ready, pass.json is formed, all that remains is to put it all together. To do this, fill out manifest.json (see Table 1), where you need to include all the pictures and pass.json. It turns out something like this:

. . . . . . "pass.json" = 303c753abc39aa732ec74643d6db28348fe8a823; "strip.png" = 736d01f84cb73d06e8a9932e43076d68f19461ff; " [email protected] " = 468fa7bc93e6b55342b56fda09bdce7c829d7d46; . . . . . .

From this point on, nothing needs to be changed, since the SHA will be incorrect; in case of changes, you need to generate the SHA again.

Next, you need to create a Pass Type ID in the developer’s account and make a certificate for it. The procedure should be more or less familiar if you have previously created, for example, Provisioning profiles.

Next, go to the Keychain and export the Apple Worldwide Developer Relation Certificate (WWDR) from there as .pem.

From there we export the created Pass Type ID as .p12. At this point, the key holder will ask you to enter the password for the certificate. In this case, it is not necessary to enter a password. Please note that all further actions must be performed in one folder, where manifest.json, pass.json and pictures should already be located.

Now we need to generate a signature with which we will sign the archive. First, export the Pass Type ID and the key to it as .pem.

openssl pkcs12 -in certificate.p12 -clcerts -nokeys -out passcertificate.pem -passin pass: your_password

And

openssl pkcs12 -in certificates.p12 -nocerts -out passkey.pem -passin pass: -passout pass:new_password

Now we are ready to generate the signature. Let's do this with the command:

openssl smime -binary -sign -certfile WWDR.pem -signer passcertificate.pem -inkey passkey.pem -in manifest.json -out signature -outform DER -passin pass:password_from_previous_command

So, we have everything ready, all that remains is to collect the archive, we do this with the command:

zip -r nameOfPass.pkpass manifest.json pass.json signature logo.png icon.png

Please note that all files in which you want to include the data archive for the card (.pkpass) should be listed here. As a result, we will get a .pkpass file that can be opened on a computer. We will see a preview of the map, the appearance of which may differ from the view on the phone. All this can be done a little easier. Apple provides a signpass utility (Apple Wallet sample meterials), which takes care of all SHA calculations (you don’t have to do the manifest.json file yourself) and the work of creating signatures. To use it, you need to assemble the project and place the signpass file in the folder with all the necessary resources.

In general, the structure should look something like this:

Next we run the command:

./signpass -p wallet

Wallet is the name of the folder in which all resources are located. The output is the file wallet.pkpass. Its contents can be viewed by unzipping wallet.pkpass.

unzip wallet.pkpass

It is possible that the creation of pkpass will be carried out on the backend, in which case it will be necessary to transfer to the WWDR developers the certificate for Pass Type ID in the form of .p12 and the password for it.

In order for an application to be able to add cards to Wallet, it is necessary to enable this ability in the App ID and also enable this ability in Capabilities in the project.

This is necessary for full correct work with Wallet. Otherwise, it will not be possible to read cards from Wallet and, for example, there will be no way to understand whether our card has been added or not. It is also important to note that the team id in pass.json must match the team id, or you will have to add them manually to the entitlements and this may correct the situation, but I have not checked this.

Device requirements

The iPhone Wallet app helps you launch Apple Pay. It is through it that cards are loaded and configured.

For the contactless service to work, you need to have a suitable gadget from Apple. The device must have Face ID or Touch ID and a built-in NFC module.

These are phone models such as: 6, 6 Plus, 6s, 6s Plus, SE, 7, 7 Plus, 8, 9, 10, XR and newer.

Mac computers with Touch ID and all Apple Watches are compatible. Also iPad models (Air, Pro, mini).

On iPhones 5, 5 S and PC Mac (without an identification sensor), it is possible to work in tandem with another Apple device that has the NFS function.

Adding a map

Adding cards is very simple:

guard let passPath = Bundle.main.path(forResource: "wallet", ofType: "pkpass") else { return } let error: ErrorPointer = ErrorPointer(nilLiteral: ()) guard let passData = NSData(contentsOfFile: passPath) else { return } let pass = PKPass(data: passData as Data, error: error) let passLibrary = PKPassLibrary() passLibrary.addPasses([pass]) { (status) in print(passLibrary.containsPass(pass)) }

However, again, more often than not, the .pkpass file will need to be downloaded from your server. It's worth noting that PassKit produces fairly readable errors, so you can easily figure out what exactly was done wrong.