sumsub-create-transaction

Name: sumsub-create-transaction
Author: sumsub

github.com/sumsubその他71.2k 回インストール4 週間前に更新

リポジトリ

sumsub-create-transaction について

簡潔な仕様から Sumsub KYT 取引データを作成・送信し、必須項目を検証して応答 ID とリスク結果を報告するスキルです。サンドボックスで取引監視を扱うエージェント向けです。

主な機能

01簡潔な仕様から KytTxnData を生成
02必須項目と列挙値を検証
03既存・新規申請者に応じてルーティング
04Sumsub KYT へ取引を送信
05スコアとダッシュボードリンクを報告

活用シーン

01決済取引を KYT 監視に送信
02トラベルルール取引やプラットフォームイベントを記録
03リスクスコアと審査結果を確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/sumsub/agent-skills --skill sumsub-create-transaction

インストール後、Claude Code で/sumsub-create-transactionを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

examples/

crypto-in.json

fiat-out.json

login-event.json

new-applicant.json

travel-rule.json

references/

transaction-schema.md

scripts/

build_transaction.py

post_transaction.sh

詳細

Sumsub — Create Transaction (KYT)

コンパクトな仕様から KytTxnData JSON ペイロードを作成し、Sumsub KYT エンドポイントに POST して、結果の txnId ／ score ／ reviewAnswer を報告します。

エンドポイント

2 つのバリアントがあり、POST スクリプトが自動的に選択します。

ケース	メソッド + パス
Applicant が存在する	`POST https://api.sumsub.com/resources/applicants/{applicantId}/kyt/txns/-/data`
Applicant が存在しない（Sumsub が `applicant.externalUserId` から作成）	`POST https://api.sumsub.com/resources/applicants/-/kyt/txns/-/data?levelName=<levelName>`

本文：KytTxnData。監視スコアが付与された、永続化済みの KytTxn を返します。

どちらのエンドポイントも非推奨とされていますが、公式ドキュメントにおける、標準の「トランザクションを送信」するエントリーポイントとして引き続き使用されています。v2／v3 の代替手段はありません。

認証 — App Token + secret（sandbox 専用）

このスキルは公開 Sumsub API を利用し、認証リファレンスに従って各リクエストに署名します。仕組みの詳細は sumsub-api-auth スキルに記載されています。401 Invalid signature が発生した場合は、そちらをお読みください。

⚠️ sandbox トークンのみを使用してください。 ここでは本番環境の App Token を受け入れたり、使用したりしないでください。トランザクション監視は実際の Applicant データを扱い、実際の KYT アラートを発生させる可能性があります。ユーザーが本番環境のトークンを提示した場合は、受け取りを断り、https://cockpit.sumsub.com/checkus/home?sbx=true で sandbox 用のペアを生成するよう依頼してください（Connect Sumsub to your AI agent -> Build & configure -> Generate token）。トークンとシークレットは一度だけ表示されます。ダイアログを閉じる前に両方をコピーしてください。ヘルパースクリプトはこの要件を強制し、sbx: で始まらないトークンを拒否します。

変数	例
`SUMSUB_APP_TOKEN`	`sbx:...` — ダッシュボードで発行した sandbox 用 App Token。
`SUMSUB_SECRET_KEY`	トークン作成時に一度だけ表示される、対応するシークレット。
`SUMSUB_BASE`	任意。デフォルトは `https://api.sumsub.com` です。

解決済みパスへの署名

ルーティングには注意点が 1 つあります。クエリ文字列を含むパスに署名する必要があります。POST スクリプトがこれを処理します。ビルダーが出力するサイドカールートファイルを読み取り、URI（/resources/applicants/{id}/… または /resources/applicants/-/…?levelName=…）を選択して、動的なセグメントを URL エンコードし、送信するものと同じバイト列に署名します。スクリプトを介さずに実行する場合は、次の点に注意してください。

実際に送信するパスに署名してください。エンコード済みの形式を使い、クエリ文字列も含めてください。
署名する本文のバイト列は、送信するバイト列と一致させてください（空白の再整形は禁止です）。

ユーザーが会話中にすでに認証情報を提供している場合は、それを再利用してください。それ以外の場合は、実行前に一度だけ確認してください。シークレットを絶対にそのまま表示しないでください。

手順

ユーザーの意図を 以下の簡潔な仕様に対応付けます。取引の大半は type: finance（支払い）です。この場合、ユーザーが伝えているのは実質的に、金額＋通貨＋方向＋申請者＋取引相手です。
検証します。txnId が空でないこと、applicant.externalUserId が空でないこと、さらに type ごとに次を確認します。
- finance / travelRule → info.amount、info.currencyCode、info.direction が必須です（OpenAPI では KytTxnInfo の3項目すべてが必須とされています）。
- userPlatformEvent → userPlatformEvent.type が必須です。
- 列挙値（direction、currencyType、applicant.type、nameType など）は事前に検証し、失敗時には許可されている値をすべて提示します。
${CLAUDE_SKILL_DIR}/scripts/build_transaction.py で完全なペイロードを生成します（標準入力の簡潔な仕様 → 標準出力の完全な KytTxnData ペイロード）。
${CLAUDE_SKILL_DIR}/scripts/post_transaction.sh 経由で POST します。仕様で _applicantId が設定されているかどうかに基づき、既存申請者用 URL と未登録申請者用 URL のどちらに自動的にルーティングします（ペイロード内の値ではありません。詳細は以下を参照）。
ダッシュボードリンクを作成します。 レスポンス本文から id（指定した txnId ではなく、サーバーが割り当てた識別子）と clientId を読み取り、次の形式にします。
```
https://cockpit.sumsub.com/checkus/kyt/txns/<id>?clientId=<clientId>&sbx=true
```

仕様でユーザーが指定した txnId（例：finance-2026-05-21-0001）は URL に使用しません。Sumsub は保存時に別の識別子を割り当てます。sbx=true クエリパラメーターは Sandbox ワークスペースを指定します。これはすべてのスキルで共通して使用される標準的なサンドボックスリンク用パラメーターです。 6. 結果を報告します。txnId（ユーザーが指定した値）、サーバーの id、申請者の externalUserId、方向＋金額＋通貨、取引相手（存在する場合）、レスポンスに含まれていれば score / reviewAnswer / riskLabels、そしてクリック可能な Markdown リンクとしてのダッシュボードリンクを報告します。

簡潔な仕様の形式（標準入力の JSON または YAML）

# Top-level
txnId: "finance-2026-05-21-0001"     # REQUIRED, unique alphanumeric in your system
txnDate: "2026-05-21 14:30:00+0000"  # optional; format: yyyy-MM-dd HH:mm:ss+XXXX
zoneId:  "UTC+01:00"                 # optional, time zone string
type:    finance                     # finance | travelRule | kyc | userPlatformEvent | iGamingSession (default: finance)

# Routing — pick ONE
_applicantId: "67abc..."             # post to existing applicant (path id, NOT a payload field)
# - OR -
_levelName: "Default"                # post to non-existing-applicant URL with ?levelName=...
                                     # (Sumsub creates the applicant from applicant.externalUserId)

# Finance / Travel Rule info (required for those types)
amount:       1500.50
currency:     USD                    # ISO-4217 fiat or crypto ticker (BTC, ETH, …)
currencyType: fiat                   # fiat | crypto  (default: fiat)
direction:    out                    # in | out
amountInDefaultCurrency: 1500.50     # optional, converted to client default
defaultCurrencyCode:     USD
paymentDetails: "Invoice #INV-2026-001"
mcc:    5411                         # optional, 4-digit Merchant Category Code

# Crypto-only block (used when currencyType=crypto)
crypto:
  chain:        ETH                  # ETH | BTC | TRX | … (mandatory for tokens; empty for native)
  contract:     "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
  paymentTxnId: "0x1234abcd..."      # on-chain hash
  fingerprint:  "0x1234abcd..."      # alternative blockchain identifier
  attemptId:    "attempt-01"         # optional, when retrying
  outputIndex:  0                    # for UTXO chains

# Applicant (REQUIRED) — the person/entity acting on your platform
applicant:
  externalUserId: "user-001"         # REQUIRED — your stable user id
  type: individual                   # individual | company (default: individual)
  fullName: "John Smith"             # required for company; recommended for non-existing-applicant flow
  dob: "1990-05-01"
  email: "[email protected]"
  phone: "+1234567890"
  placeOfBirth: "London"
  address:
    country: USA
    town: "New York"
    street: "5th Avenue"
    formatted: "5th Avenue, New York, USA"
  paymentMethod:
    type: bankCard                   # bankCard | bankAccount | crypto | cryptoWallet |
                                     # eWallet | unhostedWallet | card | other
    accountId: "4111********1111"    # IBAN, last4-hash, wallet address, etc.
    issuingCountry: USA
    "3dsUsed": true
    "2faUsed": false
    memo: "optional memo"
  idDoc:
    number: "A12345678"
    country: USA
    idDocType: PASSPORT
  device:
    fingerprint: "abc123"
    userAgent: "Mozilla/5.0 ..."
    ipInfo: { ip: "1.2.3.4" }

# Counterparty (typical for finance + travelRule; same shape as applicant + a few extras)
counterparty:
  externalUserId: "merchant-XYZ"
  type: company
  fullName: "Acme Inc."
  registrationNumber: "12345678"
  leiCode: "529900XXXX0000XXXX00"
  residenceCountry: QAT
  address: { country: QAT }
  institution:                       # → institutionInfo
    code: "ACME-CODE"
    name: "Acme Bank"
    internalId: "<VASP id from directory>"
  ceo:                               # only for company counterparties (Travel Rule)
    firstName: "Jane"
    lastName: "Roe"

# user-platform-event only (when type=userPlatformEvent)
userPlatformEvent:
  type: login                        # login | failedLogin | signup | passwordReset | twoFaReset | general
  twoFaUsed: true
  passwordHash: "..."

# Optional escape hatches
sourceKey: "<segregation key>"
props:                               # custom string-string map
  customField: "value"
  dailyOutLimit: "10000"

列挙値（事前に検証）

フィールド	許可されている値
`type`（トップレベル）	`finance`、`travelRule`、`kyc`、`auditTrailEvent`、`userPlatformEvent`、`scheduledEvent`、`iGamingSession`
`direction`	`in`、`out`
`currencyType`	`crypto`、`fiat`
`applicant.type` / `counterparty.type`	`individual`、`company`
`applicant.nameType`	`aliasName`、`birthName`、`maidenName`、`legalName`、`shortName`、`tradingName`、`other`
`userPlatformEvent.type`	`login`、`failedLogin`、`signup`、`passwordReset`、`twoFaReset`、`general`

paymentMethod.type は意図的に列挙値として検証しません。OpenAPI では KytTxnPaymentMethodType（smartContract、bankCard、bankAccount のみ）とされていますが、ドキュメントや実データでは、より多くの値（crypto、eWallet、unhostedWallet など）が受け入れられています。ビルダーは呼び出し元から渡された値をそのまま転送します。

出力

成功時は次のすべてを報告します。

txnId（ユーザーが指定した値）と id（サーバーが割り当てた値。ダッシュボードリンクで使用）。
申請者の externalUserId。
direction amount currency、取引相手（存在する場合）。
レスポンスに含まれていれば score / reviewAnswer / riskLabels。
ダッシュボードリンク：https://cockpit.sumsub.com/checkus/kyt/txns/<id>?clientId=<clientId>&sbx=true。クリック可能な Markdown リンクとして表示します。<id> はサーバーが割り当てた識別子（送信した txnId ではありません）です。id と clientId はどちらも POST レスポンス本文に含まれます。sbx=true は Sandbox ワークスペースを指定します。

失敗時は、HTTP ステータスと Sumsub の description / errorName を報告します。よくある 4xx エラーは次のとおりです。

409 Entity already exists — txnId が重複しています（新しい ID を使用するか、一括インポート方式で更新してください）。
400 — 必須フィールドがありません（よくあるのは info.amount、info.currencyCode、info.direction、applicant.externalUserId です）。
400 — levelName が不明です（未登録申請者用のフローを使用した場合）。

実例

examples/fiat-out.json — 海外の取引先への EUR カード決済（ドキュメントで標準的な例として使用されています）。
examples/crypto-in.json — cryptoParams.cryptoChain=ETH、コントラクトアドレス、オンチェーンの paymentTxnId を指定した ETH の入金。
examples/travel-rule.json — 取引先に institution.internalId（VASP ID）を指定した、type: travelRule の暗号資産の送金。
examples/login-event.json — 2FA を使用したログイン成功を示す type: userPlatformEvent。
examples/new-applicant.json — 新規申請者のフロー：_levelName を設定することで、POST は /-/kyt/txns/-/data に送信され、?levelName=... が付与されます。

基本情報

作者: sumsub
リポジトリ: sumsub/agent-skills
カテゴリ: その他
インストール数: 1,202
GitHub スター: 7

問題を報告