Référence de l’API

Simuler un paiement Sandbox

POST/v1/simulate

Contrat v1 / 1.1.3 5 / 2026-11-17

Sur cette page

Exécute un scénario avec une clé de test en écriture et le droit simulation. Idempotency-Key est requis ; une répétition identique renvoie le résultat enregistré sans nouvelle transition ni livraison. Une clé réutilisée avec des paramètres différents renvoie 409. Données, destinataires, quotas et soldes sont séparés de Live. Aucune transaction blockchain n’est créée. expire et late sont disponibles ; Pay et les abonnements sont exclus.

Permissions de la clé : simulation / write.

Paramètres

ParamètreEntrantObligatoireDescription
Idempotency-KeyheaderOui16–80 lettres ASCII, chiffres, tirets ou soulignements. Conservez la même clé et la requête exacte lors d’une répétition. Chaque transition distincte utilise une nouvelle clé.
string minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$

Corps de la requête

ChampTypeObligatoireDescription
operation_idstringNonCopie facultative de Idempotency-Key dans le corps ; elle doit correspondre exactement à l’en-tête. Préférez l’en-tête seul.
minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$
invoice_idstringNonFacture Sandbox du compte et du projet autorisés par la clé. Fournissez exactement invoice_id ou watch_id.
minLength: 1
watch_idstringNonAdresse Sandbox active du compte et du projet/service autorisés par la clé. Fournissez une seule cible.
minLength: 1
transaction_idstringNonOmettez ce champ pour un nouveau paiement de test. Réutilisez l’identifiant simulated_ retourné pour ses transitions suivantes. Un identifiant inconnu renvoie 404 ; actif et montant sont immuables.
pattern: ^simulated_[0-9]+$
event_typestringNonTransition de la transaction de test. Confirmez ou annulez le même transaction_id pour tester son cycle de vie.
payment.pending, payment.confirmed, payment.rolled_back; Défaut: payment.confirmed
amount_rawstringNonMontant entier positif dans les plus petites unités de l’actif. Par défaut : montant de la facture, de la transaction existante ou une unité entière de l’actif du catalogue pour un nouveau paiement d’adresse. Utilisez une nouvelle transaction pour un versement partiel distinct.
minLength: 1; maxLength: 78; pattern: ^[0-9]+$
assetstringNonL’actif d’une facture est figé. Pour une adresse avec plusieurs règles d’actifs, choisissez explicitement un actif autorisé du catalogue. La précision d’un jeton inconnu ne peut pas être devinée.
decimalsintegerNonVérification facultative : doit correspondre à la précision figée de la facture ou du catalogue. Ne modifie pas la précision.
minimum: 0; maximum: 255
occurred_atstringNonDate facultative de l’événement, de 30 jours avant maintenant à 7 jours et 1 minute après. Ne modifie pas les autres objets ni l’heure système. late fixe sa propre date.
date-time
actionstringNonScénario réservé aux factures. expire applique l’expiration de cette facture sans événement ni webhook. late fait expirer la facture et simule un paiement confirmé une seconde après l’expiration. invoice_status suit les règles normales d’acceptation ; late ne garantit pas un état précis.
expire, late
application/json
{
  "invoice_id": "2001",
  "event_type": "payment.pending",
  "amount_raw": "1000000"
}

Exemples de requêtes

Les exemples réalisent une opération réelle dans votre compte. Définissez les variables d’environnement nommées dans le code. Gardez votre clé privée ; les requêtes d’écriture ne sont pas réessayées automatiquement.

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
Télécharger l’exemple
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) }
}
Télécharger l’exemple
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); }
}
Télécharger l’exemple
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);
}
Télécharger l’exemple
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)
Télécharger l’exemple
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;
}
Télécharger l’exemple

Réponses et erreurs

202 Scénario accepté, ou résultat enregistré d’une répétition identique.
ChampTypeObligatoireDescription
event_idstringNonIdentifiant de l’événement enregistré. Absent pour expire, qui ne crée pas d’événement.
event_typestringNonTransition de paiement enregistrée ; absente pour expire.
watch_idstringOuiAdresse Sandbox utilisée par ce scénario.
transaction_idstringNonIdentifiant stable du paiement de test pour ses transitions suivantes ; absent pour expire.
invoice_idstringNonFacture Sandbox concernée si le scénario cible une facture.
invoice_statusstringNonÉtat réel de la facture après l’opération ; ne supposez jamais un résultat tardif ou expiré fixe.
actionstringNonScénario explicite de facture, si demandé.
expire, late
queuedbooleanOuiLe traitement des notifications a été mis en file. Cela ne prouve pas l’acceptation d’un envoi externe.
replayedbooleanOuiVrai si la même opération idempotente a été renvoyée sans nouvelle transition ni événement.
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 Requête invalide (bad_request, unsupported_asset).
ChampTypeObligatoireDescription
errorobjectOui
400 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
401 Aucune clé API active valide (unauthorized).
ChampTypeObligatoireDescription
errorobjectOui
401 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
403 La clé n’autorise pas l’opération, le projet, le service ou l’IP ; e-mail non confirmé.
ChampTypeObligatoireDescription
errorobjectOui
403 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
404 Objet introuvable dans le périmètre de la clé (not_found).
ChampTypeObligatoireDescription
errorobjectOui
404 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
409 Conflit d’état, paramètres de nouvelle tentative contradictoires ou limite de ressources de paiement (conflict, limit_reached, service_inactive).
ChampTypeObligatoireDescription
errorobjectOui
409 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
429 Trop de requêtes (rate_limited) ; réessayez après Retry-After.
ChampTypeObligatoireDescription
errorobjectOui
429 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
500 Erreur interne (internal).
ChampTypeObligatoireDescription
errorobjectOui
500 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
503 Indisponibilité temporaire (unavailable) ; réessayez avec un délai progressif.
ChampTypeObligatoireDescription
errorobjectOui
503 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}

Gestion des erreurs et nouvelles tentatives sûres

Objets imbriqués

SimulateRequest

ChampTypeObligatoireDescription
operation_idstringNonCopie facultative de Idempotency-Key dans le corps ; elle doit correspondre exactement à l’en-tête. Préférez l’en-tête seul.
minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$
invoice_idstringNonFacture Sandbox du compte et du projet autorisés par la clé. Fournissez exactement invoice_id ou watch_id.
minLength: 1
watch_idstringNonAdresse Sandbox active du compte et du projet/service autorisés par la clé. Fournissez une seule cible.
minLength: 1
transaction_idstringNonOmettez ce champ pour un nouveau paiement de test. Réutilisez l’identifiant simulated_ retourné pour ses transitions suivantes. Un identifiant inconnu renvoie 404 ; actif et montant sont immuables.
pattern: ^simulated_[0-9]+$
event_typestringNonTransition de la transaction de test. Confirmez ou annulez le même transaction_id pour tester son cycle de vie.
payment.pending, payment.confirmed, payment.rolled_back; Défaut: payment.confirmed
amount_rawstringNonMontant entier positif dans les plus petites unités de l’actif. Par défaut : montant de la facture, de la transaction existante ou une unité entière de l’actif du catalogue pour un nouveau paiement d’adresse. Utilisez une nouvelle transaction pour un versement partiel distinct.
minLength: 1; maxLength: 78; pattern: ^[0-9]+$
assetstringNonL’actif d’une facture est figé. Pour une adresse avec plusieurs règles d’actifs, choisissez explicitement un actif autorisé du catalogue. La précision d’un jeton inconnu ne peut pas être devinée.
decimalsintegerNonVérification facultative : doit correspondre à la précision figée de la facture ou du catalogue. Ne modifie pas la précision.
minimum: 0; maximum: 255
occurred_atstringNonDate facultative de l’événement, de 30 jours avant maintenant à 7 jours et 1 minute après. Ne modifie pas les autres objets ni l’heure système. late fixe sa propre date.
date-time
actionstringNonScénario réservé aux factures. expire applique l’expiration de cette facture sans événement ni webhook. late fait expirer la facture et simule un paiement confirmé une seconde après l’expiration. invoice_status suit les règles normales d’acceptation ; late ne garantit pas un état précis.
expire, late
Simulation

ChampTypeObligatoireDescription
event_idstringNonIdentifiant de l’événement enregistré. Absent pour expire, qui ne crée pas d’événement.
event_typestringNonTransition de paiement enregistrée ; absente pour expire.
watch_idstringOuiAdresse Sandbox utilisée par ce scénario.
transaction_idstringNonIdentifiant stable du paiement de test pour ses transitions suivantes ; absent pour expire.
invoice_idstringNonFacture Sandbox concernée si le scénario cible une facture.
invoice_statusstringNonÉtat réel de la facture après l’opération ; ne supposez jamais un résultat tardif ou expiré fixe.
actionstringNonScénario explicite de facture, si demandé.
expire, late
queuedbooleanOuiLe traitement des notifications a été mis en file. Cela ne prouve pas l’acceptation d’un envoi externe.
replayedbooleanOuiVrai si la même opération idempotente a été renvoyée sans nouvelle transition ni événement.
Error

ChampTypeObligatoireDescription
errorobjectOui