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:
- Item purchased
- Item refunded
- Subscription started
- Subscription ended
- Subscription refunded
- Subscription renewed
- Subscription price change accepted
- Order history deleted
- Test
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.
|
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
- Item refunded
- Subscription started
- Subscription ended
- Subscription refunded
- Subscription renewed
- Subscription price change accepted
- Order history deleted
- Test
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 |