API 참조

Sandbox 결제 시뮬레이션

POST/v1/simulate

계약 v1 / 1.1.3 5 / 2026-11-17

이 페이지에서

쓰기 가능한 테스트 키와 simulation 권한으로 결제 시나리오를 실행합니다. Idempotency-Key가 필요하며 동일한 재시도는 새 전환이나 전송 없이 저장된 결과를 반환합니다. 같은 키에 다른 매개변수를 사용하면 409를 반환합니다. 데이터, 수신자, 한도와 잔액은 Live와 분리됩니다. 블록체인 거래는 생성하지 않습니다. expire와 late를 지원하며 Pay와 구독은 제외됩니다.

키 권한: simulation / write.

매개변수

매개변수입금필수설명
Idempotency-Keyheader예16–80자의 ASCII 문자, 숫자, 하이픈 또는 밑줄입니다. 재시도 시 같은 키와 정확한 요청을 유지하세요. 서로 다른 전환에는 새 키를 사용하세요.
string minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$

요청 본문

필드유형필수설명
operation_idstring아니요본문에 넣는 선택적 Idempotency-Key 사본으로, 헤더와 정확히 일치해야 합니다. 헤더만 사용하는 것을 권장합니다.
minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$
invoice_idstring아니요키의 계정 및 허용된 프로젝트에 속한 Sandbox 청구서입니다. invoice_id와 watch_id 중 하나만 지정하세요.
minLength: 1
watch_idstring아니요키의 계정 및 허용된 프로젝트/서비스에 속한 활성 Sandbox 주소입니다. 대상 하나만 지정하세요.
minLength: 1
transaction_idstring아니요새 테스트 결제에서는 생략하세요. 반환된 simulated_ 식별자를 같은 결제의 다음 전환에 재사용하세요. 알 수 없는 식별자는 404를 반환하며 자산과 금액은 변경할 수 없습니다.
pattern: ^simulated_[0-9]+$
event_typestring아니요테스트 거래의 전환입니다. 같은 transaction_id를 확정하거나 되돌려 전체 수명 주기를 확인하세요.
payment.pending, payment.confirmed, payment.rolled_back; 기본값: payment.confirmed
amount_rawstring아니요자산의 최소 단위로 표시한 양의 정수 금액입니다. 기본값은 청구서 금액, 기존 거래 금액 또는 새 주소 결제에 대한 카탈로그 자산 한 단위입니다. 별도의 추가 결제는 새 거래를 사용하세요.
minLength: 1; maxLength: 78; pattern: ^[0-9]+$
assetstring아니요청구서 자산은 고정됩니다. 자산 규칙이 여러 개인 주소에서는 허용된 카탈로그 자산을 명시적으로 선택하세요. 알 수 없는 토큰의 정밀도는 추측하지 않습니다.
decimalsinteger아니요선택적 일관성 검사입니다. 청구서 또는 카탈로그의 고정 정밀도와 같아야 하며 정밀도를 덮어쓰지 않습니다.
minimum: 0; maximum: 255
occurred_atstring아니요선택적 이벤트 시각으로 현재 30일 전부터 7일과 1분 후까지 가능합니다. 다른 객체나 시스템 시각을 변경하지 않습니다. late는 자체 시각을 설정합니다.
date-time
actionstring아니요청구서 전용 시나리오입니다. expire는 이벤트나 웹훅 없이 해당 청구서에 만료 처리를 적용합니다. late는 청구서를 만료시키고 만료 일 초 후의 확정 결제를 시뮬레이션합니다. invoice_status는 일반 수락 규칙을 따르며 late는 특정 상태를 보장하지 않습니다.
expire, late
application/json
{
  "invoice_id": "2001",
  "event_type": "payment.pending",
  "amount_raw": "1000000"
}

요청 예시

예제는 귀하의 계정에서 실제 작업을 수행합니다. 코드에 명시된 환경 변수를 설정하세요. 키를 비공개로 유지하세요. 쓰기 요청은 자동 재시도하지 않습니다.

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
예제 다운로드
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) }
}
예제 다운로드
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); }
}
예제 다운로드
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);
}
예제 다운로드
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)
예제 다운로드
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;
}
예제 다운로드

응답 및 오류

202 시나리오가 수락되었거나 동일 재시도의 저장 결과가 반환되었습니다.
필드유형필수설명
event_idstring아니요기록된 이벤트 ID입니다. 이벤트를 생성하지 않는 expire에서는 생략됩니다.
event_typestring아니요기록된 결제 전환입니다. expire에서는 생략됩니다.
watch_idstring예이 시나리오에 사용된 Sandbox 주소입니다.
transaction_idstring아니요이후 전환에도 사용하는 고정 테스트 결제 식별자입니다. expire에서는 생략됩니다.
invoice_idstring아니요청구서 대상 시나리오에서 영향을 받은 Sandbox 청구서입니다.
invoice_statusstring아니요작업 후 실제 청구서 상태입니다. 지연 또는 만료 결과를 미리 단정하지 마세요.
actionstring아니요요청한 경우의 명시적 청구서 시나리오입니다.
expire, late
queuedboolean예이벤트 알림 처리가 대기열에 등록되었습니다. 외부 전송이 수락되었다는 뜻은 아닙니다.
replayedboolean예추가 전환이나 이벤트 없이 동일한 멱등 작업의 결과를 반환했다면 참입니다.
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 잘못된 요청(bad_request, unsupported_asset).
필드유형필수설명
errorobject예
400 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
401 유효한 활성 API 키가 없습니다(unauthorized).
필드유형필수설명
errorobject예
401 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
403 키가 작업, 프로젝트, 서비스 또는 IP를 허용하지 않거나 이메일이 확인되지 않았습니다.
필드유형필수설명
errorobject예
403 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
404 키 범위에서 객체를 찾을 수 없습니다(not_found).
필드유형필수설명
errorobject예
404 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
409 상태 충돌, 재시도 매개변수 충돌 또는 결제 리소스 한도(conflict, limit_reached, service_inactive).
필드유형필수설명
errorobject예
409 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
429 요청이 너무 많습니다(rate_limited). Retry-After 이후 재시도하세요.
필드유형필수설명
errorobject예
429 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
500 내부 오류(internal).
필드유형필수설명
errorobject예
500 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}
503 일시적 사용 불가(unavailable). 점진적 대기로 재시도하세요.
필드유형필수설명
errorobject예
503 application/json
{
  "error": {
    "code": "forbidden",
    "message": "this API key is read-only"
  }
}

오류 처리 및 안전한 재시도

중첩 객체

SimulateRequest

필드유형필수설명
operation_idstring아니요본문에 넣는 선택적 Idempotency-Key 사본으로, 헤더와 정확히 일치해야 합니다. 헤더만 사용하는 것을 권장합니다.
minLength: 16; maxLength: 80; pattern: ^[A-Za-z0-9_-]+$
invoice_idstring아니요키의 계정 및 허용된 프로젝트에 속한 Sandbox 청구서입니다. invoice_id와 watch_id 중 하나만 지정하세요.
minLength: 1
watch_idstring아니요키의 계정 및 허용된 프로젝트/서비스에 속한 활성 Sandbox 주소입니다. 대상 하나만 지정하세요.
minLength: 1
transaction_idstring아니요새 테스트 결제에서는 생략하세요. 반환된 simulated_ 식별자를 같은 결제의 다음 전환에 재사용하세요. 알 수 없는 식별자는 404를 반환하며 자산과 금액은 변경할 수 없습니다.
pattern: ^simulated_[0-9]+$
event_typestring아니요테스트 거래의 전환입니다. 같은 transaction_id를 확정하거나 되돌려 전체 수명 주기를 확인하세요.
payment.pending, payment.confirmed, payment.rolled_back; 기본값: payment.confirmed
amount_rawstring아니요자산의 최소 단위로 표시한 양의 정수 금액입니다. 기본값은 청구서 금액, 기존 거래 금액 또는 새 주소 결제에 대한 카탈로그 자산 한 단위입니다. 별도의 추가 결제는 새 거래를 사용하세요.
minLength: 1; maxLength: 78; pattern: ^[0-9]+$
assetstring아니요청구서 자산은 고정됩니다. 자산 규칙이 여러 개인 주소에서는 허용된 카탈로그 자산을 명시적으로 선택하세요. 알 수 없는 토큰의 정밀도는 추측하지 않습니다.
decimalsinteger아니요선택적 일관성 검사입니다. 청구서 또는 카탈로그의 고정 정밀도와 같아야 하며 정밀도를 덮어쓰지 않습니다.
minimum: 0; maximum: 255
occurred_atstring아니요선택적 이벤트 시각으로 현재 30일 전부터 7일과 1분 후까지 가능합니다. 다른 객체나 시스템 시각을 변경하지 않습니다. late는 자체 시각을 설정합니다.
date-time
actionstring아니요청구서 전용 시나리오입니다. expire는 이벤트나 웹훅 없이 해당 청구서에 만료 처리를 적용합니다. late는 청구서를 만료시키고 만료 일 초 후의 확정 결제를 시뮬레이션합니다. invoice_status는 일반 수락 규칙을 따르며 late는 특정 상태를 보장하지 않습니다.
expire, late
Simulation

필드유형필수설명
event_idstring아니요기록된 이벤트 ID입니다. 이벤트를 생성하지 않는 expire에서는 생략됩니다.
event_typestring아니요기록된 결제 전환입니다. expire에서는 생략됩니다.
watch_idstring예이 시나리오에 사용된 Sandbox 주소입니다.
transaction_idstring아니요이후 전환에도 사용하는 고정 테스트 결제 식별자입니다. expire에서는 생략됩니다.
invoice_idstring아니요청구서 대상 시나리오에서 영향을 받은 Sandbox 청구서입니다.
invoice_statusstring아니요작업 후 실제 청구서 상태입니다. 지연 또는 만료 결과를 미리 단정하지 마세요.
actionstring아니요요청한 경우의 명시적 청구서 시나리오입니다.
expire, late
queuedboolean예이벤트 알림 처리가 대기열에 등록되었습니다. 외부 전송이 수락되었다는 뜻은 아닙니다.
replayedboolean예추가 전환이나 이벤트 없이 동일한 멱등 작업의 결과를 반환했다면 참입니다.
Error

필드유형필수설명
errorobject예