Reservar capacidad de transacción

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"
  ]
}

Reservar capacidad de transacción

Usa este endpoint para reservar capacidad de transacción frente a los límites de gasto — fase uno del flujo de reserva en dos fases. Proporciona el transactionId del ledger sobre el que se indexa la reserva; la respuesta devuelve un ID de reserva por cada límite respaldado por contador que debas confirmar o liberar más tarde. Cuando se excedería un límite de gasto, la respuesta se devuelve con denied en true y no se retiene capacidad. Las reservas son idempotentes por transactionId — reintentar la misma reserva devuelve el mismo identificador.

POST

reservations

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"
  ]
}

Autorizaciones

X-API-Key

string

header

requerido

Autenticación por API Key. Utilizada por los despliegues de inquilino único (MULTI_TENANT_ENABLED=false). Se envía en cada solicitud /v1/*.

Encabezados

Content-Type

string

requerido

El tipo de medio del recurso. Debe ser application/json.

X-API-Key

string

requerido

La clave API para autenticacion. Este encabezado es requerido para todos los endpoints excepto verificaciones de salud.

X-Request-Id

string<uuid>

Un identificador unico usado para rastrear y seguir cada solicitud.

Cuerpo

application/json

Solicitud de reserva para la fase uno. Replica la carga útil de validación de transacción y añade el transactionId del ledger sobre el que se indexa el ciclo de vida de la reserva. Para las reservas, transactionType y account son opcionales porque el ledger puede no conocer el riel de pago o un UUID de cuenta interno en el punto de reserva; requestId, amount, currency y transactionTimestamp siguen siendo obligatorios.

transactionId

string<uuid>

requerido

ID de correlación de la transacción del ledger sobre el que se indexa la reserva. También es el grano de idempotencia para reservas reintentadas.

requestId

string<uuid>

requerido

ID único generado por el cliente para idempotencia y correlación del rastro de auditoría.

amount

string

requerido

Monto de la transacción como cadena decimal (p. ej., "1500.00"). Debe ser un valor decimal positivo.

currency

string

requerido

Código de moneda ISO 4217 (mayúsculas). Los códigos en minúsculas se rechazan.

Required string length: 3

transactionTimestamp

string<date-time>

requerido

Marca de tiempo de la transacción en formato RFC3339 con zona horaria.

longLived

boolean

predeterminado:false

Selecciona la vida útil de la reserva. Usa true para una transacción pendiente que no debe expirar mientras siga siendo válida; false (el valor por defecto) para una transacción directa.

transactionType

enum<string>

Tipo de transacción (método de pago). Opcional para las reservas.

Opciones disponibles:

CARD,

WIRE,

Pix,

CRYPTO

subType

string

Subtipo de transacción para contexto adicional (p. ej., débito, crédito, prepago).

Maximum string length: 50

account

object

Contexto de cuenta para validacion.

Show child attributes

segment

object

Contexto de segmento (opcional). Si se proporciona, segmentId es requerido.

Show child attributes

portfolio

object

Contexto de portafolio (opcional). Si se proporciona, portfolioId es requerido.

Show child attributes

merchant

object

Contexto de comerciante (opcional, recomendado para transacciones con tarjeta). Si se proporciona, merchantId es requerido.

Show child attributes

metadata

object

Pares clave-valor personalizados para las expresiones de reglas.

Respuesta

Indica que la reserva fue procesada. Revisa denied para confirmar si se concedió capacidad o si fue rechazada por un límite de gasto.

Identificador devuelto en una reserva exitosa. Cuando denied es true no se retuvo capacidad y reservationIds está vacío; de lo contrario, reservationIds contiene un ID por cada límite respaldado por contador que el ledger debe confirmar o liberar más tarde.

transactionId

string<uuid>

requerido

El ID de correlación de la transacción del ledger de la solicitud.

denied

boolean

requerido

Si la reserva fue rechazada porque se excedería un límite de gasto. Cuando es true, no se retiene capacidad.

reservationIds

string<uuid>[]

requerido

Un ID de reserva por cada límite respaldado por contador que confirmar o liberar en la fase dos. Vacío cuando se rechaza.

Recuperar Uso del Limite

Confirmar una reserva

⌘I