ApplePay billing contact errors

when using the PassKit framework for in-app payments on iOS, there is a specific error format that can be used to mark invalid input fields in the PKPaymentAuthorizationViewController (aka ‘payment sheet’) UI. one can choose to use either the raw NSError API, or the convenience methods on PKPaymentRequest. at the time of writing, the PKPaymentError documentation provided the following example:

// A general billing address error created with NSError
let billingAddressError = NSError.init(
    domain: PKPaymentErrorDomain,
    code: PKPaymentError.billingContactInvalidError.rawValue,
    userInfo: [
        NSLocalizedDescriptionKey:"Address has an error",
        PKPaymentErrorKey.contactFieldUserInfoKey: PKContactField.postalAddress
    ]
)

// A specific billing address error created with a convenience method
let billingAddressInvalidStreet = PKPaymentRequest.paymentBillingAddressInvalidError(
    withKey:CNPostalAddressStreetKey,
    localizedDescription: "Invalid street"
)

when such errors are returned to the PassKit framework via the various delegate method completions, they mark the appropritate form fields as invalid and display the localizedDescription. the convenience methods on PKPaymentRequest for constructing these errors are:

// For an error with contact information
paymentContactInvalidError(withContactField:localizedDescription:)

// For a shipping address that is unserviceable
paymentShippingAddressUnserviceableError(withLocalizedDescription:)

// For an error with the billing address
paymentBillingAddressInvalidError(withKey:localizedDescription:)

// For an error with the shipping address
paymentShippingAddressInvalidError(withKey:localizedDescription:)

however, the paymentContactInvalidError(...) method will only provide error feedback for invalid shipping contact fields. if you care to display errors regarding billing contact fields, you’ll need to use either the NSError or PKPaymentError APIs with specifically-configured parameters. the long form way looks like:

// verbose NSError API
let billingNameNSError = NSError(
    domain: PKPaymentErrorDomain,
    code: PKPaymentError.billingContactInvalidError.rawValue,
    userInfo: [
        NSLocalizedDescriptionKey: "Invalid billing name",
        PKPaymentErrorKey.contactFieldUserInfoKey.rawValue: PKContactField.name,
    ]
)

// slightly more compact PKPaymentError API
let billingNamePKPaymentError = PKPaymentError(
    .billingContactInvalidError,
    userInfo: [
        NSLocalizedDescriptionKey: "Invalid billing name",
        PKPaymentErrorKey.contactFieldUserInfoKey.rawValue: PKContactField.name,
    ]
)

we can fill in the missing convenience constructor via the following extension:

extension PKPaymentRequest {
    static func paymentBillingContactInvalidError(
        withContactField field: PKContactField,
        localizedDescription: String?
    ) -> PKPaymentError {
        var userInfo: [String: Any] = [
            PKPaymentErrorKey.contactFieldUserInfoKey.rawValue: field,
        ]
        if let localizedDescription = localizedDescription {
            userInfo[NSLocalizedDescriptionKey] = localizedDescription
        }

        return PKPaymentError(
            .billingContactInvalidError,
            userInfo: userInfo
        )
    }
}

// usage
let billingNameError = PKPaymentRequest.paymentBillingContactInvalidError(
    withContactField: .name, 
    localizedDescription: "Invalid billing name"
)