メインコンテンツへスキップ
すべてのシステムが正常に動作しています変更履歴v1
ログイン
SDKs

SDK の応答とコールバック

成功、エラー、クローズ、リサイズ、BIN、分割払い、および処理コールバックを、DEUNA SDK 全体で一貫して処理してください。

最終更新日 October 16, 2026
このページで

すべての DEUNA SDK は、コールバックを通じて即座の UI 結果を返します。 成功オブジェクトの正確な内容は、開かれたエクスペリエンスによって異なりますが、エラー、クローズアクション、BIN の検出、および分割払い選択には、より小さな契約を使用します。

応答の構造#

01 · widget
ローカルな結果を送信
アクティブなエクスペリエンスはコールバックを呼び出します。
02 · app
インターフェースを更新
確認、復元、ロード、またはクローズの状態を表示します。
03 · backend
注文を調整
現在の状態を取得するか、検証された Webhook を処理します。
04 · business
一度実行
処理、再試行、または権限のある状態からエスカレーション。

コールバックマトリックス#

コールバックリクエストペイロード契約条件
onSuccess(data)結果を確認「Payment and Next Action」は通常、注文データを返し、「Elements」は認証情報を返します。 認証後まで、クライアントデータとして扱ってください。
onError(error)正規化されたSDKエラー読み取り type, metadata.code, および metadata.messageネイティブな決済エラーには、 order.
onClosed(action, metadata?)終了理由も含まれることがありますウェブでの利用 userAction または systemAction; ネイティブ SDK は、タイピングされたクローズのアクションを公開します。 クローズは成功または失敗ではありません。
onEventDispatch(event, payload)生のライフサイクルイベント分析と診断のみ。ペイロードは、体験によって異なります。
onResize({height, width})ピクセル寸法埋め込まれたウェブまたはReact Nativeホストのサイズ変更
onCardBinDetected(data)BINの選択ウェブおよびReact Nativeタイプ {cardBin, cardBrand}ネイティブなコールバックはJSONを公開します。
onInstallmentSelected(data)分割払い選択ウェブおよびReact Nativeタイプ {cardBin, installmentPlanOptionId}ネイティブなコールバックはJSONを公開します。
onPaymentProcessing()ペイロードなし支払い処理中、重複送信をロックします。

WebおよびReact Nativeタイプ#

公開コールバックの形状JavaScript
type ClosedAction = 'userAction' | 'systemAction';

type SdkError = {
  type: string;
  metadata: {
    code: string;
    message: string;
  };
};

type CardBinDetected = {
  cardBin: string;
  cardBrand: string;
};

type InstallmentSelected = {
  cardBin: string;
  installmentPlanOptionId: string;
};

type Dimensions = {
  height: number;
  width: number;
};

エラーをカテゴリ別に処理し、同時にプロバイダーまたはエクスペリエンス側のコードをサポート診断に使用します。

JavaScript
const callbacks = {
  onSuccess: async (data) => {
    setCheckoutState('verifying');
    const verifiedOrder = await fetch(`/api/orders/${merchantOrderId}`).then(r => r.json());
    renderFromAuthoritativeState(verifiedOrder);
  },
  onError: ({type, metadata}) => {
    logSafeDiagnostic({type, code: metadata.code});
    showRecoveryMessage(type, metadata.code);
  },
  onClosed: (action, metadata) => {
    restorePaymentMethods();
    if (metadata) logSafeDiagnostic({action, code: metadata.code});
  },
};

ネイティブなエラータイプ#

iOSおよびAndroid SDKは、支払いエラーを以下のように正規化します。 PaymentsError ～ type（オプション） metadata（オプション） order snapshot.

カテゴリAndroidiOS意味
接続性NO_INTERNET_CONNECTIONnoInternetConnectionデバイスがサービスに到達できません。
トークンINVALID_ORDER_TOKENinvalidOrderTokenトークンが空またはエクスペリエンスに対して無効です。
初期化INITIALIZATION_FAILEDinitializationFailedウィジェットの準備または表示に失敗しました。
取得ORDER_COULD_NOT_BE_RETRIEVED, ORDER_NOT_FOUNDorderCouldNotBeRetrieved, orderNotFound注文の検索に失敗しました。再試行する前にバックエンドで再調整してください。
決済PAYMENT_ERRORpaymentError支払いエクスペリエンスでエラーが発生しました。メタデータを読み取ります。
ナビゲーション—errorWhileLoadingTheURLiOSでウィジェットのURLを読み込めませんでした。
Cliente—userErroriOSで顧客向けのエラーカテゴリを受信しました。
フォールバックUNKNOWN_ERRORunknownError安全な診断を保持し、一般的な復旧パスを表示します。
AndroidKotlin
callbacks.onError = { error ->
    val code = error.metadata?.code ?: "UNKNOWN_ERROR"
    logger.warn("DEUNA SDK error", mapOf("type" to error.type.name, "code" to code))
    renderRecovery(error.type)
}
iOSSwift
callbacks.onError = { error in
    let code = error.metadata?.code ?? "UNKNOWN_ERROR"
    logger.warning("DEUNA SDK error: \(error.type) / \(code)")
    renderRecovery(error.type)
}

成功はエクスペリエンス固有#

体験何 onSuccess を表す次のステップ
支払いウィジェットウィジェットが購入プロセスを完了し、注文形式のデータを返します。注文をバックエンドで再調整してから履行してください。
次のアクション必要な顧客アクションが完了し、注文形式のデータを返します。同じ注文を再取得し、別のものを作成しないでください。
要素/支払いVaultクレデンシャルまたはウォレットフローが完了しました。必要なクレデンシャルまたは結果のみをバックエンドフローに送信します。
バウチャークーポン表示またはそのサポートされているアクションが完了しました。指示を表示し、その後、信頼できる非同期の支払いステータスを待ちます。

注文モデルはSDKコールバックの仕組みとは独立して進化します。現在のバックエンドのスキーマを使用するために、 APIエンドポイントを参照してください。 クライアントのペイロードから、任意にフィールドをコピーするのではなく。

埋め込みサイズの調整#

JavaScript
const host = document.querySelector('#deuna-widget');

await DeunaSDK.initPaymentWidget({
  orderToken,
  mode: 'target',
  target: '#deuna-widget',
  callbacks: {
    onResize: ({height}) => {
      host.style.height = `${Math.ceil(height)}px`;
    },
    onSuccess: verifyOrder,
    onError: showRecovery,
  },
});

iframeのロード中に、ホストに安定した最小の高さを与え、その後、 onResize 更新します。小さな画面では、固定されたピクセル幅を避け、ホストがビューポート全体を埋めるようにします。

安全な取り扱いチェックリスト#

  • コールバック関数をイデムポテンツに保ちます。ライフサイクル信号は、ナビゲーションまたは再試行中に発生する可能性があります。
  • 重複送信を onPaymentProcessing および submit() が処理中の間に無効にします。
  • 許可リストから人間が読み取り可能なコピーを表示します。デフォルトでは、生のプロバイダーメッセージを公開しないでください。
  • ログ type、安全なエラーコード、SDKバージョン、環境、および商人の関連ID—クレデンシャルまたはカードデータではありません。
  • モダルの閉じ時にフォーカスを復元し、アクセス可能なライブ領域を通じてエラーを通知します。
  • 曖昧なクローズ、タイムアウト、またはネットワーク中断後に現在の注文の状態を確認します。

公開ソース契約#

コールバックの形状は、現在の Webコールバックインターフェース, React Nativeコールバックインターフェース, iOSコールバックベース, および Android共有コールバック。アプリケーションでインストールされているバージョンを使用し、リポジトリの main ブランチが、ピン留設定されたリリースよりも新しい場合は、

SDK イベントライフサイクルの名前と分析に関するガイダンス。次のアクション3DSとリダイレクトフローを継続。エラーバックエンドとプラットフォームのエラー分類。