iOS

Retrieving Push Provisioning SDK logs

You can retrieve logs using the Push Provisioning SDK debug library. Do this in Console.app:

• Filter for TPCSDK in Console.app.

• In the Console.app window, ensure both Include Info Messages and Include Debug Messages are selected, as shown below.

Example `Console.app` filter and log level settings.

You can retrieve logs in the Production Environment. You must use the Push Provisioning SDK debug library.

Retrieving Apple Pay logs

1. Use the specific provisioning profile from Apple for the following devices:

   • iPhone: iOS Provisioning Profile.

   • iWatch: iWatch Provisioning Profile.

2. Once the application is running, the logs can be filtered using the PassbookUIService process in Console.app.

For more details, see Apple Pay Profiles and Logs.

Server errors

If you receive a server-related error, you may be able to get the API request ID from the TPCError requestId parameter. Use this request ID when you report the issue to the support team.

Common errors

Unable to add card using sandbox environment

Possible causes:

• The device is not signed in with a Sandbox iCloud account.

• The PAN in use is not a Sandbox PAN. For details, see Apple Sandbox Testing.

Push Provisioning SDK getToken/getCardDigitizationResult API still returns nil/CardNotDigitized after the card provisioning process.

Possible causes:

• For Production Environment testing, test on production devices using Ad Hoc provisioning profiles, TestFlight, or the App Store (for example, via promo codes), after the required approvals.

• The provisioning profile does not include the correct entitlements. Refer to this guide to set up entitlements.

• Your issuer application details may be misconfigured in the payment network operator (PNO) system (Visa and Mastercard). Per Apple specifications, configure issuer application details in the PNO system using the following format:

  • associatedApplicationIdentifiers: TeamId.BundleId

  • associatedStoreIdentifier: AdamId

  • appLaunchUrl: Your application's URL.

The following figure shows where to configure Application Identifiers/ADAM ID and Application URL in Mastercard.

Example Mastercard configuration for application identifiers and application URL.

Card Not Added Before T&Cs

Example “card not added before T&Cs” error.

Example logs view used to troubleshoot provisioning failures.

Enter the device SEID in the search bar in the top-right corner. This returns logs with requests and responses. Review the log output and select the request message (as shown below). The highlighted field shows data for the selected message.

For this use case, validate encryptedPassData and ephemeralPublicKey. This is the data sent from the device to the server.

In the figure below, you can also view the log archive request/response. The server response is shown in a more readable format, with the error code highlighted. The response returns error 500, which is a generic error. Resolution options are listed in the next section.

Response: ...[Other data not logged here]
{
   ...[Other data not logged here]
}
{
   statusCode = 500;
   statusMessage = "Broker Service Response exception”;
}

Example log archive response with the server error highlighted.

Possible causes:

• Cryptography error, wrong data encoding, or invalid JSON dictionary.

  Resolve this by validating your cryptography implementation and data format.

• Whitelisting (Incorrect Adam ID is whitelisted)

  This applies only to tests in the Production Environment.

  • Has the issuer requested the whitelisting of their app’s Adam ID?

  • If yes, is the issuer distributing the issuer application via TestFlight? For TestFlight, the minimum supported build must be set to iOS 10.3. When the issuer application is built for the App Store, you can move the minimum supported iOS version back to iOS 9.0 or later.

• Issue with the resources such as T&Cs and Card Art being loaded.

  This is unlikely. It typically happens in the Pre-Production Environment, where payment network portal configuration may change frequently.

  To rule this out, try adding the card manually in Apple Wallet. If you see the T&Cs, you can rule out this issue. If manual provisioning fails, contact your PNO and re-upload your T&Cs.

Ineligible card

Example ineligible card response.

Unlike the “Card Not Added Before T&Cs” scenario, the server responds with status code 200, which means the request completed successfully. However, the response indicates the card is ineligible (for example, eligibilityStatus=0).

{
   "Content-Length" = 57;
   "Content-Type" = "application/json";
   Date = "Tue, 21 May 2019 04:40:57 GMT”;
   "x-conversation-id" = 086063f209b34b84bee028a75c6af0f2;
   ...[Other data not logged here]
} 
{
   errorCode = 40403;
   ...[Other data not logged here]
}

This issue is caused by card details that are not eligible for Apple Pay (for example, the card is not allowlisted by the PNO/issuer).

Check with your PNO that the card is configured correctly.

Issuer Declines Provisioning: ‘Red Flow’ Response

Example “red flow” response shown to the end user.

A failure after the end user accepts T&Cs is often caused by a decline on the issuer side. This decline is represented by a Red Response.

This can happen if the issuer declines the attempt, or if the PNO responds on the issuer’s behalf because the response takes too long to process. Logs for this error typically show error code 40403. The device may display: “Could not add Card, Try again later or contact your card issuer for more information”.

{
   "Content-Length" = 57;
   "Content-Type" = "application/json";
   Date = "Tue, 21 May 2019 04:40:57 GMT”;
   "x-conversation-id" = 086063f209b34b84bee028a75c6af0f2;
   ...[Other data not logged here]
} 
{
   errorCode = 40403;
   ...[Other data not logged here]
}

Red flow is returned by the issuer’s PNO. Contact your PNO and provide the conversationID. The PNO can use it to identify the underlying reason.

Unknown card type

This error occurs when the bundle identifier is incorrect. Apple recommends changing the bundle identifier. An example error is shown below:

PassbookUIService         AMSCardEnrollmentEligibilityTask: [D72FE7E2] Attempting to determine card type for passTypeIdentifier: paymentpass.com.apple, serialNumber: nc.prod.cert_5395c9ae24b346e7ad08fcca25a46912

PassbookUIService         tcp_input [C127.1:3] flags=[F.] seq=1370165038, ack=1840204742, win=502 state=CLOSED rcv_nxt=1370165014, snd_una=1840204718

PassbookUIService         AMSCardEnrollmentEligibilityTask: [D72FE7E2] Card is unknown type of PKPaymentPass

PassbookUIService         PKNotifyCoalescer: unregistered for notification com.apple.NPKCompanionAgent.listener.resumed.

PassbookUIService         {public}<private>:0x282608f30 (0x282530a00): Tearing down existing connection

PassbookUIService         AMSCardEnrollmentEligibilityTask: [D72FE7E2] Found card type: 0

PassbookUIService         AMSURLRequestEncoder: [D72FE7E2] Encoding request for URL: https://p19-buy.itunes.apple.com/account/stackable/applePay/silentEnroll/eligible {

                account = <ACAccount: 0x282d2e5a0 type = iTunesStore | backingID = BE105BB6-8208-4E56-AEA9-8615DE4C093F | username = [email protected] | altDSID = 000014-10-8f1f9b5d-1c5e-4f41-b9e4-85ee3dc81e11 | DSID = 20100559835 | active = true | storefront = 143441-1,29>

                mediaType = com.apple.AppleMediaServices.accountmediatype.production

Push provisioning returns status code 1

• PPROD: Testing is not triggered using an Apple Sandbox test account. Refer to the Apple Sandbox Testing page for sandbox testing steps.

• PROD: The issuer application is not published to the App Store, which causes Apple to restrict it.

An example of the error is shown below:

//L_Stage[866:312743] [TPCSDK] ProvisionViewController addPaymentPassViewController: ephemeralPublicKey: BNEz67GTNp2YEtS/hkUDaMJh/zGjBVFbMMIYu5E4xsMoCgeCsR8Qy8A/YGnmXDCZVBpAzmhdrD+e3WpFswdU7e8=

2021-03-26 18:49:21.422819+0300 UCFS_TAS_HEEL_Stage[866:312743] [TPCSDK] ProvisionViewController addPaymentPassViewController: Create request

2021-03-26 18:49:32.050545+0300 UCFS_TAS_HEEL_Stage[866:311885] [TPCSDK] ProvisionViewController addPaymentPassViewController:didFinishAdding BEGIN

2021-03-26 18:49:32.056856+0300 UCFS_TAS_HEEL_Stage[866:311885] [TPCSDK] ProvisionViewController addPaymentPassViewController:didFinishAdding error: The operation couldn't be completed. (PKPassKitErrorDomain error 1.)

The flow is correctly initiated for TSH but MasterCard does not receive the push. In device logs the error

Push provisioning returns status code 403

This error occurs when the push provisioning flow is rejected by the issuer backend, but the flow is otherwise successful (red flow). The details of the error are shown below:

[PassbookUIService error] Received Status Code 403.

Push provisioning returns 500

This error occurs when the Apple Sandbox test account is not configured on the test device.

An example of the error is shown below:

{ 
  "Content-Length" = 49; 
  "Content-Type" = "application/json"; 
  Date = "Fri, 21 May 2021 14:06:16 GMT"; 
  Vary = "accept-language"; 
  "x-conversation-id" = 8a7e25b542b34cc9a4077fb411c1b2eb;
  "x-envoy-upstream-service-time" = 625; 
  "x-pod" = "crt-pod1"; 
  "x-pod-region" = "paymentpass.com.apple"; 
} 
{ 
  errorCode = 40456; 
  statusCode = 500; 
}