Samsung IAP Purchase Acknowledgment API

The Samsung IAP Purchase Acknowledgment API is used to consume or acknowledge a purchased product. Before you can start using the IAP Purchase Acknowledgment API, you must meet all requirements, use the required authorization header parameters, and use the required URL path paremeters in your requests. See Get Started with the IAP APIs for more information.

Consume or acknowledge a purchased product

After your app has granted entitlement of a product to the user with a successful transaction, your app needs to notify Samsung IAP that the purchase was successfully processed.

You can report one or more purchased items as consumed, which makes the items available for another purchase (the app user may or may not have used the items). Or, you can acknowledge that the user has been granted entitlement for one or more purchased subscriptions.

Request

PATCH /iap/seller/v6/applications/<packageName>/purchases/<purchaseId>

Body parameter

Name

Type

Description

action

string

Required
The task to perform. Must be one of the following:
  • consume: Report one or more purchased items as consumed.
  • acknowledge: Acknowledge that the user has been granted entitlement for one or more purchased subscriptions.

purchasedIdList[].purchaseId

string

Optional
One or more purchase IDs of the purchased item or subscription.


Example: single item or subscription

Request body

{
     "action":"consume"
}

cURL

curl -i -X PATCH \
  -H  "Content-Type: application/json" \
  -H  "Authorization: Bearer <your-access-token>" \
  -H  "service-account-id: <your-service-account-id>" \
  -d '{"action" : "consume | acknowledge"}' \
'https://devapi.samsungapps.com/iap/seller/v6/applications/<packageName>/purchases/<purchaseId>'

Example: multiple items or subscriptions

Request body

{
     "action":"consume",
     "purchasedIdList":[
          "5fd9b7a353539aaa5401da21d0a3637deee12f2539fcef2f7daba8c9aaa2",
          "5ed5b555af4ecf4fb756cc32e9cbddd9da15397a26904ff7d1a248eb333d",
          "698fc6d155e74eee0896ca8a540468883f8db7eee6f3119fb2e298b7abbb"
     ]
}

cURL

curl -i -X PATCH \
  -H  "Content-Type: application/json" \
  -H  "Authorization: Bearer <your-access-token>" \
  -H  "service-account-id: <your-service-account-id>" \
  -d '{"action" : "consume | acknowledge", \
  "purchasedIdList":[ \
       "5fd9b7a353539aaa5401da21d0a3637deee12f2539fcef2f7daba8c9aaa2", \
       "5ed5b555af4ecf4fb756cc32e9cbddd9da15397a26904ff7d1a248eb333d", \
       "698fc6d155e74eee0896ca8a540468883f8db7eee6f3119fb2e298b7abbb" \
  ] }' \
'https://devapi.samsungapps.com/iap/seller/v6/applications/<packageName>/purchases/<purchaseId>'

Response

Name

Type

Description

totalCount

int

The number of products for which a response is returned.

purchaseItemList[].purchaseId

string

The purchase ID of the transaction.

purchaseItemList[].statusCode

string

Response status code.

purchaseItemList[].statusString

string

Response status message.


StatusCode and StatusString values

StatusCode

StatusString (consume)

StatusString (acknowledge)

0

success.

success.

1

Can't find an order with this purchaseId.

Can't find an order with this purchaseId.

2

Can't consume this purchase because it's not a successful order.

This is not a successful order.

3

This type of product is not a consumable item.

This type of product is not a subscription.

4

This purchase has been consumed already.

This purchase has been acknowledged already.

5

Can't consume this purchase because the user is not authorized to consume this order.

This purchase is not authorized for this order.


Example response

{
     "totalCount": 3,
     "purchaseItemList": [
          {
               "purchaseId": "5fd9b7a353539aaa5401da21d0a3637deee12f2539fcef2f7daba8c9aaa2",
               "statusCode": "0",
               "statusString": "success."
          },
          {
               "purchaseId": "Can't find order with this purchaseID.",
               "statusCode": "1",
               "statusString": "This type of item is not non-consumable or subscription."
          },
          {
               "purchaseId": "698fc6d155e74eee0896ca8a540468883f8db7eee6f3119fb2e298b7abbb",
               "statusCode": "3",
               "statusString": "This type of item is not non-consumable or subscription."
          }
     ]
}

See Failure response codes for a list of possible response codes when a request fails.

Failure response codes

Status

Code and message

400
Bad Request

  • 102: Invalid parameter
401
Unauthorized

  • 101: Failed to verify gateway server authorization