curl --request POST \
--url https://playground.runa.io/v2/order \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--data '
{
"payment_method": {
"type": "ACCOUNT_BALANCE",
"currency": "USD"
},
"items": [
{
"face_value": "10.00",
"distribution_method": {
"type": "EMAIL",
"email_address": "fred@example.com",
"template_id": "DT-01HPSF51G0ZWHJ3JTNWRH0WDYK"
},
"products": {
"type": "SINGLE",
"value": "AMZ-US"
}
}
],
"description": "Your own reference text",
"metadata": {
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
}
'import requests
url = "https://playground.runa.io/v2/order"
payload = {
"payment_method": {
"type": "ACCOUNT_BALANCE",
"currency": "USD"
},
"items": [
{
"face_value": "10.00",
"distribution_method": {
"type": "EMAIL",
"email_address": "fred@example.com",
"template_id": "DT-01HPSF51G0ZWHJ3JTNWRH0WDYK"
},
"products": {
"type": "SINGLE",
"value": "AMZ-US"
}
}
],
"description": "Your own reference text",
"metadata": {
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
}
headers = {
"X-Idempotency-Key": "<x-idempotency-key>",
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Idempotency-Key': '<x-idempotency-key>',
'X-Api-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
payment_method: {type: 'ACCOUNT_BALANCE', currency: 'USD'},
items: [
{
face_value: '10.00',
distribution_method: {
type: 'EMAIL',
email_address: 'fred@example.com',
template_id: 'DT-01HPSF51G0ZWHJ3JTNWRH0WDYK'
},
products: {type: 'SINGLE', value: 'AMZ-US'}
}
],
description: 'Your own reference text',
metadata: {internal_id: '12345', department: 'marketing', campaign: 'summer_2024'}
})
};
fetch('https://playground.runa.io/v2/order', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://playground.runa.io/v2/order",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'payment_method' => [
'type' => 'ACCOUNT_BALANCE',
'currency' => 'USD'
],
'items' => [
[
'face_value' => '10.00',
'distribution_method' => [
'type' => 'EMAIL',
'email_address' => 'fred@example.com',
'template_id' => 'DT-01HPSF51G0ZWHJ3JTNWRH0WDYK'
],
'products' => [
'type' => 'SINGLE',
'value' => 'AMZ-US'
]
]
],
'description' => 'Your own reference text',
'metadata' => [
'internal_id' => '12345',
'department' => 'marketing',
'campaign' => 'summer_2024'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>",
"X-Idempotency-Key: <x-idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://playground.runa.io/v2/order"
payload := strings.NewReader("{\n \"payment_method\": {\n \"type\": \"ACCOUNT_BALANCE\",\n \"currency\": \"USD\"\n },\n \"items\": [\n {\n \"face_value\": \"10.00\",\n \"distribution_method\": {\n \"type\": \"EMAIL\",\n \"email_address\": \"fred@example.com\",\n \"template_id\": \"DT-01HPSF51G0ZWHJ3JTNWRH0WDYK\"\n },\n \"products\": {\n \"type\": \"SINGLE\",\n \"value\": \"AMZ-US\"\n }\n }\n ],\n \"description\": \"Your own reference text\",\n \"metadata\": {\n \"internal_id\": \"12345\",\n \"department\": \"marketing\",\n \"campaign\": \"summer_2024\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://playground.runa.io/v2/order")
.header("X-Idempotency-Key", "<x-idempotency-key>")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"payment_method\": {\n \"type\": \"ACCOUNT_BALANCE\",\n \"currency\": \"USD\"\n },\n \"items\": [\n {\n \"face_value\": \"10.00\",\n \"distribution_method\": {\n \"type\": \"EMAIL\",\n \"email_address\": \"fred@example.com\",\n \"template_id\": \"DT-01HPSF51G0ZWHJ3JTNWRH0WDYK\"\n },\n \"products\": {\n \"type\": \"SINGLE\",\n \"value\": \"AMZ-US\"\n }\n }\n ],\n \"description\": \"Your own reference text\",\n \"metadata\": {\n \"internal_id\": \"12345\",\n \"department\": \"marketing\",\n \"campaign\": \"summer_2024\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://playground.runa.io/v2/order")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"payment_method\": {\n \"type\": \"ACCOUNT_BALANCE\",\n \"currency\": \"USD\"\n },\n \"items\": [\n {\n \"face_value\": \"10.00\",\n \"distribution_method\": {\n \"type\": \"EMAIL\",\n \"email_address\": \"fred@example.com\",\n \"template_id\": \"DT-01HPSF51G0ZWHJ3JTNWRH0WDYK\"\n },\n \"products\": {\n \"type\": \"SINGLE\",\n \"value\": \"AMZ-US\"\n }\n }\n ],\n \"description\": \"Your own reference text\",\n \"metadata\": {\n \"internal_id\": \"12345\",\n \"department\": \"marketing\",\n \"campaign\": \"summer_2024\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "O-01H5WQGHKCBB85MQFM68S9KJ5Q",
"status": "PROCESSING",
"created_at": "2023-11-07T05:31:56Z",
"payment_method": {
"type": "ACCOUNT_BALANCE",
"currency": "USD"
},
"currency": "USD",
"total_price": "10.00",
"total_discount": "1.00",
"items": [
{
"id": "E-NWPEKW4VL",
"distribution_method": {
"type": "EMAIL",
"email_address": "fred@example.com",
"template_id": "DT-01HPSF51G0ZWHJ3JTNWRH0WDYK"
},
"products": {
"type": "MULTIPLE",
"values": [
"AMZ-US",
"AIRBNB-US"
]
},
"face_value": "10.00",
"price": "10.00",
"payout": {
"status": "ACTIVE",
"status_updated_at": "2023-11-07T05:31:56Z",
"url": "<string>",
"expiry_date": "2023-11-07T05:31:56Z"
},
"currency": "USD"
}
],
"completed_at": "2023-11-07T05:31:56Z",
"description": "Your own reference text",
"transaction_detail": {
"USD": {
"value": "10.00",
"fx": null
}
},
"metadata": {
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
}{
"id": "O-01H5WQGHKCBB85MQFM68S9KJ5Q",
"status": "PROCESSING",
"created_at": "2023-11-07T05:31:56Z",
"payment_method": {
"type": "ACCOUNT_BALANCE",
"currency": "USD"
},
"currency": "USD",
"total_price": "10.00",
"total_discount": "1.00",
"items": [
{
"id": "E-NWPEKW4VL",
"distribution_method": {
"type": "EMAIL",
"email_address": "fred@example.com",
"template_id": "DT-01HPSF51G0ZWHJ3JTNWRH0WDYK"
},
"products": {
"type": "MULTIPLE",
"values": [
"AMZ-US",
"AIRBNB-US"
]
},
"face_value": "10.00",
"price": "10.00",
"payout": {
"status": "ACTIVE",
"status_updated_at": "2023-11-07T05:31:56Z",
"url": "<string>",
"expiry_date": "2023-11-07T05:31:56Z"
},
"currency": "USD"
}
],
"completed_at": "2023-11-07T05:31:56Z",
"description": "Your own reference text",
"transaction_detail": {
"USD": {
"value": "10.00",
"fx": null
}
},
"metadata": {
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
}{
"type": "not_found",
"message": "The requested resource was not found",
"help": "Please check the resource ID and try again."
}{
"type": "not_found",
"message": "The requested resource was not found",
"help": "Please check the resource ID and try again."
}{
"type": "not_found",
"message": "The requested resource was not found",
"help": "Please check the resource ID and try again."
}{
"type": "validation_error",
"message": "There were one or more problems processing your request, see details key.",
"details": [
{
"type": "value_error.number.not_ge",
"message": "ensure this value is greater than or equal to 1",
"location": [
"items",
"0",
"face_value"
]
}
],
"help": null
}{
"type": "rate_limit",
"message": "You've exceeded the rate limit, please wait a short period and try again.",
"help": "See https://developer.runa.io/rate-limits for details."
}{
"type": "not_found",
"message": "The requested resource was not found",
"help": "Please check the resource ID and try again."
}Create a new order
Creates a new order, supports both sync and async execution modes
curl --request POST \
--url https://playground.runa.io/v2/order \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--data '
{
"payment_method": {
"type": "ACCOUNT_BALANCE",
"currency": "USD"
},
"items": [
{
"face_value": "10.00",
"distribution_method": {
"type": "EMAIL",
"email_address": "fred@example.com",
"template_id": "DT-01HPSF51G0ZWHJ3JTNWRH0WDYK"
},
"products": {
"type": "SINGLE",
"value": "AMZ-US"
}
}
],
"description": "Your own reference text",
"metadata": {
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
}
'import requests
url = "https://playground.runa.io/v2/order"
payload = {
"payment_method": {
"type": "ACCOUNT_BALANCE",
"currency": "USD"
},
"items": [
{
"face_value": "10.00",
"distribution_method": {
"type": "EMAIL",
"email_address": "fred@example.com",
"template_id": "DT-01HPSF51G0ZWHJ3JTNWRH0WDYK"
},
"products": {
"type": "SINGLE",
"value": "AMZ-US"
}
}
],
"description": "Your own reference text",
"metadata": {
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
}
headers = {
"X-Idempotency-Key": "<x-idempotency-key>",
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Idempotency-Key': '<x-idempotency-key>',
'X-Api-Key': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
payment_method: {type: 'ACCOUNT_BALANCE', currency: 'USD'},
items: [
{
face_value: '10.00',
distribution_method: {
type: 'EMAIL',
email_address: 'fred@example.com',
template_id: 'DT-01HPSF51G0ZWHJ3JTNWRH0WDYK'
},
products: {type: 'SINGLE', value: 'AMZ-US'}
}
],
description: 'Your own reference text',
metadata: {internal_id: '12345', department: 'marketing', campaign: 'summer_2024'}
})
};
fetch('https://playground.runa.io/v2/order', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://playground.runa.io/v2/order",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'payment_method' => [
'type' => 'ACCOUNT_BALANCE',
'currency' => 'USD'
],
'items' => [
[
'face_value' => '10.00',
'distribution_method' => [
'type' => 'EMAIL',
'email_address' => 'fred@example.com',
'template_id' => 'DT-01HPSF51G0ZWHJ3JTNWRH0WDYK'
],
'products' => [
'type' => 'SINGLE',
'value' => 'AMZ-US'
]
]
],
'description' => 'Your own reference text',
'metadata' => [
'internal_id' => '12345',
'department' => 'marketing',
'campaign' => 'summer_2024'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>",
"X-Idempotency-Key: <x-idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://playground.runa.io/v2/order"
payload := strings.NewReader("{\n \"payment_method\": {\n \"type\": \"ACCOUNT_BALANCE\",\n \"currency\": \"USD\"\n },\n \"items\": [\n {\n \"face_value\": \"10.00\",\n \"distribution_method\": {\n \"type\": \"EMAIL\",\n \"email_address\": \"fred@example.com\",\n \"template_id\": \"DT-01HPSF51G0ZWHJ3JTNWRH0WDYK\"\n },\n \"products\": {\n \"type\": \"SINGLE\",\n \"value\": \"AMZ-US\"\n }\n }\n ],\n \"description\": \"Your own reference text\",\n \"metadata\": {\n \"internal_id\": \"12345\",\n \"department\": \"marketing\",\n \"campaign\": \"summer_2024\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Idempotency-Key", "<x-idempotency-key>")
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://playground.runa.io/v2/order")
.header("X-Idempotency-Key", "<x-idempotency-key>")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"payment_method\": {\n \"type\": \"ACCOUNT_BALANCE\",\n \"currency\": \"USD\"\n },\n \"items\": [\n {\n \"face_value\": \"10.00\",\n \"distribution_method\": {\n \"type\": \"EMAIL\",\n \"email_address\": \"fred@example.com\",\n \"template_id\": \"DT-01HPSF51G0ZWHJ3JTNWRH0WDYK\"\n },\n \"products\": {\n \"type\": \"SINGLE\",\n \"value\": \"AMZ-US\"\n }\n }\n ],\n \"description\": \"Your own reference text\",\n \"metadata\": {\n \"internal_id\": \"12345\",\n \"department\": \"marketing\",\n \"campaign\": \"summer_2024\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://playground.runa.io/v2/order")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"payment_method\": {\n \"type\": \"ACCOUNT_BALANCE\",\n \"currency\": \"USD\"\n },\n \"items\": [\n {\n \"face_value\": \"10.00\",\n \"distribution_method\": {\n \"type\": \"EMAIL\",\n \"email_address\": \"fred@example.com\",\n \"template_id\": \"DT-01HPSF51G0ZWHJ3JTNWRH0WDYK\"\n },\n \"products\": {\n \"type\": \"SINGLE\",\n \"value\": \"AMZ-US\"\n }\n }\n ],\n \"description\": \"Your own reference text\",\n \"metadata\": {\n \"internal_id\": \"12345\",\n \"department\": \"marketing\",\n \"campaign\": \"summer_2024\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "O-01H5WQGHKCBB85MQFM68S9KJ5Q",
"status": "PROCESSING",
"created_at": "2023-11-07T05:31:56Z",
"payment_method": {
"type": "ACCOUNT_BALANCE",
"currency": "USD"
},
"currency": "USD",
"total_price": "10.00",
"total_discount": "1.00",
"items": [
{
"id": "E-NWPEKW4VL",
"distribution_method": {
"type": "EMAIL",
"email_address": "fred@example.com",
"template_id": "DT-01HPSF51G0ZWHJ3JTNWRH0WDYK"
},
"products": {
"type": "MULTIPLE",
"values": [
"AMZ-US",
"AIRBNB-US"
]
},
"face_value": "10.00",
"price": "10.00",
"payout": {
"status": "ACTIVE",
"status_updated_at": "2023-11-07T05:31:56Z",
"url": "<string>",
"expiry_date": "2023-11-07T05:31:56Z"
},
"currency": "USD"
}
],
"completed_at": "2023-11-07T05:31:56Z",
"description": "Your own reference text",
"transaction_detail": {
"USD": {
"value": "10.00",
"fx": null
}
},
"metadata": {
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
}{
"id": "O-01H5WQGHKCBB85MQFM68S9KJ5Q",
"status": "PROCESSING",
"created_at": "2023-11-07T05:31:56Z",
"payment_method": {
"type": "ACCOUNT_BALANCE",
"currency": "USD"
},
"currency": "USD",
"total_price": "10.00",
"total_discount": "1.00",
"items": [
{
"id": "E-NWPEKW4VL",
"distribution_method": {
"type": "EMAIL",
"email_address": "fred@example.com",
"template_id": "DT-01HPSF51G0ZWHJ3JTNWRH0WDYK"
},
"products": {
"type": "MULTIPLE",
"values": [
"AMZ-US",
"AIRBNB-US"
]
},
"face_value": "10.00",
"price": "10.00",
"payout": {
"status": "ACTIVE",
"status_updated_at": "2023-11-07T05:31:56Z",
"url": "<string>",
"expiry_date": "2023-11-07T05:31:56Z"
},
"currency": "USD"
}
],
"completed_at": "2023-11-07T05:31:56Z",
"description": "Your own reference text",
"transaction_detail": {
"USD": {
"value": "10.00",
"fx": null
}
},
"metadata": {
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
}{
"type": "not_found",
"message": "The requested resource was not found",
"help": "Please check the resource ID and try again."
}{
"type": "not_found",
"message": "The requested resource was not found",
"help": "Please check the resource ID and try again."
}{
"type": "not_found",
"message": "The requested resource was not found",
"help": "Please check the resource ID and try again."
}{
"type": "validation_error",
"message": "There were one or more problems processing your request, see details key.",
"details": [
{
"type": "value_error.number.not_ge",
"message": "ensure this value is greater than or equal to 1",
"location": [
"items",
"0",
"face_value"
]
}
],
"help": null
}{
"type": "rate_limit",
"message": "You've exceeded the rate limit, please wait a short period and try again.",
"help": "See https://developer.runa.io/rate-limits for details."
}{
"type": "not_found",
"message": "The requested resource was not found",
"help": "Please check the resource ID and try again."
}Need help with your first order?
Authorizations
Headers
The dated version of the API, if not specified a default is used. See API versioning for more information. The dated version of the Runa API. Send it on every request: a client that omits it silently follows whatever the server default happens to be.
2024-02-05 A unique string that prevents order duplication. See Idempotency for more information.
Whether to process the order synchronously or asynchronously. If this header is omitted we default to async. See which mode to use to help you decide which execution mode is right for your use case. Sync orders are limited to a single order item.
async, sync Body
The details of the order to create.
Payment method for the order. Select the ACCOUNT_BALANCE you want to pay for the order from
Show child attributes
Show child attributes
The list of items to be included in the order. Each item ordered results in a single payout link. The maximum number of items per order is 200.
1 - 200 elementsShow child attributes
Show child attributes
Free format text reference for the order. The order description will not be visible to the end user. You will see this description in the Runa web portal.
This field is optional and can be omitted if not needed.
If not provided, the field will be set to null in the response.
128"Your own reference text"
A flexible field for you to attach additional, customer-specific data to the order. This is for your internal use, the information stored here will not be exposed to the end user.
- All keys and their corresponding values must be strings
- Each order supports up to 20 key-value pairs
- Keys have a maximum length of 40 characters
- Values can be up to 200 characters long.
This field is optional and can be omitted if not needed.
If not provided, the field will be set to null in the response.
Show child attributes
Show child attributes
{
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
Response
Response that will be returned in sync execution mode. Order has successfully been completed.
- Completed order
- Accepted order
Used for an order that has completed. This class is typically used when returning a single order to the client.
The ID of the order.
"O-01H5WQGHKCBB85MQFM68S9KJ5Q"
Always COMPLETED for this schema.
COMPLETED "PROCESSING"
UTC timestamp, in ISO 8601 format, when the order was submitted.
The payment method used for the order.
Show child attributes
Show child attributes
The currency of the order, represented by ISO 4217 currency codes. Please check the currency section in the guidelines for how to use this field.
^[A-Z]{3}$"USD"
The total price of the order. This includes any applicable fees.
^[0-9]+(\.[0-9]{1,2})?$"10.00"
The total discount of the order.
^[0-9]+(\.[0-9]{1,2})?$"1.00"
The list of items that were included in the order. Each item represents a single payout link.
Show child attributes
Show child attributes
UTC timestamp, in ISO 8601 format, when the order was completed.
Free format text reference for the order. The order description will not be visible to the end user. You will see this description in the Runa web portal.
This field is optional and can be omitted if not needed.
If not provided, the field will be set to null in the response.
128"Your own reference text"
A mapping of the subtotal of the order using the payout currency as a key.
Show child attributes
Show child attributes
{ "USD": { "value": "10.00", "fx": null } }
A flexible field for you to attach additional, customer-specific data to the order. This is for your internal use, the information stored here will not be exposed to the end user.
- All keys and their corresponding values must be strings
- Each order supports up to 20 key-value pairs
- Keys have a maximum length of 40 characters
- Values can be up to 200 characters long.
This field is optional and can be omitted if not needed.
If not provided, the field will be set to null in the response.
Show child attributes
Show child attributes
{
"internal_id": "12345",
"department": "marketing",
"campaign": "summer_2024"
}
Was this page helpful?