Quick Start

This guide walks you through making your first API request using the Financial Events H2H endpoint.

Prerequisites

A TreasuryHub account with credentials issued for your environment
Your X-Client-Id (tenant identifier) and X-Access-Token
See Authentication for how credentials work

Environments

Environment	Base URL
Production	`https://api.gateway.treasuryhub.ai`
Sandbox	`https://sandbox.api.gateway.treasuryhub.ai`

Use Sandbox for development and testing. Production and Sandbox credentials are not interchangeable.

Step 1 — Get your credentials

Sandbox

Request manual provisioning — there is no self-service signup in Sandbox. Provide a fixed IP address; the Sandbox enforces an IP allowlist per tenant.

Production

Log in to the TreasuryHub Portal, create a client (tenant), and generate credentials. Configure token expiration and allowed IP ranges.

Once you have credentials you will have:

X-Client-Id — your tenant identifier
X-Access-Token — your access token (th_live_ prefix for Production, th_test_ for Sandbox)

Step 2 — Make your first request

Every request requires the three headers below. The example creates a Financial Event in Sandbox:

curl -X POST https://sandbox.api.gateway.treasuryhub.ai/api/h2h/ingestion/financial-events \
  -H "X-Client-Id: {{tenant_id}}" \
  -H "X-Access-Token: th_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ext-payin-001",
    "type": "INTERNAL_PAYIN",
    "countryCode": "MX",
    "currencyCode": "MXN",
    "amount": 1500.00,
    "status": "PENDING",
    "originalStatus": "CREATED",
    "payload": {}
  }'

A successful response returns 201 with the internal UUID:

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Use that UUID to retrieve the event:

curl https://sandbox.api.gateway.treasuryhub.ai/api/h2h/ingestion/financial-events/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Client-Id: {{tenant_id}}" \
  -H "X-Access-Token: th_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Step 3 — Explore the API reference

Financial Events — create, retrieve, and update H2H financial events

HTTP status codes

Code	Meaning
`200`	OK — request succeeded
`201`	Created — resource was created
`204`	No Content — request succeeded, no body returned
`400`	Bad Request — malformed request or duplicate `externalId`
`401`	Unauthorized — missing or invalid `X-Client-Id` / `X-Access-Token`
`404`	Not Found — resource does not exist
`422`	Unprocessable Entity — validation failed
`429`	Too Many Requests — rate limit exceeded
`500`	Internal Server Error

Esta guía te lleva paso a paso para realizar tu primera solicitud a la API usando el endpoint H2H de Financial Events.

Requisitos previos

Una cuenta de TreasuryHub con credenciales emitidas para tu entorno
Tu X-Client-Id (identificador de tenant) y X-Access-Token
Ver Autenticación para entender cómo funcionan las credenciales

Entornos

Entorno	URL Base
Producción	`https://api.gateway.treasuryhub.ai`
Sandbox	`https://sandbox.api.gateway.treasuryhub.ai`

Usa Sandbox para desarrollo y pruebas. Las credenciales de Producción y Sandbox no son intercambiables.

Paso 1 — Obtén tus credenciales

Sandbox

Solicita el aprovisionamiento manual — no existe registro de autoservicio en Sandbox. Debes proporcionar una dirección IP fija; el Sandbox aplica una lista de IPs permitidas por tenant.

Producción

Inicia sesión en el TreasuryHub Portal, crea un client (tenant) y genera las credenciales. Configura la expiración del token y los rangos de IP permitidos.

Una vez que tengas las credenciales dispondrás de:

X-Client-Id — tu identificador de tenant
X-Access-Token — tu token de acceso (prefijo th_live_ para Producción, th_test_ para Sandbox)

Paso 2 — Realiza tu primera solicitud

Toda solicitud requiere los tres encabezados a continuación. El ejemplo crea un Financial Event en Sandbox:

curl -X POST https://sandbox.api.gateway.treasuryhub.ai/api/h2h/ingestion/financial-events \
  -H "X-Client-Id: {{tenant_id}}" \
  -H "X-Access-Token: th_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "ext-payin-001",
    "type": "INTERNAL_PAYIN",
    "countryCode": "MX",
    "currencyCode": "MXN",
    "amount": 1500.00,
    "status": "PENDING",
    "originalStatus": "CREATED",
    "payload": {}
  }'

Una respuesta exitosa devuelve 201 con el UUID interno:

{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Usa ese UUID para recuperar el evento:

curl https://sandbox.api.gateway.treasuryhub.ai/api/h2h/ingestion/financial-events/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Client-Id: {{tenant_id}}" \
  -H "X-Access-Token: th_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Paso 3 — Explora la referencia API

Financial Events — crear, consultar y actualizar eventos financieros H2H

Códigos de estado HTTP

Código	Significado
`200`	OK — solicitud exitosa
`201`	Creado — el recurso fue creado
`204`	Sin Contenido — solicitud exitosa, sin cuerpo
`400`	Solicitud Incorrecta — sintaxis incorrecta o `externalId` duplicado
`401`	No Autorizado — `X-Client-Id` o `X-Access-Token` ausente o inválido
`404`	No Encontrado — el recurso no existe
`422`	Entidad No Procesable — validación fallida
`429`	Demasiadas Solicitudes — límite de tasa excedido
`500`	Error Interno del Servidor