​
The URL

As we are using the playground, the base URL is https://playground.runa.io/v2, we will be making a call to the POST /order endpoint. The full path therefore is https://playground.runa.io/v2/order.

​
What headers do I need to send?

To successfully place an order, you need to include the following headers in your API request:

​
X-Api-Key
string
required

The API key you created in the previous step.

​
X-Idempotency-Key
string
required

A unique value that we use to prevent duplicate purchases. If a network error occurs, you can retry the request with the same idempotency key and we will return the original order without any danger of creating a new one. You can read more about how we handle this field in the idempotency guide.

For testing you can just make one up, but you must generate a unique value for each order you intend to make. We suggest using a V4 UUID for this field.

​
X-Api-Version
string

The API version you want to use. This header is optional but we highly recommend you to set it. For this guide, we will use the latest version 2024-02-05

​
X-Execution-Mode
string
default:"async"

Set the value of this header to sync as we are using the synchronous execution mode for this guide. If omitted, the default value is async.

Putting this all together the full headers we need to send are:

X-Api-Key: <your-api-key>
X-Idempotency-Key: <your-idempotency-key>
X-Api-Version: 2024-02-05
X-Execution-Mode: sync

​
The request body

The request body is a JSON object that defines the order we are about to place. We need to define the payment method and the items we want to order, and how we want to distribute the payout link to the end users.

Here’s the outline of the request body we will be constructing, read on to see how to fill in the details.

{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "USD"
  },
  "items": [
    {
      "face_value": 10,
      "distribution_method": {
        "type": "PAYOUT_LINK"
      },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    }
  ]
}

​
The payment method

The payment method is the balance you want to use to pay for the order. For simplicity we will match the currency of the payout link we are about to order. The following fields are set on the payment_method object:

​
type
string
required

Set the payment method type as ACCOUNT_BALANCE

​
currency
string
required

For this example, we will use the currency USD

"payment_method": {
  "type": "ACCOUNT_BALANCE",
  "currency": "USD"
}

​
The order item

As we are using the synchronous execution mode, we can only order a single payout link at a time. The following fields are set on the single item within the items array:

​
face_value
number
required

Indicate the face value of the payout link you wish to order. The currency will be based on the selected product. As the product is in USD this will be $10.

​
distribution_method
object
required

We have a choice here between EMAIL and PAYOUT_LINK. Read on to see how to set these fields.

​
products
object
required

We have a choice here between SINGLE and MULTIPLE and TEMPLATE. Read on to see how to set these fields.

{
  "face_value": 10,
  "distribution_method": {
    ...
  },
  "products": {
    ...
  }
}

​
The distribution method

As mentioned we have two options here, EMAIL and PAYOUT_LINK.

  • EMAIL: This will send the payout link directly to the end user’s email inbox.
  • PAYOUT_LINK: This will return the payout link in the response body.
  • RECIPIENT: This is used for payment type products, we won’t be using this in this guide.
To distribute via EMAIL
​
type
string
required

Set the distribution method type as EMAIL

​
email_address
string
required

Set the email address you want to send this payout link to.

"distribution_method": {
  "type": "EMAIL",
  "email_address": "recipient@example.com"
}

The playground environment by default does not send emails. To enable this, you need to set the X-Send-Email: true header.

Ensure you refer to the playground reference for more details.

To distribute via PAYOUT_LINK
​
type
string
required

Set the distribution method type as PAYOUT_LINK

"distribution_method": {
  "type": "PAYOUT_LINK"
}

​
The product selection

There are three options here, SINGLE, MULTIPLE and TEMPLATE.

  • SINGLE: This will create a payout link for the selected product, the end user will receive a link for the chosen value exactly.
  • MULTIPLE: This will create payout link where the end user can choose to split the value between multiple products.
  • TEMPLATE: This will create a payout link as defined by a pre-built template.

As we’ve not pulled the product catalog we’ll use TEMPLATE for this example. In the playground environment we have a pre-defined template we can use for USD that will give us a payout link with 10 randomized products.

On the products object we will set the type to TEMPLATE and the template_id to PT-01HQ12PV4B8XMBRTK281JM54KK. The template_id is the ID of the template we want to use.

​
type
string
required

Set the product selection type to TEMPLATE

​
template_id
string
required

Set the template ID to PT-01HQ12PV4B8XMBRTK281JM54KK, a pre-defined playground template for USD.

​
Putting it all together

​
The request

Here’s the complete request we’ll be sending to the API.

The Request Headers
POST https://playground.runa.io/v2/order
X-Api-Key: <your-api-key>
X-Idempotency-Key: <your-idempotency-key>
X-Api-Version: 2024-02-05
X-Execution-Mode: sync
Content-Type: application/json
The Request Body
{
  "payment_method": {
    "type": "ACCOUNT_BALANCE",
    "currency": "USD"
  },
  "items": [
    {
      "face_value": 10,
      "distribution_method": {
        "type": "PAYOUT_LINK"
      },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    }
  ]
}

​
The response

The response will be a 200 OK with the order details in the body. You can retrieve the payout link from the payout.url field from the items array.

The Response
{
  "id": "O-01234567890ABCDEFGHIJK",
  "status": "COMPLETED",
  "created_at": "2025-01-01T12:00:00+00:00",
  "completed_at": "2025-01-01T12:00:01+00:00",
  "description": null,
  "payment_method": {
    "type": "ACCOUNT_BALANCE"
  },
  "currency": "USD",
  "items": [
    {
      "id": "E-01234567890ABCDEFGHIJK",
      "distribution_method": {
        "type": "PAYOUT_LINK",
      },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK",
        "values": [ ... ]
      },
      "face_value": "10.00",
      "price": "10.00",
      "payout": {
        "status": "ACTIVE",
        "status_updated_at": "2025-01-01T12:00:01+00:00",
        "url": "https://payout.playground.runa.io/01234567-0000-4000-abcd-012345678900",
      },
      "currency": "USD"
    }
  ],
}

Pop the url field into your browser to see the payout link. Congratulations, you’ve just made your first order with Runa.

​
Next steps

You can now explore the following features to take your first order to the next level.

Fetch the product catalog

To make orders for specific products you’ll need to fetch the product catalog first.

Customizing the payout link

Add your own branding and customize the redemption experience for your recipients.

Pay using a different currency

Use Runa Embedded FX to pay for an order using your funds in another currency

Alternatively, you can explore the steps needed to make real orders in the production environment.

Moving to production

Once you’re ready to go live have a look at the production checklist.