> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/classic-push-provisioning/developer-guide/troubleshooting/ios.md). # 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](https://developer.apple.com/services-account/download?path=/iOS/iOS_Logs/WalletFull.mobileconfig). * iWatch: [iWatch Provisioning Profile](https://developer.apple.com/services-account/download?path=/iOS/watchOS_Logs/WalletFull.mobileconfig). 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](https://developer.apple.com/bug-reporting/profiles-and-logs/?name=Apple%20Pay). ### 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](https://developer.apple.com/apple-pay/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](/classic-push-provisioning/developer-guide/sdk-configuration/ios.md) 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](https://developer.apple.com/documentation/xcode/allowing_apps_and_websites_to_link_to_your_content/defining_a_custom_url_scheme_for_your_app). 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 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

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}: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 = 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](/classic-push-provisioning/developer-guide/sandbox-testing.md) 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; } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.payments.thalescloud.io/classic-push-provisioning/developer-guide/troubleshooting/ios.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.