Skip to main content
POST
/
v1
/
reservations
Reserve Transaction Capacity
curl --request POST \
  --url https://tracer.sandbox.lerian.net/v1/reservations \
  --header 'Content-Type: <content-type>' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "transactionId": "019c96a0-1071-7a0d-9916-a831221de252",
  "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "transactionType": "CARD",
  "amount": "1500.00",
  "currency": "USD",
  "transactionTimestamp": "2026-01-30T10:00:00Z",
  "account": {
    "accountId": "019c96a0-0c0d-7915-84b9-e497bfee9916",
    "type": "checking",
    "status": "active"
  }
}
'
import requests

url = "https://tracer.sandbox.lerian.net/v1/reservations"

payload = {
    "transactionId": "019c96a0-1071-7a0d-9916-a831221de252",
    "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
    "transactionType": "CARD",
    "amount": "1500.00",
    "currency": "USD",
    "transactionTimestamp": "2026-01-30T10:00:00Z",
    "account": {
        "accountId": "019c96a0-0c0d-7915-84b9-e497bfee9916",
        "type": "checking",
        "status": "active"
    }
}
headers = {
    "Content-Type": "<content-type>",
    "X-API-Key": "<api-key>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'Content-Type': '<content-type>', 'X-API-Key': '<api-key>'},
  body: JSON.stringify({
    transactionId: '019c96a0-1071-7a0d-9916-a831221de252',
    requestId: '019c96a0-10ce-75fc-a273-dc799079a99c',
    transactionType: 'CARD',
    amount: '1500.00',
    currency: 'USD',
    transactionTimestamp: '2026-01-30T10:00:00Z',
    account: {
      accountId: '019c96a0-0c0d-7915-84b9-e497bfee9916',
      type: 'checking',
      status: 'active'
    }
  })
};

fetch('https://tracer.sandbox.lerian.net/v1/reservations', 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://tracer.sandbox.lerian.net/v1/reservations",
  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([
    'transactionId' => '019c96a0-1071-7a0d-9916-a831221de252',
    'requestId' => '019c96a0-10ce-75fc-a273-dc799079a99c',
    'transactionType' => 'CARD',
    'amount' => '1500.00',
    'currency' => 'USD',
    'transactionTimestamp' => '2026-01-30T10:00:00Z',
    'account' => [
        'accountId' => '019c96a0-0c0d-7915-84b9-e497bfee9916',
        'type' => 'checking',
        'status' => 'active'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: <content-type>",
    "X-API-Key: <api-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://tracer.sandbox.lerian.net/v1/reservations"

	payload := strings.NewReader("{\n  \"transactionId\": \"019c96a0-1071-7a0d-9916-a831221de252\",\n  \"requestId\": \"019c96a0-10ce-75fc-a273-dc799079a99c\",\n  \"transactionType\": \"CARD\",\n  \"amount\": \"1500.00\",\n  \"currency\": \"USD\",\n  \"transactionTimestamp\": \"2026-01-30T10:00:00Z\",\n  \"account\": {\n    \"accountId\": \"019c96a0-0c0d-7915-84b9-e497bfee9916\",\n    \"type\": \"checking\",\n    \"status\": \"active\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "<content-type>")
	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://tracer.sandbox.lerian.net/v1/reservations")
  .header("Content-Type", "<content-type>")
  .header("X-API-Key", "<api-key>")
  .body("{\n  \"transactionId\": \"019c96a0-1071-7a0d-9916-a831221de252\",\n  \"requestId\": \"019c96a0-10ce-75fc-a273-dc799079a99c\",\n  \"transactionType\": \"CARD\",\n  \"amount\": \"1500.00\",\n  \"currency\": \"USD\",\n  \"transactionTimestamp\": \"2026-01-30T10:00:00Z\",\n  \"account\": {\n    \"accountId\": \"019c96a0-0c0d-7915-84b9-e497bfee9916\",\n    \"type\": \"checking\",\n    \"status\": \"active\"\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://tracer.sandbox.lerian.net/v1/reservations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = '<content-type>'
request["X-API-Key"] = '<api-key>'
request.body = "{\n  \"transactionId\": \"019c96a0-1071-7a0d-9916-a831221de252\",\n  \"requestId\": \"019c96a0-10ce-75fc-a273-dc799079a99c\",\n  \"transactionType\": \"CARD\",\n  \"amount\": \"1500.00\",\n  \"currency\": \"USD\",\n  \"transactionTimestamp\": \"2026-01-30T10:00:00Z\",\n  \"account\": {\n    \"accountId\": \"019c96a0-0c0d-7915-84b9-e497bfee9916\",\n    \"type\": \"checking\",\n    \"status\": \"active\"\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "transactionId": "019c96a0-1071-7a0d-9916-a831221de252",
  "denied": false,
  "reservationIds": [
    "019c96a0-10d2-7193-8841-0d7347efd09a"
  ]
}

Authorizations

​
X-API-Key
string
header
required

API Key authentication. Used by single-tenant deployments (MULTI_TENANT_ENABLED=false). Sent on every /v1/* request.

Headers

​
Content-Type
string
required

The type of media of the resource. Must be application/json.

​
X-API-Key
string
required

The API Key for authentication. This header is required for all endpoints except health checks.

​
X-Request-Id
string<uuid>

A unique identifier used to trace and track each request.

Body

application/json

Reserve request for phase one. Mirrors the transaction validation payload and adds the ledger transactionId the reservation lifecycle is keyed on. For reserves, transactionType and account are optional because the ledger may not know the payment rail or an internal account UUID at the reserve anchor; requestId, amount, currency and transactionTimestamp remain required.

​
transactionId
string<uuid>
required

Ledger transaction correlation ID the reservation is keyed on. Also the idempotency grain for retried reserves.

​
requestId
string<uuid>
required

Client-generated unique ID for idempotency and audit trail correlation.

​
amount
string
required

Transaction amount as a decimal string (e.g., "1500.00"). Must be a positive decimal value.

​
currency
string
required

ISO 4217 currency code (uppercase). Lowercase codes are rejected.

Required string length: 3
​
transactionTimestamp
string<date-time>
required

Transaction timestamp in RFC3339 format with timezone.

​
longLived
boolean
default:false

Selects the reservation lifetime. Use true for a pending transaction that must not expire while it remains valid; false (the default) for a direct transaction.

​
transactionType
enum<string>

Type of transaction (payment method). Optional for reserves.

Available options:
CARD,
WIRE,
Pix,
CRYPTO
​
subType
string

Transaction subtype for additional context (e.g., debit, credit, prepaid).

Maximum string length: 50
​
account
object

Account context for validation.

​
segment
object

Segment context (optional). If provided, segmentId is required.

​
portfolio
object

Portfolio context (optional). If provided, portfolioId is required.

​
merchant
object

Merchant context (optional, recommended for card transactions). If provided, merchantId is required.

​
metadata
object

Custom key-value pairs for rule expressions.

Response

Indicates that the reserve was processed. Inspect denied to confirm capacity was granted rather than rejected by a spending limit.

Handle returned on a successful reserve. When denied is true no capacity was held and reservationIds is empty; otherwise reservationIds holds one ID per counter-backed limit the ledger must later confirm or release.

​
transactionId
string<uuid>
required

The ledger transaction correlation ID from the request.

​
denied
boolean
required

Whether the reserve was denied because a spending limit would be exceeded. When true, no capacity is held.

​
reservationIds
string<uuid>[]
required

One reservation ID per counter-backed limit to confirm or release in phase two. Empty when denied.