Async - Runa Developer Hub

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 async as we are using the synchronous execution mode for this guide. If omitted, the default value is async but we still recommend you set it for explicitness.

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

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"
      }
    },
    {
      "face_value": 20,
      "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 items

As we are using the asynchronous execution mode, we can order multiple payout links at a time. The following fields are set on the items 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"
      }
    },
    {
      "face_value": 20,
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    }
  ]
}

The initial response

For async orders the response to the request will only contain the order ID and the status of the order. This is because the order is processing in the background.

The Intermediate Response

{
  "id": "O-01234567890ABCDEFGHIJK",
  "status": "PROCESSING"
}

You should take note of the order ID as you will need it to fetch the order details later.

Getting the order details

If you wait a short period and then fetch the order details using the get order details endpoint you’re able to fetch the same details available when using the synchronous ordering mode.

The order status will be PROCESSING for a short period of time after it is accepted. On the playground environment this is simulated by a 1 second delay.

The URL to fetch the order details is:

https://playground.runa.io/v2/order/{order-id}

The response will be a 200 OK with the order details in the body. You can retrieve the payout links from the payout.url fields 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"
    },
    {
      "id": "E-11234567890ABCDEFGHIJK",
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK",
        "values": [ ... ]
      },
      "face_value": "20.00",
      "price": "20.00",
      "payout": {
        "status": "ACTIVE",
        "status_updated_at": "2025-01-01T12:00:01+00:00",
        "url": "https://payout.playground.runa.io/11234567-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.

Webhooks

While you can fetch the order details after a short delay, in reality this would require you to poll the endpoint until the order is completed. This is not ideal and may lead to rate limiting issues. Instead we have the order completion webhook available for you to use.

If you intend to use the async ordering mode you should take a look at the webhooks section to see how to set one up. Unfortunately the playground environment does not support webhooks so you will need to use a real environment to test this out.

Webhooks

Get real-time updates for the product catalogue and your orders.

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.

On this page

The URL
What headers do I need to send?
The request body
The payment method
The order items
The distribution method
The product selection
Putting it all together
The request
The initial response
Getting the order details
Webhooks
Next steps

The URL

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

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 async as we are using the synchronous execution mode for this guide. If omitted, the default value is async but we still recommend you set it for explicitness.

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

The request body

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"
      }
    },
    {
      "face_value": 20,
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    }
  ]
}

The payment method

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 items

As we are using the asynchronous execution mode, we can order multiple payout links at a time. The following fields are set on the items 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.

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"
      }
    },
    {
      "face_value": 20,
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK"
      }
    }
  ]
}

The initial response

For async orders the response to the request will only contain the order ID and the status of the order. This is because the order is processing in the background.

The Intermediate Response

{
  "id": "O-01234567890ABCDEFGHIJK",
  "status": "PROCESSING"
}

You should take note of the order ID as you will need it to fetch the order details later.

Getting the order details

If you wait a short period and then fetch the order details using the get order details endpoint you’re able to fetch the same details available when using the synchronous ordering mode.

The order status will be PROCESSING for a short period of time after it is accepted. On the playground environment this is simulated by a 1 second delay.

The URL to fetch the order details is:

https://playground.runa.io/v2/order/{order-id}

The response will be a 200 OK with the order details in the body. You can retrieve the payout links from the payout.url fields 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"
    },
    {
      "id": "E-11234567890ABCDEFGHIJK",
      "distribution_method": { "type": "PAYOUT_LINK" },
      "products": {
        "type": "TEMPLATE",
        "template_id": "PT-01HQ12PV4B8XMBRTK281JM54KK",
        "values": [ ... ]
      },
      "face_value": "20.00",
      "price": "20.00",
      "payout": {
        "status": "ACTIVE",
        "status_updated_at": "2025-01-01T12:00:01+00:00",
        "url": "https://payout.playground.runa.io/11234567-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.

Webhooks

Get real-time updates for the product catalogue and your orders.

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.

On this page

The URL
What headers do I need to send?
The request body
The payment method
The order items
The distribution method
The product selection
Putting it all together
The request
The initial response
Getting the order details
Webhooks
Next steps

​The URL

​What headers do I need to send?

​The request body

​The payment method

​The order items

​The distribution method

To distribute via EMAIL

To distribute via PAYOUT_LINK

​The product selection

​Putting it all together

​The request

​The initial response

​Getting the order details

​Webhooks

Webhooks

​Next steps

Fetch the product catalog

Customizing the payout link

Pay using a different currency

Moving to production

API

Network

​The URL

​What headers do I need to send?

​The request body

​The payment method

​The order items

​The distribution method

To distribute via EMAIL

To distribute via PAYOUT_LINK

​The product selection

​Putting it all together

​The request

​The initial response

​Getting the order details

​Webhooks

Webhooks

​Next steps

Fetch the product catalog

Customizing the payout link

Pay using a different currency

Moving to production

The URL

What headers do I need to send?

The request body

The payment method

The order items

The distribution method

To distribute via `EMAIL`

To distribute via `PAYOUT_LINK`

The product selection

Putting it all together

The request

The initial response

Getting the order details

Webhooks

Next steps

The URL

What headers do I need to send?

The request body

The payment method

The order items

The distribution method

To distribute via `EMAIL`

To distribute via `PAYOUT_LINK`

The product selection

Putting it all together

The request

The initial response

Getting the order details

Webhooks

Next steps