Playground changes

On 5 Jan 2024 the static playground was replaced by the new dynamic playground. You now have to generate a new playground API key to use this environment.

If you are currently using the Connect API, please contact your Account Manager as your current credentials will not work on this version of the API.

The Playground environment allows you to safely and effortlessly test our API without any real transactions or expenses. It's a controlled environment where you can freely experiment with the API and familiarize yourself with its functionalities.

This guide will walk you through on how to access the Playground environment, testing the order endpoints, and provide information about its limitations.

It's important to note that no real orders will be created in the Playground, although you will be able to retrieve the data you submitted, and follow redemption links to perform a fake redemption which looks and feels exactly like the real thing.

Accessing the Playground environment

To access the Playground environment, use the following base URL for your requests:

In the API Reference section you can use the URL drop-down to switch to making requests against playground.


In order to make requests to the Playground, you'll need to include an API key in the X-Api-Key header.
To generate a key, please follow these steps:

  1. Log into the Runa web app

  2. Go to the API page

  3. Click Create a new API key in the top-right

  4. Select Playground key

  5. Add a label for the key, and acknowledge responsibility for the key's security by checking the checkbox.

  6. Click Create key

  7. Your key will now be displayed for you inside a yellow dialogue box. Please save this somewhere secure as this is the only time we will show you the key.

You cannot use a production key on playground, nor can you use a playground key on production.


The Playground environment supports only the latest version of the API. If you set the X-Api-Version header it must match the latest version.

Supported APIs

Behaviour of supported APIs

The supported APIs in the Playground environment will have the same request and response structure to the production API, but there are some exceptions regarding the values that can be used for testing purposes. These are explained below. See details about these APIs in the API Reference section.

When using the Create Order endpoint, the behaviour will closely resemble the production API, but there are a few limitations to consider:

  • Use of account balance to pay for an order will always be accepted. There is no need to top-up or maintain a balance on the playground.
  • For card_id, you can use wgCard in the request body. Using any other card id will give the same error as it would in production for any invalid card.
  • You can place as many orders as you want without reaching a fund limit. We are working on ways to simulate the errors you would get if you reached this limit, to be released in a future version.

It's important to note that no real orders will be created in the Playground, although you will be able to retrieve the data you submitted. If you select an email distribution type, emails will be sent, but please note the important message below about how this works.

Sending emails from playground

By default no emails are sent for playground orders. If you want to enable email sending you should send a custom header X-Send-Email: true. The response will contain the same header.

When enabled, we will only send an email for the first order item that has an email distribution type. This enables you to test large orders with email testing but without actually sending an excessive number of emails.

When testing orders with the header X-Send-Email: true you must ensure that the email addresses you use are valid and messages sent to them will not bounce. We monitor deliverability and may remove this feature from your account for repeat violations. For safety you can use emails ending in .invalid or .test, for example [email protected], which will never trigger email delivery.

Default product selection templates

You can use the following curated template IDs in the products field while creating a playground order. The actual payout types will be present in the response when you retrieve your order. Note that, the randomised products for some of the countries are for representational purpose, it is not a real functionality on production environment.

CountryProduct selection template IDSupported payout options
United StatesPT-01HQ12PV4B8XMBRTK281JM54KKRandomised 10 payout types
United KingdomPT-01HPPT8ME05693EG77RCGKMX7NRandomised 10 payout types
EuropePT-01HQ130AHCKRRB45Z5XV2Y8W9KRandomised 10 payout types
CanadaPT-01HQ12SMX2964BVXG2N69K8HF3Randomised 10 payout types
All other supported countriesCatalog based on payout currency

The Get Order endpoint lets you retrieve the details of orders you created using your Playground API key.

The redemption URLs in the response can be followed, and will lead to a page where you can test out a simulated redemption, to a fake gift card for the selected product.


Customer name on redemption link pages

In Playground mode, the customer name on redemption link pages currently show as PlaygroundCustomer: C-ABC (with your customer ID). In production, this will show your customer name instead.

The Get Order List endpoint lets you retrieve orders you created in Playground.

This endpoint gives you access to the supported product catalogue for the Playground. This list is currently static and corresponds to our base product selection without additional product approval. You may have access to a broader range of products when using the production API. You can only place Playground orders with the products returned from this endpoint.

To create a payout link in the ordering process, you’ll need to provide a list of products that are all redeemable in the same country.

This will return a static list of ISO3166 ALPHA-2 country codes. You can use this to aggregate products that belong to a country for ordering by using the countries_redeemable_in query parameter, in the endpoint described above.

Unsupported APIs

  • The Estimate order endpoint is currently unsupported. This will be added in a later release.

Error responses

At time of writing, there are some differences in the human readable messages in some request validation responses. We guarantee the top-level type of the error will match production however the details object may differ from what you see in production.

This is due to a version difference in the validation library we use which will be harmonised at a later date.

For example, if you pass in an invalid currency when creating an order, production will return

  "type": "validation_error",
  "message": "There were one or more problems processing your request, see details key.",
  "help": null,
  "details": [
      "type": "type_error.enum",
      "message": "value is not a valid enumeration member; permitted: 'GBP', 'EUR', 'USD', 'CAD'",
      "location": ["payment_method", "currency"]

while Playground will return the semantically identical, but differently worded

  "type": "validation_error",
  "message": "There were one or more problems processing your request, see details.",
  "help": null,
  "details": [
      "type": "enum",
      "message": "Input should be 'GBP', 'EUR', 'USD' or 'CAD'",
      "location": ["body", "payment_method", "currency"]

Continuous Improvement

We are continuously enhancing the Playground environment to better serve your needs for experimenting and testing integrations. Expect ongoing improvements and more features to be added over time.