SDK responses and callbacks

Every DEUNA SDK returns immediate UI outcomes through callbacks. The exact success object depends on the opened experience, while errors, close actions, BIN detection, and installment selection use smaller contracts.

Response anatomyAsk Athia about this#

Callback matrixAsk Athia about this#

Web and React Native typesAsk Athia about this#

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;
};

Handle errors by category, while keeping the provider or experience code for support diagnostics:

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});
  },
};

Native error typesAsk Athia about this#

The iOS and Android SDKs normalize payment errors into PaymentsError with type, optional metadata, and an optional order snapshot.

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)
}

callbacks.onError = { error in
    let code = error.metadata?.code ?? "UNKNOWN_ERROR"
    logger.warning("DEUNA SDK error: \(error.type) / \(code)")
    renderRecovery(error.type)
}

Success is experience-specificAsk Athia about this#

The order model evolves independently of SDK callback plumbing. Use the API endpoint reference for the current backend schema instead of copying arbitrary fields from a client payload.

Embedded resize handlingAsk Athia about this#

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,
  },
});

Give the host a stable minimum height while the iframe loads, then let onResize update it. On small screens, avoid a fixed pixel width and allow the host to fill the viewport.

Safe handling checklistAsk Athia about this#

• Keep callback functions idempotent; lifecycle signals can occur near navigation or retries.
• Disable duplicate submission during onPaymentProcessing and while submit() is pending.
• Render human-readable copy from an allow-list. Do not expose raw provider messages by default.
• Log type, safe error code, SDK version, environment, and a merchant correlation ID—not credentials or card data.
• Restore focus when a modal closes and announce errors through an accessible live region.
• Verify the current order state after ambiguous closure, timeout, or network interruption.

Public source contractsAsk Athia about this#

The callback shapes are verified against the current Web callback interfaces, React Native callback interfaces, iOS callback base, and Android shared callbacks. Use the version installed by your application when a repository’s main branch is newer than your pinned release.

Related referencesAsk Athia about this#