​

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:

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:

"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": 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

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

To distribute via 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.

​

Putting it all together

​

The request

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

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

{
  "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.

{
  "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.

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