Glosario y convenciones de campo

Definiciones canónicas utilizadas en la documentación API.

Encabezados de solicitud

Encabezado	Requerido	Definición
x-api-key	Sí	Clave API emitida en la aplicación (sección "Negocios"). La organización se resuelve desde el host de solicitud
Content-Type	Sí (POST)	application/json para crear solicitudes

Monto y moneda

Término	Definición
amount	Cadena de un número entero en unidades menores (por ejemplo, centavos, fracción simbólica más pequeña)
amount_with_fee	Importe más tasa aplicada (unidades menores)
currency	Código de moneda/token similar a ISO (por ejemplo, USDT)
currency_dest	Moneda de destino para la conversión (FX). Opcional; por defecto es currency

Identificadores

Término	Definición
id	Sistema interno UUID de transacción
txid	Cadena proporcionada por el cliente que identifica una operación comercial; UUID es una opción conveniente, no un formato obligatorio

Enrutamiento

Término	Definición
route	Alias ​​de ruta de procesamiento configurado para la clave API
env	prod (predeterminado). Conserve este valor al abrir y confirmar la solicitud.

Estado del ciclo de vida

Estado	Significado
created	Aceptado, pendiente de procesamiento
new	Estado inicial antes de que comience el procesamiento
authorizing	Autorización en curso
pre_authorized_3ds	En espera de autenticación 3DS
action_required	En espera de una acción adicional (3DS / autorización extra)
charging	En curso (autorización/financiación)
payment_suspended	Transacción entrante suspendida temporalmente
payout_suspended	Transacción saliente suspendida temporalmente
charged	Completado con éxito (terminal)
reversed	Cargo revertido (terminal)
refunded	Reembolsado (terminal)
rejected	Fallo irrecuperable (terminal)
failed	Fallido (terminal)

Los estados de los terminales son charged, reversed, refunded, rejected, failed. El camino feliz más común es created → charging → charged.

Campos de tiempo

Campo	Definición
started	Marca de tiempo ISO cuando comenzó el procesamiento
finished	Marca de tiempo ISO cuando se completó el procesamiento; determinar el resultado del estado

Objetos de almacenamiento de dinero

Campo	Definición
network	Red blockchain (ETH, TRX, etc.)
type	Tipo de instrumento (bank_card, p2p_proxy, etc.)
wallet_id	Identificador interno de billetera (destino de pago/pago)
cardnumber	Tarjeta virtual PAN (enmascarada en algunas respuestas)
cvv	Código de seguridad de la tarjeta virtual (nunca inicie sesión en texto plano)
exp_month / exp_year	Valores de caducidad de la tarjeta (cadena, relleno con ceros)
cardholder	Nombre del titular de la tarjeta (ASCII o UTF-8)

Campos de error

Campo	Definición
error_description	Motivo del fallo legible por humanos (texto no estable)

Orientación sobre idempotencia

Utilice un txid único (idempotente) por operación comercial y consérvelo antes de enviarlo. El valor es una cadena; La generación de UUID es conveniente pero no se requiere la sintaxis de UUID. Vuelva a intentar la misma instrucción con el mismo identificador en la misma cuenta. No lo reutilices para un destinatario o monto diferente. Recuperar la operación original después de un tiempo de espera; un nuevo intento no debe convertirse silenciosamente en un nuevo pago.

Estrategia de encuesta

Lecturas de encuesta con retroceso acotado, por ejemplo 1s → 2s → 4s → 8s, con un presupuesto de interacción de 30s. Deténgase en un estado final conocido o cuando expire el presupuesto. Cuando se agote el tiempo, informe un resultado pendiente/desconocido y conserve el id/txid original. Los estados desconocidos no son un éxito. Consulte errores y reintentos.

Webhooks (informativo)

Los webhooks indican cambios de estado pero no tienen autoridad. Confirme siempre mediante la transacción GET.

Escala de importes

Las cantidades son cadenas de números enteros en unidades menores, no valores de punto flotante. Obtenga decimales para la moneda, la red de GET https://app.heth.me/api/v1/contracts?env=prod. USDT/ETH y USDT/TRX utilizan actualmente decimales 6: 1 USDT = "1000000", 0.25 USDT = "250000". ETH tiene decimales 18; Esto no se aplica a todos los tokens de Ethereum. Una báscula desconocida debe detener la conversión de cantidades. Consulte el esquema API.