Article

Generating a Signature for Subscription Offers

Create a signature to validate a subscription offer using your private key.

Overview

Before you can create a signature on your server, you must complete the one-time setup to generate a private key in App Store Connect, as described in Setting Up Subscription Offers. Always use a secure connection when sending data, including the signature, between your app and server. For more information on ensuring your data’s security, see Preventing Insecure Network Connections.

To create the signature, you will need parameters that identify the product and offer, parameters generated by the server, and your private key. To generate the signature, you combine required parameters, then sign and encode the resulting string.

Combine the Parameters

In the first step of generating the signature, you need the following parameters, most of which you also supply for SKPaymentDiscount:

appBundleID

The app bundle identifier.

keyIdentifier

A string that identifies the private key you use to generate the signature. You can find this identifier in App Store Connect Users and Access > Keys, in the KEY ID column for the subscription key you generated.

productIdentifier

The subscription product identifier, productIdentifier. The app can provide this value.

offerIdentifier

The subscription discount identifier, identifier. The app can provide this value.

applicationUsername

An optional string value that you define; may be an empty string. The app can provide this value and uses it in applicationUsername.

nonce

A unique UUID value that your server defines. This value is cached for 24 hours. The string representation of the nonce used in the signature must be in lowercase.

timestamp

A timestamp your server generates in UNIX epoch time format, in milliseconds; the timestamp keeps the offer active for 24 hours.

Combine the parameters into a UTF-8 string with an invisible separator ('\u2063') between them, in the order shown:

appBundleId + '\u2063' + keyIdentifier + '\u2063' + productIdentifier + '\u2063' + offerIdentifier + '\u2063' + applicationUsername + '\u2063' + nonce + '\u2063' + timestamp

Sign the Combined String

Sign the combined UTF-8 string with the following key and algorithm:

  • The PKCS#8 private key (downloaded from App Store Connect) that corresponds to the keyIdentifier in the UTF-8 string.

  • The Elliptic Curve Digital Signature Algorithm (ECDSA) with a SHA-256 hash.

The result should be a Digital Encoding Rules (DER)-formatted binary value, which is the signature.

Encode the Signature

Base64-encode the binary signature you generated to get the final signature string. The signature string will look similar to:

MEQCIEQlmZRNfYzKBSE8QnhLTIHZZZWCFgZpRqRxHss65KoFAiAJgJKjdrWdkLUOCCjuEx2RmFS7daRzSVZRVZ8RyMyUXg==

Respond with the Signature String and Parameters

Respond to the app’s request for the signature over a secure connection, providing the encoded signature string, the nonce, timestamp, and the keyIdentifier.

See Create a Signature for information about the app’s request and how it uses the signature.

See Also

Providing Subscription Offers

Setting Up Subscription Offers

Generate a key and configure offers for auto-renewable subscriptions in App Store Connect.

Implementing Subscription Offers in Your App

Offer discounted pricing for auto-renewable subscription products to eligible subscribers.

class SKPaymentDiscount

The signed discount applied to a payment.