Referencia de la API

Simular un pago Sandbox

POST/v1/simulate

Contrato v1 / 1.1.3 5 / 2026-11-17

En esta página

Ejecuta un escenario con clave de prueba de escritura y permiso simulation. Requiere Idempotency-Key; un reintento idéntico devuelve el resultado guardado sin otra transición ni envío. Reutilizar la clave con parámetros distintos devuelve 409. Datos, destinatarios, cuotas y saldos se separan de Live. No se crea una transacción blockchain. Se admiten expire y late; Pay y las suscripciones quedan excluidos.

Permisos de la clave: simulation / write.

Parámetros

ParámetroEntranteObligatorioDescripción
Idempotency-KeyheaderSí16–80 letras ASCII, dígitos, guiones o guiones bajos. Conserva la misma clave y solicitud exacta al reintentar. Usa una clave nueva para cada transición distinta.
string minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$

Cuerpo de la solicitud

CampoTipoObligatorioDescripción
operation_idstringNoCopia opcional de Idempotency-Key en el cuerpo; debe coincidir exactamente con la cabecera. Se recomienda usar solo la cabecera.
minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$
invoice_idstringNoFactura Sandbox de la cuenta y proyecto autorizados por la clave. Indica exactamente invoice_id o watch_id.
minLength: 1
watch_idstringNoDirección Sandbox activa de la cuenta y proyecto/servicio autorizados por la clave. Indica un solo destino.
minLength: 1
transaction_idstringNoOmítelo para un pago de prueba nuevo. Reutiliza el identificador simulated_ devuelto para sus transiciones posteriores. Un identificador desconocido devuelve 404; el activo y el importe no cambian.
pattern: ^simulated_[0-9]+$
event_typestringNoTransición de la transacción de prueba. Confirma o revierte el mismo transaction_id para probar su ciclo de vida.
payment.pending, payment.confirmed, payment.rolled_back; Predeterminado: payment.confirmed
amount_rawstringNoImporte entero positivo en unidades mínimas del activo. Por defecto se usa el importe de la factura, el de la transacción existente o una unidad completa del activo del catálogo para un pago de dirección nuevo. Usa una transacción nueva para otro pago parcial.
minLength: 1; maxLength: 78; pattern: ^[0-9]+$
assetstringNoEl activo de la factura queda fijado. Si una dirección tiene varias reglas de activos, selecciona un activo permitido del catálogo. No se puede deducir la precisión de un token desconocido.
decimalsintegerNoComprobación opcional: debe coincidir con la precisión fijada en la factura o el catálogo. No modifica la precisión.
minimum: 0; maximum: 255
occurred_atstringNoHora opcional del evento, desde 30 días antes hasta 7 días y 1 minuto después del momento actual. No cambia otros objetos ni el reloj del sistema. late fija su propia hora.
date-time
actionstringNoEscenario exclusivo de facturas. expire aplica el vencimiento de esta factura sin evento ni webhook. late vence la factura y simula un pago confirmado un segundo después. invoice_status sigue las reglas normales de aceptación; late no garantiza un estado concreto.
expire, late
application/json
{
  "invoice_id": "2001",
  "event_type": "payment.pending",
  "amount_raw": "1000000"
}

Ejemplos de solicitudes

Los ejemplos realizan una operación real en tu cuenta. Configura las variables de entorno indicadas en el código. Mantén tu clave privada; las solicitudes de escritura no se reintentan automáticamente.

Shell / cURL
#!/usr/bin/env bash
set -euo pipefail
: "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}"
: "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}"
response_file="$(mktemp)"
trap 'rm -f "$response_file"' EXIT
transfer_status=0
http_status="$(curl \
  --silent --show-error --max-time 30 --request POST \
  --header "Authorization: Bearer $CRYPTANIO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \
  --data-binary '{"invoice_id":"2001","event_type":"payment.pending","amount_raw":"1000000"}' \
  "https://api.cryptanio.com/v1/simulate" \
  --output "$response_file" --write-out '%{http_code}')" || transfer_status=$?
if [[ "$http_status" == 2?? ]]; then
  cat "$response_file"
  exit "$transfer_status"
fi
printf 'HTTP %s\n' "$http_status" >&2
cat "$response_file" >&2
exit 1
Descargar ejemplo
Go
// Go; standard library only. Run: go run request.go
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "time"
)

func env(name string) string {
    value := os.Getenv(name)
    if value == "" { fmt.Fprintln(os.Stderr, "Set", name); os.Exit(1) }
    return value
}
func run() error {
    path := "/v1/simulate"

    endpoint, err := url.Parse("https://api.cryptanio.com" + path)
    if err != nil { return err }
    query := endpoint.Query()

    endpoint.RawQuery = query.Encode()
    var payload map[string]any
    if err := json.Unmarshal([]byte("{\"invoice_id\":\"2001\",\"event_type\":\"payment.pending\",\"amount_raw\":\"1000000\"}"), &payload); err != nil { return err }

    body, err := json.Marshal(payload)
    if err != nil { return err }
    request, err := http.NewRequest("POST", endpoint.String(), bytes.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + env("CRYPTANIO_API_KEY"))
    request.Header.Set("Accept", "application/json")
    request.Header.Set("Content-Type", "application/json")
    request.Header.Set("Idempotency-Key", env("CRYPTANIO_OPERATION_ID"))
    client := &http.Client{Timeout: 30 * time.Second, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }}
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        body, err := io.ReadAll(response.Body)
        if err != nil { return err }
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, body)
    }
    _, err = io.Copy(os.Stdout, response.Body)
    return err
}
func main() {
    if err := run(); err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) }
}
Descargar ejemplo
Rust
// Cargo.toml dependencies:
// reqwest = { version = "=0.12.24", features = ["blocking", "json"] }
// serde_json = "=1.0.145"
use std::{error::Error, io, time::Duration};
use reqwest::{blocking::Client, redirect::Policy, Method, Url};

fn env(name: &str) -> Result<String, Box<dyn Error>> {
    let value = std::env::var(name)?;
    if value.is_empty() { return Err(format!("Set {name}").into()); }
    Ok(value)
}
fn run() -> Result<(), Box<dyn Error>> {
    let mut url = Url::parse("https://api.cryptanio.com")?;
    {
        let mut segments = url.path_segments_mut().map_err(|_| "Invalid base URL")?;
        segments.clear();
        segments.push("v1");
        segments.push("simulate");
    }
    let client = Client::builder().timeout(Duration::from_secs(30)).redirect(Policy::none()).build()?;
    let request = client.request(Method::POST, url)
        .header("Authorization", format!("Bearer {}", env("CRYPTANIO_API_KEY")?))
        .header("Accept", "application/json".to_owned())
        .header("Content-Type", "application/json".to_owned())
        .header("Idempotency-Key", env("CRYPTANIO_OPERATION_ID")?);
    let mut body: serde_json::Value = serde_json::from_str("{\"invoice_id\":\"2001\",\"event_type\":\"payment.pending\",\"amount_raw\":\"1000000\"}")?;

    let request = request.json(&body);
    let mut response = request.send()?;
    let status = response.status();
    if !status.is_success() { return Err(format!("HTTP {}: {}", status.as_u16(), response.text()?).into()); }
    io::copy(&mut response, &mut io::stdout())?;
    Ok(())
}
fn main() {
    if let Err(error) = run() { eprintln!("{error}"); std::process::exit(1); }
}
Descargar ejemplo
PHP
<?php
// PHP 8 with the cURL extension. Run this on your server.
function env(string $name): string {
    $value = getenv($name);
    if ($value === false || $value === '') throw new RuntimeException('Set ' . $name);
    return $value;
}
try {
    $path = '/v1/simulate';

    $query = [

    ];
    $url = 'https://api.cryptanio.com' . $path . ($query ? '?' . http_build_query($query, '', '&', PHP_QUERY_RFC3986) : '');
    $headers = [
        'Authorization: ' . 'Bearer ' . env('CRYPTANIO_API_KEY'),
        'Accept: ' . 'application/json',
        'Content-Type: ' . 'application/json',
        'Idempotency-Key: ' . env('CRYPTANIO_OPERATION_ID'),
    ];
    $body = json_decode('{"invoice_id":"2001","event_type":"payment.pending","amount_raw":"1000000"}', true, 512, JSON_THROW_ON_ERROR);

    $curl = curl_init($url);
    curl_setopt_array($curl, [
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_HTTPHEADER => $headers,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_FOLLOWLOCATION => false,
        CURLOPT_CONNECTTIMEOUT => 10,
        CURLOPT_TIMEOUT => 30,
        CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
    ]);
    $response = curl_exec($curl);
    if ($response === false) throw new RuntimeException(curl_error($curl));
    $status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
    if ($status < 200 || $status >= 300) throw new RuntimeException('HTTP ' . $status . ': ' . $response);
    echo $response;
} catch (Throwable $error) {
    fwrite(STDERR, $error->getMessage() . PHP_EOL);
    exit(1);
}
Descargar ejemplo
Python
# Python 3; standard library only.
import json
import os
import sys
from urllib.error import HTTPError, URLError
from urllib.parse import quote, urlencode
from urllib.request import HTTPRedirectHandler, Request, build_opener

def env(name):
    result = os.environ.get(name)
    if not result:
        raise ValueError("Set " + name)
    return result

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

try:
    path = "/v1/simulate"

    query = {

    }
    url = "https://api.cryptanio.com" + path + ("?" + urlencode(query) if query else "")
    headers = {
        "Authorization": "Bearer " + env("CRYPTANIO_API_KEY"),
        "Accept": "application/json",
        "Content-Type": "application/json",
        "Idempotency-Key": env("CRYPTANIO_OPERATION_ID"),
    }
    body = json.loads("{\"invoice_id\":\"2001\",\"event_type\":\"payment.pending\",\"amount_raw\":\"1000000\"}")

    data = json.dumps(body).encode("utf-8")
    request = Request(url, data=data, headers=headers, method="POST")
    with build_opener(NoRedirect()).open(request, timeout=30) as response:
        if not 200 <= response.status < 300:
            raise ValueError("HTTP " + str(response.status))
        sys.stdout.buffer.write(response.read())
except HTTPError as error:
    print("HTTP " + str(error.code) + ": " + error.read().decode("utf-8", errors="replace"), file=sys.stderr)
    sys.exit(1)
except (ValueError, URLError, OSError) as error:
    print(str(error), file=sys.stderr)
    sys.exit(1)
Descargar ejemplo
Node.js
// Node.js 18+. Run on your server, never in a browser.
const env = name => {
  const result = process.env[name];
  if (!result) throw new Error(`Set ${name}`);
  return result;
};
try {
  let path = "/v1/simulate";

  const url = new URL(path, "https://api.cryptanio.com");

  const headers = {
    "Authorization": "Bearer " + env("CRYPTANIO_API_KEY"),
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Idempotency-Key": env("CRYPTANIO_OPERATION_ID"),
  };
  const body = {
    "invoice_id": "2001",
    "event_type": "payment.pending",
    "amount_raw": "1000000"
  };

  const response = await fetch(url, {
    method: "POST", headers, redirect: "manual",
    signal: AbortSignal.timeout(30_000), body: JSON.stringify(body),
  });
  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  if (response.body) {
    for await (const chunk of response.body) process.stdout.write(chunk);
  }
} catch (error) {
  console.error(error.message);
  process.exitCode = 1;
}
Descargar ejemplo

Respuestas y errores

202 Escenario aceptado, o resultado guardado de un reintento idéntico.
CampoTipoObligatorioDescripción
event_idstringNoID del evento registrado. Se omite para expire, que no crea un evento.
event_typestringNoTransición de pago registrada; se omite para expire.
watch_idstringSíDirección Sandbox usada por este escenario.
transaction_idstringNoIdentificador estable del pago de prueba para transiciones posteriores; se omite para expire.
invoice_idstringNoFactura Sandbox afectada cuando el escenario se dirige a una factura.
invoice_statusstringNoEstado real de la factura tras la operación; no presupongas un resultado fijo de pago tardío o vencimiento.
actionstringNoEscenario explícito de factura, si se solicita.
expire, late
queuedbooleanSíSe ha encolado el procesamiento de la notificación. Esto no confirma la aceptación de un envío externo.
replayedbooleanSíVerdadero si se devuelve la misma operación idempotente sin otra transición ni evento.
202 application/json
{
  "event_id": "2301",
  "event_type": "payment.pending",
  "watch_id": "2000",
  "transaction_id": "simulated_2300",
  "invoice_id": "2001",
  "invoice_status": "pending",
  "queued": true,
  "replayed": false
}
400 Solicitud inválida (bad_request, unsupported_asset).
CampoTipoObligatorioDescripción
errorobjectSí
400 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
401 No hay una clave API activa válida (unauthorized).
CampoTipoObligatorioDescripción
errorobjectSí
401 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
403 La clave no permite la operación, el proyecto, el servicio o la IP; correo sin confirmar.
CampoTipoObligatorioDescripción
errorobjectSí
403 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
404 Objeto no encontrado en el ámbito de la clave (not_found).
CampoTipoObligatorioDescripción
errorobjectSí
404 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
409 Conflicto de estado, parámetros de reintento distintos o límite de recursos de pago (conflict, limit_reached, service_inactive).
CampoTipoObligatorioDescripción
errorobjectSí
409 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
429 Demasiadas solicitudes (rate_limited); reintenta después de Retry-After.
CampoTipoObligatorioDescripción
errorobjectSí
429 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
500 Error interno (internal).
CampoTipoObligatorioDescripción
errorobjectSí
500 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
503 Indisponibilidad temporal (unavailable); reintenta con espera progresiva.
CampoTipoObligatorioDescripción
errorobjectSí
503 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}

Gestión de errores y reintentos seguros

Objetos anidados

SimulateRequest

CampoTipoObligatorioDescripción
operation_idstringNoCopia opcional de Idempotency-Key en el cuerpo; debe coincidir exactamente con la cabecera. Se recomienda usar solo la cabecera.
minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$
invoice_idstringNoFactura Sandbox de la cuenta y proyecto autorizados por la clave. Indica exactamente invoice_id o watch_id.
minLength: 1
watch_idstringNoDirección Sandbox activa de la cuenta y proyecto/servicio autorizados por la clave. Indica un solo destino.
minLength: 1
transaction_idstringNoOmítelo para un pago de prueba nuevo. Reutiliza el identificador simulated_ devuelto para sus transiciones posteriores. Un identificador desconocido devuelve 404; el activo y el importe no cambian.
pattern: ^simulated_[0-9]+$
event_typestringNoTransición de la transacción de prueba. Confirma o revierte el mismo transaction_id para probar su ciclo de vida.
payment.pending, payment.confirmed, payment.rolled_back; Predeterminado: payment.confirmed
amount_rawstringNoImporte entero positivo en unidades mínimas del activo. Por defecto se usa el importe de la factura, el de la transacción existente o una unidad completa del activo del catálogo para un pago de dirección nuevo. Usa una transacción nueva para otro pago parcial.
minLength: 1; maxLength: 78; pattern: ^[0-9]+$
assetstringNoEl activo de la factura queda fijado. Si una dirección tiene varias reglas de activos, selecciona un activo permitido del catálogo. No se puede deducir la precisión de un token desconocido.
decimalsintegerNoComprobación opcional: debe coincidir con la precisión fijada en la factura o el catálogo. No modifica la precisión.
minimum: 0; maximum: 255
occurred_atstringNoHora opcional del evento, desde 30 días antes hasta 7 días y 1 minuto después del momento actual. No cambia otros objetos ni el reloj del sistema. late fija su propia hora.
date-time
actionstringNoEscenario exclusivo de facturas. expire aplica el vencimiento de esta factura sin evento ni webhook. late vence la factura y simula un pago confirmado un segundo después. invoice_status sigue las reglas normales de aceptación; late no garantiza un estado concreto.
expire, late
Simulation

CampoTipoObligatorioDescripción
event_idstringNoID del evento registrado. Se omite para expire, que no crea un evento.
event_typestringNoTransición de pago registrada; se omite para expire.
watch_idstringSíDirección Sandbox usada por este escenario.
transaction_idstringNoIdentificador estable del pago de prueba para transiciones posteriores; se omite para expire.
invoice_idstringNoFactura Sandbox afectada cuando el escenario se dirige a una factura.
invoice_statusstringNoEstado real de la factura tras la operación; no presupongas un resultado fijo de pago tardío o vencimiento.
actionstringNoEscenario explícito de factura, si se solicita.
expire, late
queuedbooleanSíSe ha encolado el procesamiento de la notificación. Esto no confirma la aceptación de un envío externo.
replayedbooleanSíVerdadero si se devuelve la misma operación idempotente sin otra transición ni evento.
Error

CampoTipoObligatorioDescripción
errorobjectSí