Testing Payments

Best way to test implementation

Once you have your payments system in place, follow these steps to thoroughly test your implementation.

Payment testers

To test your payment implementation, you can assign specific users of your app to be payment testers. If a user is assigned as a payment tester they can make transactions as normal within your app, however their payment instrument won't be charged and the transaction won't appear in the payments reporting API.

Payment testers can be defined in the Payments section of your App Dashboard.

Payment Testers

Whenever a payment tester invokes the payment dialog in your app, they'll be presented with a test flow instead of the regular payment flow. Payment testers have the option to test different scenarios:

  • A transaction which succeeds immediately.
  • A transaction which fails immediately.
  • An asynchronous transaction which will succeed after 30 seconds.
  • An asynchronous transaction which will fail after 30 seconds.
Payment tester options
Asynchronous tests

By using the different options, you can test if the different payments flows in your app work as expected.

In terms of order fulfillment, test payments behave in the same way as non-test payments. The JavaScript callback, Webhooks and Payment Graph API perform consistently, irrespective of if the payment is made by a test user or otherwise.

The only differences separating real payments from test payments, are that test payments won't appear in the user's Purchase History, and won't appear in any payment reporting.

Payment Info

When querying the Graph API for payment info on a test transaction with a payment_id, an extra test field will be added to the Graph API return data and set to 1, signaling it was a test transaction which you won't be paid out for.

  "id": "370408446422594", 
  "user": {
    "name": "Marco Alvarez", 
    "id": "500535225"
  "application": {
    "name": "Friend Smash!", 
    "namespace": "friendsmash", 
    "id": "24143148..."
  "actions": [
      "type": "charge", 
      "status": "completed", 
      "currency": "USD", 
      "amount": "0.90", 
      "time_created": "2013-10-23T22:24:41+0000", 
      "time_updated": "2013-10-23T22:25:18+0000"
  "refundable_amount": {
    "currency": "USD", 
    "amount": "0.00"
  "items": [
      "type": "IN_APP_PURCHASE", 
      "product": "https://friendsmash.com/og/coin.html", 
      "quantity": 9
  "country": "US", 
  "request_id": "5D81tgIWTBrfYG36ohftTci3KVU8M6dAg2NPmJwXcpk65ABVlkp5vtE2y43YYpWI", 
  "created_time": "2013-10-23T22:24:41+0000", 
  "test": 1, 
  "payout_foreign_exchange_rate": 1

Testing Options

Regardless of which method you use to invoke the dialog, a payment tester will be presented with 5 different payment options. These options are designed to exercise potential scenarios that may occur when a player elects to pay with their mobile phone or selects an asynchronous payment method.

The 5 different options are discussed below:

Immediately settle the payment This method is useful for simulating a payment made via a mobile payment provider, and will generate a completed test payment immediately after clicking on the 'Confirm' button. The JavaScript function you defined as a callback when invoking the Pay Dialog will be triggered withstatus=completed, and we will immediately issue a Webhook Update to your server. If you query the Graph API, you'll notice that the payment has a completed status.

Immediately fail the payment This option will immediately create a test payment with a status of failed. The Pay Dialog will behave in the same way as a non-test payment and will prompt you to try another payment method. In this case, because the you're a payment tester, it'll present the payment tester flow with the 2 original options. We will also immediately issue a Webhook Update to your server, notifying you of the failure.

Settle the payment in 30 seconds This method is useful for simulating a payment made via an asynchronous payment method. In this case, the JavaScript callback function will be called immediately after the 'Confirm' button is clicked, with the payment in an status=initiated state (Note: We won't issue a Webhook Update for payments with this status). If you query the Graph API for details of the payment at this time, you'll see that the payment status will be set to initiated. After 30 seconds, the payment status will automatically be set to completed. At that moment, we will issue a Webhook Update to your server, notifying you of the change. You'll also be able to confirm by querying the Graph API.

Fail the payment in 30 seconds The final option works in much the same way as the previous option. A test payment will be created with an initial status of initiated. This status will then automatically change tofailed after 30 seconds. This is designed to simulate the scenario of a mobile or asynchronous payment failing to complete. we will issue a Webhook Update to your server after the status changes to notify you of the failure. You can again check the status of this payment via the Graph API.

Withhold Tax This option will immediately create a settled payment with additional information about the tax witheld.

Disputing Test Transactions

You can test disputing and refunding test transactions by using a special parameter on the different pages where your transactions are listed.

For example, you can use the Help Center for Payments to dispute test transactions by adding the special parameter env=external parameter at the end of the link: https://www.facebook.com/help/contact/830921593618796?env=external

You can also go to your personal Payment Settings page and add the parameter to list test transactions of your applications: Payments Settings

This will allow you to test Webhooks for disputes and for refunds.

Testing mobile shortcutting and asynchronous payment methods

In addition to the testing options, we have also included a new dialog designed specifically to test mobile shortcutting and asynchronous payments. This dialog can be invoked in one of t2wo ways:

  • By selecting the 'Asynchronous Payment Method' option on the testing dialog, illustrated above.
  • By altering the call to the FB.ui pay method of the Facebook SDK for JavaScript with a non-empty test pricepoint_id. This is illustrated by the code sample below.
    method: "pay",
    action: "purchaseitem",
    product: "http://www.friendsmash.com/og/coins.html",
    quantity: 20,
    pricepoint_id: "this_is_a_test_pricepoint"

Testing multiple currencies

We've added the functionality for developers of an app to test purchases in multiple currencies without having to change their preferred currency in their payments settings. This will only work for admins, developers and testers listed on an app to avoid potential abuse from users through JavaScript injection.

To test this, you will need to define an extra parameter when invoking the Pay Dialog called test_currency. When calling the Pay Dialog, if you set this parameter to the 3 character code for a supported currency, it'll temporarily override the currency which you're charged in. An example of how to use this can be seen below.

Note: this only overrides the default currency and doesn't mean that every transaction will be a 'test' transaction, transactions will be charged unless you're listed as a payment tester.

      method: 'pay',
      action: 'purchaseitem',
      product: 'www.mydomain.com/payment_product.html',
      quantity: 1,                   // optional, defaults to 1
      request_id: 'YOUR_REQUEST_ID', // optional, must be unique for each payment
      test_currency: 'EUR'           // optional, overrides currency for testing  

A/B testing API

In an effort to make it easy for developers to A/B test their Facebook payments implementation, we've created a simple API that segments users into 1 of 10 groups. This allows you to try different pricing strategies, product offerings or promotions in a controlled environment.

When you query the API, we'll return a test_group value from 1 through 10 for a given user. This test group value will remain stable for a given user.

It's important to note that we have taken steps to ensure that this segmentation is truly random, and will generate reliable results with no payment bias across the base of the ecosystem.

To check which test_group a user is in, you can query the graph API with the following query:

GET https://graph.facebook.com/USER_ID?fields=test_group&access_token=ACCESS_TOKEN

Response An integer value from 1 through 10.

If you're still using the older payment_test_group, that will still work. However, we're planning on deprecating it eventually so you must move to test_group at your earliest convenience

Testing Subscriptions

Payments test users in the subscription environment

Player's whose IDs appear in the "Payments Testers" list in your app's settings will be set up to test subscription payments. This will allow you to quickly test your workflows for both valid and invalid payment instruments. Note: Subscriptions that have been created using the testing flow won't be displayed with the Subscription management interface, under Account Settings > Payments. This is reserved only for legitimate subscriptions.

Using the server-side API to test payment recurrence

It's important to test your system's ability to handle the ending of a billing period, and the beginning of a new one. To do it, use the server-side API's subscription management interface to set the next_bill_time property to a date and time near the current time.

Using test users to test free trials

There's no way to undo a given player "using up" their free trial. To test your trial functionality repeatedly, you'll need a steady supply of new users; the only way to get them is by using the "test user" functionality, which allows you to create a special kind of user, isolated from normal users.