Samsung IAP ISN Payload

The Samsung In-App Purchase (IAP) Instant Server Notification (ISN) contains registered and private claims.

Because event types and content within the payload is continually added (content that already exists is not deleted), handling the notifications that are sent to your server requires some flexibility.

The payload is encoded in base64 format. When it is decoded, it is in JSON format.

The following events are reported in the notification and are explained in the Data Claims section below:

Example encoded payload

eyJpc3MiOiJpYXAuc2Ftc3VuZ2FwcHMuY29tIiwic3ViIjoiRVZFTlRfTkFNRSIsImF1ZCI6WyJjb20ucGFja2FnZS5uYW1lIl0sIm5iZiI6MTcxNzIwNCwiaWF0IjoxNzE3MjA0LCJkYXRhIjp7InNlbGxlck5hbWUiOm51bGwsImNvbnRlbnROYW1lIjoiTWFydGluZSJ9LCJ2ZXJzaW9uIjoiMi4wIn0

Example decoded payload

{
"iss": "iap.samsungapps.com",
"sub": "EVENT_NAME",
"aud": [ "com.package.name" ],
"nbf": 1717204200,
"iat": 1717204200,
"data": {..},
"version": "2.0"
}

Claims set properties

Claim Name

Claim Type

Value Type

Description

iss

registered

string

Always iap.samsungapps.com.

sub

registered

string

Type of event that occurred.

  • ITEM_PURCHASED: The user successfully purchased the item.
  • ITEM_REFUNDED: The purchased item is refunded to the customer.
  • ARS_SUBSCRIBED: The subscription has started.
  • ARS_UNSUBSCRIBED: The subscription has ended or is cancelled.
  • ARS_REFUNDED: The subscription payment, at any point during the current subscription period, is refunded to the subscriber.
  • ARS_RENEWED: The subscription has been renewed by the subscriber.
  • ARS_PRICECHANGE_AGREED: The subscriber has consented or not consented to a subscription price change.
  • ORDER_HISTORY_DELETED: The listed order details are deleted. Receipts and subscriptions cannot be retrieved using the specified ID.
  • TEST: This is a test notification sent using Seller Portal.
aud

registered

string

The package name of the content.

iat

registered

number

The time at which the JWT was issued (Unix epoch time).

nbf

registered

number

The time at which the JWT can be accepted for processing (Unix epoch time).

data

private

json

Detailed payload for each notification based on the event type (sub). See Data claims for more information about the data claims payload.

version

private

string

The version of the Samsung IAP ISN service. The current version, which is JWT-based, is 2.0.

Data claims

The following are the data claims that may be included in the ISN, based on the event type.

Item purchased

The user successfully purchased the item.

Example

"data" : {
   "itemId": "one_gallon_gas",
   "orderId": "S20240601KRA0010001",
   "purchaseId": "579cc7245d57cc1ba072b81d06e6f86cd49d3da63854538eea68927378799a37",
   "testPayYn": "N",
   "betaTestYn": "N",
   "passThroughParam": null
}

Properties

Name

Value

Description

itemId

string

ID of item purchased.

orderId

string

Order ID on the receipt delivered to the user.

purchaseId

string

The purchase ID you used with the receipt verification API.

testPayYn

string

Y: The item was purchased by a licensed tester in IAP test mode.
N: The item was purchased in IAP production mode.
See IAP test mode conditions for more information.

betaTestYn

string

Y: The item was purchased during a closed beta test.
N: The item was not purchased during a closed beta test.
See IAP test mode conditions for more information.

passThroughParam

string

Transaction ID you created as a security enhancement when requesting a payment, and is delivered only when entered when requesting a payment.

Item refunded

The purchased item is refunded to the customer.

Example

"data" : {
   "orderId": "S20240601KRA0010001",
   "purchaseId": "579cc7245d57cc1ba072b81d06e6f86cd49d3da63854538eea68927378799a37",
   "testPayYn": "N",
   "betaTestYn": "N"
}

Properties

Name

Value

Description

orderId

string

Order ID on the receipt delivered to the user.

purchaseId

string

The purchase ID you used with the receipt verification API.

testPayYn

string

Y: The item was purchased by a licensed tester in IAP test mode.
N: The item was purchased in IAP production mode.
See IAP test mode conditions for more information.

betaTestYn

string

Y: The item was purchased during a closed beta test.
N: The item was not purchased during a closed beta test.
See IAP test mode conditions for more information.

Subscription started

The subscription has started.

Example

"data" : {
   "itemId": "weekly_fuel",
   "orderId": "S20240601KRA0010009",
   "purchaseId": "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2",
   "paymentPlan": "Regular",
   "scheduledTimeOfRenewal": 1717809005,
   "testPayYn": "N",
   "betaTestYn": "N"
}

Properties

Name

Value

Description

itemId

string

ID of item purchased.

orderId

string

Order ID on the receipt delivered to the user.

purchaseId

string

The purchase ID you used with the receipt verification API.

paymentPlan

string

Product plan applied to the current user (for example, FreeTrial / TieredPrice / Regular).

scheduledTimeOfRenewal

number

The next subscription renewal date, in Unix epoch time.

testPayYn

string

Y: The item was purchased by a licensed tester in IAP test mode.
N: The item was purchased in IAP production mode.
See IAP test mode conditions for more information.

betaTestYn

string

Y: The item was purchased during a closed beta test.
N: The item was not purchased during a closed beta test.
See IAP test mode conditions for more information.

Subscription ended

The subscription has ended or is cancelled and is not renewed. The subscription is still available until the end of the current subscription period.

Example

"data" : {
   "firstOrderId": "S20240601KRA0010009",
   "firstPurchaseId": "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2",
   "testPayYn": "N",
   "betaTestYn": "N",
   "validUntil": 1717809005
}

Properties

Name

Value

Description

firstOrderId

string

The order ID on the first receipt delivered to the subscriber.

firstPurchaseId

string

The purchase ID you used with the receipt verification API.

testPayYn

string

Y: The item was purchased by a licensed tester in IAP test mode.
N: The item was purchased in IAP production mode.
See IAP test mode conditions for more information.

betaTestYn

string

Y: The item was purchased during a closed beta test.
N: The item was not purchased during a closed beta test.
See IAP test mode conditions for more information.

validUntil

number

The subscription expiration date, in Unix epoch time.

Subscription refunded

The subscription payment, at any point during the current subscription period, is refunded to the subscriber.

Example

"data" : {
    "firstOrderId": "S20240601KRA0010009",
    "firstPurchaseId": "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2",
    "refundedOrderId": "S20240608KRA0110009",
    "refundedPurchaseId": "3b3a885281926494dd23273da39dd62a4de7e088b0cc284acbb463b91b95310e",
    "refundedPurchaseDate": 1596573209,
    "testPayYn": "N",
	"betaTestYn": "N"
}

Properties

Name

Value

Description

firstOrderId

string

The order ID on the first receipt delivered to the subscriber.

firstPurchaseId

string

The purchase ID you used with the receipt verification API.

refundedOrderId

string

The order ID of the refunded payment.

refundedPurchaseId

string

The purchase ID of the refunded payment.

refundedPurchaseDate

number

The purchase date of the refunded payment, in Unix epoch time.

testPayYn

string

Y: The item was purchased by a licensed tester in IAP test mode.
N: The item was purchased in IAP production mode.
See IAP test mode conditions for more information.

betaTestYn

string

Y: The item was purchased during a closed beta test.
N: The item was not purchased during a closed beta test.
See IAP test mode conditions for more information.

Subscription renewed

The subscription has been renewed by the subscriber.

Example

"data" : {
   "itemId": "weekly_fuel",
   "firstOrderId": "S20240601KRA0010009",
   "firstPurchaseId": "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2",
   "renewedOrderId": "S20240608KRA0110009",
   "renewedPurchaseId": "3b3a885281926494dd23273da39dd62a4de7e088b0cc284acbb463b91b95310e",
   "paymentPlan": "Regular",
   "scheduledTimeOfRenewal": 1720415824,
   "testPayYn": "Y",
   "betaTestYn": "N"
}

Properties

Name

Value

Description

firstOrderId

string

The order ID on the first receipt delivered to the subscriber.

firstPurchaseId

string

The purchase ID you used with the receipt verification API.

renewedOrderId

string

The order ID of the most recent renewal payment.

renewedPurchaseId

string

The purchase ID of the most recent renewal payment.

paymentPlan

string

The product plan applied to the current subscriber (for example, FreeTrial / TieredPrice / Regular).

scheduledTimeOfRenewal

number

The next subscription renewal date, in Unix epoch time.

testPayYn

string

Y: The item was purchased by a licensed tester in IAP test mode.
N: The item was purchased in IAP production mode.
See IAP test mode conditions for more information.

betaTestYn

string

Y: The item was purchased during a closed beta test.
N: The item was not purchased during a closed beta test.
See IAP test mode conditions for more information.

Subscription price change accepted

The subscriber has consented or not consented to a subscription price change.

Example

"data" : {
   "itemId": "weekly_fuel",
   "firstOrderId": "S20240601KRA0010009",
   "firstPurchaseId": "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2",
   "agreeYn": "Y",
   "testPayYn": "N",
   "betaTestYn": "N"
}

Properties

Name

Value

Description

itemId

string

ID of item purchased.

firstOrderId

string

The order ID on the first receipt delivered to the subscriber.

firstPurchaseId

string

The purchase ID you used with the receipt verification API.

agreeYn

string

Y: The subscriber consented to the subscription price increase and the subscription will be renewed at the increased price at the beginning of the subscription period when the price increase is applied..
N: The subscriber did not consent to the subscription price increase and the subscription will be cancelled at the end of the final subscription period that charges the current price.

testPayYn

string

Y: The item was purchased by a licensed tester in IAP test mode.
N: The item was purchased in IAP production mode.
See IAP test mode conditions for more information.

betaTestYn

string

Y: The item was purchased during a closed beta test.
N: The item was not purchased during a closed beta test.
See IAP test mode conditions for more information.

Order history deleted

Delete order details. When the order details are deleted, receipt and subscription information for the specified order and purchase IDs are no longer available.

Example

"data" : {
   "count": 3,
   "orderList": [
      {
         "orderId": "S20240601KRA0010001",
         "purchaseId": "579cc7245d57cc1ba072b81d06e6f86cd49d3da63854538eea68927378799a37"
      },
      {
         "orderId": "S20240601KRA0010009",
         "purchaseId": "9c7a73ec46aaf1fb7e3792c23633f3f227005d6a6c716f1869ca41b9e4f17fe2"
      },
      {
         "orderId": "S20240608KRA0110009",
         "purchaseId": "3b3a885281926494dd23273da39dd62a4de7e088b0cc284acbb463b91b95310e"
      }
   ]
}

Properties

Name

Value

Description

orderId

string

Order ID on the receipt delivered to the user.

purchaseId

string

The purchase ID you used with the receipt verification API.

Test

This is a test notification sent using Seller Portal.

Example

"data" : {
   "sellerName": "Martine",
   "contentName": "Driving Game"
}

Properties

Name

Value

Description

sellerName

string

The name of the person selling the item.

contentName

string

The name of the item.

IAP test mode conditions

The following table describes the conditions (status of content in Seller Portal and the IAP operating mode) that apply for the testPayYn and betaTestYn property values.

Content Status in Seller Portal

Registering (with licensed tester)

Closed beta

For Sale

IAP Operating Mode

OPERATION_MODE_TEST

OPERATION_MODE_PRODUCTION

testPayYn

Y

N

betaTestYn

N

Y

N