Managing refunds and chargebacks from your service

The Clawback service allows partner services to be notified of refunds, returns, and chargeback events for their consumable products and store-managed subscriptions.
This allows partner services to implement logic helping prevent and mitigate revenue loss from fraudulent transactions and refund requests.

The following information is based on the latest version of the Clawback event service, which is the recommended approach for all services.

Risk and fraud potential with refunded consumables and store-managed subscriptions

The Microsoft Store allows users the ability to request refunds or returns of digitally purchased content through their account's orders page (https://account.microsoft.com/billing/orders/). The automated system allows users the ability to receive a certain number of automatic returns per year if certain criteria are met, such as the purchase being made within a short time of the return request. Otherwise, only in certain instances will Microsoft's Customer Support team issue refunds or returns of a digital item.

If a consumable product has not yet been fulfilled or its quantity consumed, the quantity from the returned purchase is automatically removed from the user's balance. However, if the item was fulfilled or consumed prior to the return, the user's balance will never go below 0. In this instance, the user has the in-game currency credit from when the game service consumed the item and they received their money back. This can lead to abuse and fraud related to consumables purchased, redeemed in-game, and then refunded.

Similarly, store-managed subscriptions are subject to varying regional laws that require either full or partial refunds.
Depending on the refund type, different revocation actions may be desired by the game developer or publisher.

Therefore, it is recommended that partners use the Clawback event service to detect these scenarios, manage, and protect their revenue streams for consumable products and store-managed subscriptions.

Utilizing the Microsoft.StoreServices .NET library and sample

To help demonstrate the principles and flows outlined in this article review the Microsoft.StoreServices Sample which provides the following:

• Use of the Microsoft.StoreServices library to manage authentication and make the calls to the Microsoft Store Services.

• Example logic for managing consumable products, tracking pending consume requests, reconciling refunded purchases, renew expired User Store Ids, and more.

• A configuration guide that includes the steps in this article on how to configure and setup your Microsoft Entra ID for this authentication method.

• Microsoft.StoreServices (GitHub)

• Microsoft.StoreServices Sample (GitHub)

Clawback event Queues

The Clawback event service is based on writing event messages to an Azure Storage Queue configured for your service's Entra application client ID.
The events are written to the queue almost instantly when a refund, return, or chargeback is processed through the Microsoft Store services.
Therefore, this allows your service to periodically query for any recent Clawback events across your entire product catalog and reconcile them within your system.

Currently the following product types are supported with the Clawback event service queue:

Required On-boarding and Setup

On-boarding for a Clawback event queue requires an Azure Storage Queue to be configured by the Microsoft Store services team. The queue's hosting cost and management will be covered by Microsoft.

To have a Clawback event queue setup for you, contact your Developer Partner Manager or Microsoft contact. When requesting the queue's setup you must provide the following:

• The Entra application client ID that your service(s) will use to authenticate and that your products are associated with in Partner Center.
• The preferred geographical Azure data center of the primary queue. This is not required as the queue is accessible world-wide, but will provide better latency if close to your own service(s).

Once submitted, it can take 1-2 weeks for the queue setup to be deployed.

Accessing your Clawback event queue

To access your Clawback event queue, your service obtains an SAS Token from purchase.mp.microsoft.com/v8.0/b2b/clawback/sastoken using a service access token generated from your service's Entra ID credentials. The SAS Token has a limited lifetime, but your service can request a new SAS Token at any time.

The returned uri parameter of the SAS Token represents the URI address to your Clawback Queue and the parameters needed to authenticate to it. However, to query and operate on your queue the URI requires additions outlined below depending on the operation you want to perform.

Processing Clawback messages from the queue

Using the modified uri parameter of the SAS token, your service can interact with your Clawback queue using either of the following:

• Azure Queue Storage REST APIs
• Azure Queue Storage using .NET

Each entry in the Clawback queue is written as a message with the details of the Clawback event provided as a part of those messages.
To manage the messages on the queue, your service can perform these operations by adding the following parameters to the URI:

When you use the Get operation to retrieve messages from the queue, it places a visibility timeout (default 30 seconds) on the returned messages. This prevents messages being processed from showing up in subsequent Get operations until after the visibility timeout. The Peek operation on the other hand, does not set a visibility timeout and the messages will be visible to all follow up Peek or Get requests. However, in order to delete a message from the queue you need the popreceipt value which is only returned in messages using the Get operation.

The recommended flow for message processing is:

1. Get a message (or set of messages) from the queue.
2. Extract the Clawback event information from each message.
3. Check your completed transaction database for any matching transactions with the same ProductId, OrderId, and LineItemOrderId as the Clawback event.
4. Reconcile the items granted to the user in your system from the completed transactions.
5. Set the transaction in your own database as reconciled.
6. Delete the message from the message queue.

The response from the Get or Peek functions will be an XML List of QueueMessage items with the following format:

<QueueMessagesList>  
    <QueueMessage>  
      <MessageId>string-message-id</MessageId>  
      <InsertionTime>insertion-time</InsertionTime>  
      <ExpirationTime>expiration-time</ExpirationTime>  
      <PopReceipt>opaque-string-receipt-data</PopReceipt>  
      <TimeNextVisible>time-next-visible</TimeNextVisible>  
      <DequeueCount>integer</DequeueCount>  
      <MessageText>message-body</MessageText>  
    </QueueMessage>  
</QueueMessagesList>  

QueueMessage structure

Clawback event structure

Each message in the queue will have an encoded JSON string in the MessageText that represents the Clawback event with the following parameters:

Clawback event source values

ClawbackEventContractV2 structure

Clawback event states

ClawbackEventSubscriptionData structure

Clawback event example

{
  "id": "5ef37bd1-8b4b-48c4-9b67-be458d8ab9de",
  "source": "/Purchase/Refund",
  "type": "ClawbackEventContractV2",
  "data": {
    "lineItemId": "230e9063-bffe-411a-8aa1-6f99ca091452",
    "orderId": "70fd35f2-7e4a-4f27-8df3-a673a5a4d9d9",
    "productId": "9N0297GK108W",
    "productType": "UnmanagedConsumable",
    "purchasedDate": "2023-01-24T21:59:19.5725585+00:00",
    "eventDate": "2023-01-26T08:18:52.246847+00:00",
    "eventState": "Revoked",
    "sandboxId": "XDKS.1",
    "skuId": "0010"
  },
  "time": "2023-01-26T08:18:56.7103057+00:00",
  "specversion": "1.0",
  "datacontenttype": "application/json",
  "subject": "/Purchase/Refund/907eb4af-57bf-4ff6-b040-e9296d169436",
  "traceparent": "00-6d2a86a53e8cae15cddaadc43f4d9670-4821cba073c416c1-00"
}

Refunds vs returns

When an event comes from the /Purchase/Refund source, this indicates that the event is tied to either a customer refund or return request. These two terms are sometimes used synonymously, but in the context of the Microsoft Store services they are each have unique behavior that should be handled by your service.

In both cases the user will receive their payment back from the order, but differ in what happens to the entitlement or quantity granted from the purchase.
A return operation will attempt to remove the entitlement or quantity from the user's account. Refunds however result in the user's account retaining the entitlement or quantity from the purchase.

Requests to Microsoft Customer Support or through the automated tools are generally treated as a return requests.
However, in rare cases as a 'make-good' gesture based on the circumstances related to the customer's issue, the state of the event may be Refund in an effort to provide positive customer service. The Refund state may also be used as a pro-active refund issued to the customer if there is an indication the purchase will be reported as a chargeback to avoid the chargeback processing fees.

Your service should check the eventState value and follow the recommendations for reconciliation of each value outlined in Clawback event states. For example scenarios see Clawback return state behavior for consumable products and Clawback return behavior for store-managed subscription products

Chargebacks and chargeback reversals

When an event comes from the /Purchase/Chargeback source, this indicates that the payment institution reversed the charge of the order and has taken payment back. A common cause of a chargeback is a dispute or fraudulent charge to the payment instrument. When the chargeback event happens, the Clawback service will report the event with either a Revoked or Returned state based on the attempt to remove the entitlement or quantity from the user's account. At the time of the event, your service should treat chargeback events with the same reconciliation actions as events from /Purchase/Refund.

Microsoft will commonly appeal the chargeback based on information if we believe the purchase appears to be legitimate and quantity used. If the appeal is granted, payment is sent back to Microsoft and a ChargebackReversal event will be logged in your Clawback queue. This event will have the same OrderIDs as the initial chargeback event.

When a ChargebackReversal happens, the item that was purchased is restored to the user's account. Therefore, any action taken on your server to revoke or remove the purchased item should be reversed as the payment has now been restored.

The timeline of a chargeback and chargeback reversal can vary. Chargebacks are usually triggered within 90 days of a purchase, but some may take up to 180 days after the purchase. If the chargeback is appealed by Microsoft, the process and final appeal outcome can take between 3 - 6 months.

Reconciling consumable Clawback events

When a Clawback event for an already fulfilled or consumed item is detected, the development team or publisher are free to determine the proper course of action on the user's account. Some possible actions are listed below, but are not limited to only these.

• Remove the equivalent consumable value (usually in-game currency) from the user's remaining balance if possible
• Remove the last purchased items using the consumable value within the game (if unable to remove quantity from their remaining balance)
• Take no action against the user at this time, but track their account to see if this is a pattern of possible fraud or abuse of returns (ex: Large consumable qty products purchased, then returned after being consumed in-game).

It is recommended to notify the user of reconciliation actions taken, reason why, and logging this information in your services to avoid further Customer Support calls or disputes. Example: "Due to a return issued to your account through Microsoft we have removed [qty] of [product] from your account balance."

Requirements for managing Clawback events for consumable products

To properly manage and reconcile events related to store-managed and dev-managed consumables, your service must track each consume transaction and use the includeOrderIds parameter as TRUE. This parameter returns the IDs related to the purchase orders and quantity used to fulfill the consume request. These same OrderIDs are provided in the Clawback events which can then be used to search for and identify exactly which consume transaction and user in your own database need to be reconciled based on the data in the event.

For more information on recommendations and flow to track consume transactions on your service, see Managing consumable products from your service

Clawback Return state behavior for consumable products

Clawback Refund state behavior for consumable products

A Refund event state is a special case where the user is given their payment back, but also allowed to keep the entitlement to the item. There are two main scenarios that would lead to this event state:

• Refund issued by customer service as a 'make good' effort to a user for their inconvenience or issue that lead to the refund.
• Pro-actively issued refund when there is a high probability the purchase will be reported as a chargeback. This prevents the added fees and resource cost of processing a likely chargeback event.

Therefore, the correct action when you see a Refund event state is to record the event with the linked account information on your service. Then watch for patterns or repeated Refund event states on a single account indicating possible fraud or abuse on that account.

Clawback chargeback behavior for consumable products

Clawback chargeback reversal behavior for consumable products

Unique behavior of dev-managed consumables during chargeback Reversal

Regardless if the dev-managed consumable was consumed or not before the chargeback event, if there is a chargeback reversal the consumable quantity from the purchase will be added back to the user's account balance. However, Dev-Managed consumables will never report a quantity greater than 1 even if there are multiple valid entitlements to the dev-managed consumable. This is because Dev-Managed consumables are intended to block users from purchasing the consumable again until it has been reported as consumed / fulfilled by the game service. In the case of a chargeback reversal when there is already a non-zero balance on the user's account, the multiple entitlements are still valid and can be individually consumed as normal. Just note that the user's balance will remain as '1' after each consume request until all of the active entitlements have been consumed / fulfilled. Therefore, your system should go through the consume flow as normal until the user's balance for the Dev-Managed consumable reports as '0'.

When consuming, if you see a record matching the same OrderID, LineItemID, and ProductId check if it is marked as going through a chargeback reconciliation.
If it was marked as reconciled from a chargeback, reverse the action taken on the user's account balance and mark the item as a chargeback reversal.

Example: Qty = 1 before reversal, Qty = 1 after reversal but there are actually 2 active entitlements. Service consumes 1 of the consumable, user's quantity will still be '1' after the consume. Service consumes 1 more of the consume, user's quantity now reports as '0'.

Clawback return behavior for store-managed subscription products

When a Clawback event for a store-managed subscription is detected, additional information related to the subscription is added to the Clawback event through the ClawbackEventSubscriptionData structure. Specifically, if the user was issued a full or partial amount of their payment for the corresponding subscription interval. If your subscription grants monthly in-game rewards or currency to the user’s account, you may want to revoke those rewards depending on how many days payment was returned vs retained.

[NOTE!] The development team and publisher are free to determine the proper course of action on a user’s account when a store-managed subscription Clawback event is received. If action is taken to revoke any items or benefits, it is recommended to notify the user of the reconciliation actions taken, reason why, and logging the information in your service to avoid further Customer Support calls or disputes. Example: “Due to a return issued to your account through Microsoft we have adjusted your [subscription product] benefits.”

Clawback event behavior for store-managed subscriptions

Example ClawbackEventSubscriptionData for full and partial returns

Scenario: Monthly subscription, user was issued a pro-rated (partial) return on Jul 6, 2023. User was given back the price of 25 unused days, Microsoft retained the remaining price for 6 days that were used.

    "subscriptionData": {
      "recurrenceId": "mdr:0:ae5cad80acf2428fa64c38529996a3fd:df3763c2-36f8-4bde-8fa5-a29fb6058d62",
      "durationIntervalStart": "2023-07-01T00:00:00+00:00",
      "durationInDays": 31,
      "consumedDurationInDays": 6,
      "refundType": "Partial"
    }

Scenario: Monthly subscription, user was issued a full return on Jul 6, 2023. User was given back the full price paid for the month subscription, Microsoft did not retain any payment.

    "subscriptionData": {
      "recurrenceId": "mdr:0:0dc7194514404dd3bf0f678e21716774:23a454d5-f240-4dad-9923-9c3f53f515cc",
      "durationIntervalStart": "2023-07-01T00:00:00+00:00",
      "durationInDays": 31,
      "consumedDurationInDays": 6,
      "refundType": "Full"
    }

Scenario: Yearly subscription, user was issued a pro-rated (partial) return on Jan 15, 2024. User was given back the price of 199 unused days, Microsoft retained the remaining price for 168 days that were used.

    "subscriptionData": {
      "recurrenceId": "mdr:0:9ed0a48236404b78a017e9e226da94c6:22aa4f3c-1ffc-4dd3-8801-cb2a227a5c46",
      "durationIntervalStart": "2023-07-31T00:00:00+00:00",
      "durationInDays": 367,
      "consumedDurationInDays": 168,
      "refundType": "Partial"
    }

[NOTE!] The above example’s yearly subscription durationInDays is 367 rather than 365. One day is added due to 2024 being a leap-year, the other is added to move the user’s renewal date to the 1st of the next month in order to avoid issues with some months not having a 29th, 30th, or 31st. For more information see Understanding subscription start, renew, and expire dates.

In the latter example, payment for the time prior to the Clawback event was retained. If the subscription granted monthly rewards or in-game items, the recommendation is to ensure the user keeps the items granted to them for that time period.

Testing product returns within your development sandbox

Development accounts for sandboxes do not have access to the automated product return request tool on support.xbox.com. Therefore, to test the return scenarios and your Clawback implementation you will need to request a return for test purchases with the help of your Microsoft Developer Account manager or Microsoft contact by doing the following:

1. Verify that the test products are set with non-zero prices ($0.01 is sufficient).
2. Login to the development sandbox with your test account(s).
3. Purchase the product(s) on the test account(s).
4. Fulfill / consume the purchased items using the includeOrderIds: true option on the consume request.
5. Note the OrderIds that are returned in the consume responses.
6. Send an email to your Microsoft Developer Partner Manager or Microsoft contact to request a product return for the product(s). The email must include the following information in the following template example:

NOTE: Make sure your request is listed as a 'return' and not a 'refund'. The tools used for 'refunds' will refund the payment but keep the entitlement on the user's account. A 'return' in the tools will cause the entitlement to be revoked and cause Clawback event messages to be written to the queue.

A representative from the Xbox support team will reply to confirm the request has been processed within 3 business days. You should then be able to see the correct Clawback information in your queries.
If authorized by your Developer Partner Manager, they may provide you the Xbox Support team's email address for making future requests directly. Do not share this alias broadly within your organization and please remember to CC your Developer Partner Manager on any future direct requests.

NOTE: Returns and refunds will only cause Clawback events with non-zero priced products. Therefore, your products need to have a price of at least $0.01. This is now enabled as all newly created test accounts will have a test payment instrument added to them where they can make test purchases within a sandbox. If you are using an older account that does not have a test payment instrument, create a new account to be able to do this flow.

See also

Commerce Overview

Consumable-based ecosystems

Managing consumable products from your service

Microsoft Store Service APIs

Microsoft.StoreServices library (GitHub)

Microsoft.StoreServices Sample (GitHub)