API-Referenz

Sandbox-Zahlung simulieren

POST/v1/simulate

Vertrag v1 / 1.1.3 5 / 2026-11-17

Auf dieser Seite

Zahlungsszenario mit schreibberechtigtem Testschlüssel und simulation ausführen. Idempotency-Key ist Pflicht; identische Wiederholungen liefern das gespeicherte Ergebnis ohne neuen Übergang oder neue Zustellung. Andere Parameter mit demselben Schlüssel ergeben 409. Daten, Empfänger, Kontingente und Guthaben bleiben von Live getrennt. Keine Blockchain-Transaktion wird erzeugt. expire und late werden unterstützt, Pay und Abonnements nicht.

Schlüsselberechtigungen: simulation / write.

Parameter

ParameterEingehendErforderlichBeschreibung
Idempotency-KeyheaderJa16–80 ASCII-Buchstaben, Ziffern, Binde- oder Unterstriche. Bei Wiederholung denselben Schlüssel und dieselbe Anfrage behalten. Für jeden anderen Übergang einen neuen Schlüssel verwenden.
string minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$

Anfrageinhalt

FeldTypErforderlichBeschreibung
operation_idstringNeinOptionale Kopie von Idempotency-Key im Body; muss dem Header exakt entsprechen. Den Header allein bevorzugen.
minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$
invoice_idstringNeinSandbox-Rechnung des Kontos und des erlaubten Projekts dieses Schlüssels. Genau invoice_id oder watch_id angeben.
minLength: 1
watch_idstringNeinAktive Sandbox-Adresse des Kontos und erlaubten Projekts/Dienstes dieses Schlüssels. Genau ein Ziel angeben.
minLength: 1
transaction_idstringNeinFür eine neue Testzahlung weglassen. Die zurückgegebene simulated_-Kennung für weitere Übergänge dieser Zahlung wiederverwenden. Unbekannte Kennungen ergeben 404; Asset und Betrag sind unveränderlich.
pattern: ^simulated_[0-9]+$
event_typestringNeinÜbergang der Testtransaktion. Dieselbe transaction_id bestätigen oder widerrufen, um den Ablauf zu testen.
payment.pending, payment.confirmed, payment.rolled_back; Standard: payment.confirmed
amount_rawstringNeinPositiver ganzzahliger Betrag in kleinsten Asset-Einheiten. Standard ist der Rechnungsbetrag, bestehende Transaktionsbetrag oder eine ganze Katalog-Einheit bei einer neuen Adresszahlung. Für eine weitere Teilzahlung eine neue Transaktion nutzen.
minLength: 1; maxLength: 78; pattern: ^[0-9]+$
assetstringNeinDas Rechnungs-Asset ist festgelegt. Bei einer Adresse mit mehreren Asset-Regeln wählen Sie ein erlaubtes Katalog-Asset ausdrücklich. Unbekannte Token-Präzision wird nicht geraten.
decimalsintegerNeinOptionale Konsistenzprüfung; muss der festgelegten Rechnungs- oder Katalog-Präzision entsprechen. Überschreibt diese nicht.
minimum: 0; maximum: 255
occurred_atstringNeinOptionale Ereigniszeit zwischen 30 Tagen vor jetzt und 7 Tagen plus 1 Minute danach. Ändert weder andere Objekte noch die Systemzeit. late setzt seine eigene Zeit.
date-time
actionstringNeinNur für Rechnungen. expire wendet den Ablauf dieser Rechnung ohne Ereignis oder Webhook an. late lässt sie ablaufen und simuliert eine bestätigte Zahlung eine Sekunde danach. invoice_status folgt den normalen Annahmeregeln; late garantiert keinen bestimmten Status.
expire, late
application/json
{
  "invoice_id": "2001",
  "event_type": "payment.pending",
  "amount_raw": "1000000"
}

Anfragebeispiele

Beispiele führen eine echte Aktion in Ihrem Konto aus. Die im Code genannten Umgebungsvariablen setzen. Schlüssel geheim halten; Schreibanfragen werden nicht automatisch wiederholt.

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
Beispiel herunterladen
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) }
}
Beispiel herunterladen
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); }
}
Beispiel herunterladen
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);
}
Beispiel herunterladen
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)
Beispiel herunterladen
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;
}
Beispiel herunterladen

Antworten und Fehler

202 Szenario angenommen oder gespeichertes Ergebnis einer identischen Wiederholung.
FeldTypErforderlichBeschreibung
event_idstringNeinID des gespeicherten Ereignisses. Bei expire ohne Ereigniserstellung nicht vorhanden.
event_typestringNeinGespeicherter Zahlungsübergang; bei expire nicht vorhanden.
watch_idstringJaVon diesem Szenario verwendete Sandbox-Adresse.
transaction_idstringNeinStabile Testzahlungs-ID für weitere Übergänge; bei expire nicht vorhanden.
invoice_idstringNeinBetroffene Sandbox-Rechnung bei einem Rechnungsszenario.
invoice_statusstringNeinTatsächlicher Rechnungsstatus nach der Aktion; kein festes Ergebnis für verspätet oder abgelaufen annehmen.
actionstringNeinAusdrückliches Rechnungsszenario, wenn angefordert.
expire, late
queuedbooleanJaDie Ereignisbenachrichtigung wurde zur Verarbeitung eingereiht. Dies bestätigt keine angenommene externe Zustellung.
replayedbooleanJaWahr, wenn dieselbe idempotente Aktion ohne weiteren Übergang oder weiteres Ereignis zurückgegeben wurde.
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 Ungültige Anfrage (bad_request, unsupported_asset).
FeldTypErforderlichBeschreibung
errorobjectJa
400 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
401 Kein gültiger aktiver API-Schlüssel (unauthorized).
FeldTypErforderlichBeschreibung
errorobjectJa
401 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
403 Schlüssel verbietet Aktion, Projekt, Dienst oder IP; E-Mail unbestätigt.
FeldTypErforderlichBeschreibung
errorobjectJa
403 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
404 Objekt im Schlüsselumfang nicht gefunden (not_found).
FeldTypErforderlichBeschreibung
errorobjectJa
404 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
409 Zustandskonflikt, abweichende Wiederholungsparameter oder Zahlungsressourcenlimit (conflict, limit_reached, service_inactive).
FeldTypErforderlichBeschreibung
errorobjectJa
409 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
429 Zu viele Anfragen (rate_limited); nach Retry-After wiederholen.
FeldTypErforderlichBeschreibung
errorobjectJa
429 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
500 Interner Fehler (internal).
FeldTypErforderlichBeschreibung
errorobjectJa
500 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
503 Vorübergehend nicht verfügbar (unavailable); mit Backoff wiederholen.
FeldTypErforderlichBeschreibung
errorobjectJa
503 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}

Fehler behandeln und sicher wiederholen

Verschachtelte Objekte

SimulateRequest

FeldTypErforderlichBeschreibung
operation_idstringNeinOptionale Kopie von Idempotency-Key im Body; muss dem Header exakt entsprechen. Den Header allein bevorzugen.
minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$
invoice_idstringNeinSandbox-Rechnung des Kontos und des erlaubten Projekts dieses Schlüssels. Genau invoice_id oder watch_id angeben.
minLength: 1
watch_idstringNeinAktive Sandbox-Adresse des Kontos und erlaubten Projekts/Dienstes dieses Schlüssels. Genau ein Ziel angeben.
minLength: 1
transaction_idstringNeinFür eine neue Testzahlung weglassen. Die zurückgegebene simulated_-Kennung für weitere Übergänge dieser Zahlung wiederverwenden. Unbekannte Kennungen ergeben 404; Asset und Betrag sind unveränderlich.
pattern: ^simulated_[0-9]+$
event_typestringNeinÜbergang der Testtransaktion. Dieselbe transaction_id bestätigen oder widerrufen, um den Ablauf zu testen.
payment.pending, payment.confirmed, payment.rolled_back; Standard: payment.confirmed
amount_rawstringNeinPositiver ganzzahliger Betrag in kleinsten Asset-Einheiten. Standard ist der Rechnungsbetrag, bestehende Transaktionsbetrag oder eine ganze Katalog-Einheit bei einer neuen Adresszahlung. Für eine weitere Teilzahlung eine neue Transaktion nutzen.
minLength: 1; maxLength: 78; pattern: ^[0-9]+$
assetstringNeinDas Rechnungs-Asset ist festgelegt. Bei einer Adresse mit mehreren Asset-Regeln wählen Sie ein erlaubtes Katalog-Asset ausdrücklich. Unbekannte Token-Präzision wird nicht geraten.
decimalsintegerNeinOptionale Konsistenzprüfung; muss der festgelegten Rechnungs- oder Katalog-Präzision entsprechen. Überschreibt diese nicht.
minimum: 0; maximum: 255
occurred_atstringNeinOptionale Ereigniszeit zwischen 30 Tagen vor jetzt und 7 Tagen plus 1 Minute danach. Ändert weder andere Objekte noch die Systemzeit. late setzt seine eigene Zeit.
date-time
actionstringNeinNur für Rechnungen. expire wendet den Ablauf dieser Rechnung ohne Ereignis oder Webhook an. late lässt sie ablaufen und simuliert eine bestätigte Zahlung eine Sekunde danach. invoice_status folgt den normalen Annahmeregeln; late garantiert keinen bestimmten Status.
expire, late
Simulation

FeldTypErforderlichBeschreibung
event_idstringNeinID des gespeicherten Ereignisses. Bei expire ohne Ereigniserstellung nicht vorhanden.
event_typestringNeinGespeicherter Zahlungsübergang; bei expire nicht vorhanden.
watch_idstringJaVon diesem Szenario verwendete Sandbox-Adresse.
transaction_idstringNeinStabile Testzahlungs-ID für weitere Übergänge; bei expire nicht vorhanden.
invoice_idstringNeinBetroffene Sandbox-Rechnung bei einem Rechnungsszenario.
invoice_statusstringNeinTatsächlicher Rechnungsstatus nach der Aktion; kein festes Ergebnis für verspätet oder abgelaufen annehmen.
actionstringNeinAusdrückliches Rechnungsszenario, wenn angefordert.
expire, late
queuedbooleanJaDie Ereignisbenachrichtigung wurde zur Verarbeitung eingereiht. Dies bestätigt keine angenommene externe Zustellung.
replayedbooleanJaWahr, wenn dieselbe idempotente Aktion ohne weiteren Übergang oder weiteres Ereignis zurückgegeben wurde.
Error

FeldTypErforderlichBeschreibung
errorobjectJa