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

Base URL

To access the Playground environment, use https://playground.runa.io/v2 as the base URL for your requests.

API key

The playground uses a different API key from the production environment. You can generate a playground API key in the API keys section of the dashboard. For security reasons, the API key will only be displayed to you at the time of generation, if you loose the key you will need to generate a new one.

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

Versioning

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

Supported endpoints & behaviour

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. Some endpoints are not available in the playground environment.

Unsupported endpoints

Error responses

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 the following.

{
    "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"]
        }
    ]
}

Triggering certain errors

Some errors cannot be triggered in playground through incorrect formatting or request inputs. For these errors, you can simulate them by adding a X-Trigger-Error header with the value set to one of the error types below:

Error typeDescription
insufficient_fundsThe account balance you’re trying to use to pay for your order does not have enough funds.
internal_server_errorAn unknown error occurred in our services.

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.

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

Base URL

To access the Playground environment, use https://playground.runa.io/v2 as the base URL for your requests.

API key

The playground uses a different API key from the production environment. You can generate a playground API key in the API keys section of the dashboard. For security reasons, the API key will only be displayed to you at the time of generation, if you loose the key you will need to generate a new one.

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

Versioning

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

Supported endpoints & behaviour

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. Some endpoints are not available in the playground environment.

Unsupported endpoints

Error responses

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 the following.

{
    "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"]
        }
    ]
}

Triggering certain errors

Some errors cannot be triggered in playground through incorrect formatting or request inputs. For these errors, you can simulate them by adding a X-Trigger-Error header with the value set to one of the error types below:

Error typeDescription
insufficient_fundsThe account balance you’re trying to use to pay for your order does not have enough funds.
internal_server_errorAn unknown error occurred in our services.

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.