Transaction Updates

Handling updates to payments.

Incurring chargebacks, refunds and declines is a normal part of operating any online business. Handling disputed transactions in an accurate, fair and timely manner is a responsibility of the developer as part of providing good customer service and maintaining player trust.


If a transaction is declined, refunded or charge backed, it's up to the developer to decide how they want to handle these situations with their consumer. Some developers may choose to retract in-app purchases for users who end up not paying for they item. It is appropriate to take different actions depending on the history and status of each transaction.

We recommend that if a developer decides to retract an in-app purchase from a player, that they inform them of their resolution via an in-app message or through email. A declined, refunded, chargeback or dispute can be the result of insufficient funds, misunderstanding or miscommunication and many of these players intend to keep using and purchasing from the game.


The following upcoming changes to our platform might impact the volume of refund requests:

  • On January 1, 2021 we will stop supporting Flash-based web games on our platform.
  • On June 30, 2021, we will fully deprecate Gameroom.
  • Our new Minimum Performance Standard will lead to the removal of low-quality Instant Games from our platform.

At times you may wish to issue a refund to a consumer for a payment made within your app. It's also important to be aware that there are some circumstances in which we can and will issue refunds directly. In both cases, when the refund is issued, we will send a webhooks update to your server. Subscribing and responding to Webhooks updates is the only way to keep your records up to date and in sync with Facebook.

You can refund the player any amount less than or equal to the refundable_amount returned by the Graph API for a given payment_id. You can also issue additional refunds, as long as therefundable_amount remains greater than zero. Depending on the method of purchase and the nature of the refund, users may see the refund amount returned to their balance rather than directly to their bank account.

To issue a refund, make an HTTP POST call to the Graph API endpoint /PAYMENT_ID/refunds with an app access token, and the following parameters:

Name Description Type


The three-letter ISO code of the currency in which the refund amount is specified; it must be the same as the currency in which the original purchase was denominated.



The amount to refund



The reason you're refunding this order. This is optional but if specified must be one of the following: MALICIOUS_FRAUD, FRIENDLY_FRAUD, CUSTOMER_SERVICE. Providing any value other than those enumerated here will result in an error.


The response from the Graph API will be true on success, or an error code otherwise. The payment object is then updated, with its actions field set to include details of the refund. If the response from Facebook is true, the refund will be issued immediately. Different banks will vary in the time taken to settle the refund, typically a couple of days.

Refunds API is only available for payments that have been made in the last 60 days. Trying to refund a payment that was made before 60 days, will result in an error.


A chargeback occurs when a consumer in you contacts their payment provider directly (ex., credit card company or PayPal) to dispute a charge. A chargeback can happen for various reasons, including unauthorized use of a financial instrument, double billing or non-receipt of a virtual good. If the payment provider issues a refund, we will recover the cost of the chargeback from the developer. We do this by deducting the charged-back amount from the next payout made to the developer at the end of the twice-monthly payout cycle. We'll only do it if the chargeback occurs within 90 days of the original transaction. Beyond 90 days, we will be responsible for the cost of the chargebacks unless:

  1. We determine you accepted the payment after breaching Facebook rules or policies.
  2. Your chargeback rate for any one of the prior 3 months exceeds 5% of your total transaction volume for that month.

As with refunds, you'll also be notified via webhook update when a chargeback has been issued. There'll also be a chargeback object added to the actions array of the Graph API return data for the payment, signifying the payment has been chargebacked.

Chargeback reversal

A chargeback reversal will occur in the rare circumstance where the consumer invokes a chargeback via their bank, then later the bank determines the chargeback wasn't warranted. In this scenario, the developer is paid for the transaction as normal. As with chargebacks, you will also be notified via webhook update when a chargeback reversal has been issued. There will also be a chargeback_reversal object added to the actions array of the Graph API return data for the payment, signifying the payment has been reversed.


In certain cases we'll group small transactions into transaction bundles that will be captured and processed together. For these transactions, the bundle is processed when the consumer reaches a certain price threshold, after a set period or after a given number of transactions have been added to the bundle. We retain control of these heuristics and will take steps to maximize the efficiency of the system across different currencies and markets.

You'll continue to receive updates via JavaScript and Webhooks for each individual transaction. Bundled transactions are not exposed via the Graph API, but costumers can see bundled transactions on their payments history and on the transaction receipt.

A decline occurs when we are unable to capture a bundled payment. Like a chargeback, if a transaction bundle is not able to be captured, we will recover the cost of the declined payment from the developer. It'll be at the developer's discretion as to how they want to handle the declined payment with customers.