Pular para o conteúdo principal
Nesta página

Cada SDK da DEUNA retorna resultados de interface imediatos através de callbacks. O objeto de sucesso exato depende da experiência aberta, enquanto erros, ações de fechamento, detecção de BIN e seleção de parcelamento usam contratos menores.

Anatomia da resposta#

01 · widget
Emitir um resultado local
A experiência ativa invoca um callback.
02 · app
Atualizar a interface
Mostrar estado de confirmação, recuperação, carregamento ou fechamento.
03 · backend
Reconciliar o pedido
Recuperar o estado atual ou processar um webhook verificado.
04 · business
Atuar uma vez
Concluir, tentar novamente ou escalar a partir do estado autorizado.

Matriz de callbacks#

CallbackCarga útilContrato
onSuccess(data)Resultado da experiênciaPagamento e Próxima Ação geralmente retornam dados do pedido; Elements retorna dados de credenciais. Trate-os como dados do cliente até que sejam reconciliados.
onError(error)Erro de SDK normalizadoLeia type, metadata.code, e metadata.messageErros de pagamento nativos também podem incluir order.
onClosed(action, metadata?)Razão de fechamentoUsado em Web userAction ou systemAction; SDKs nativos expõem sua ação de fechamento. O fechamento não é sucesso ou falha.
onEventDispatch(event, payload)Evento de ciclo de vida brutoApenas para análise e diagnóstico. O payload varia de acordo com a experiência.
onResize({height, width})Dimensões do pixelRedimensione hosts Web ou React Native integrados.
onCardBinDetected(data)Seleção de BINWeb e React Native type {cardBin, cardBrand}; As chamadas de retorno nativas expõem dados em formato JSON.
onInstallmentSelected(data)Seleção de parcelasWeb e React Native type {cardBin, installmentPlanOptionId}; As chamadas de retorno nativas expõem dados em formato JSON.
onPaymentProcessing()Sem dadosBloqueie a submissão duplicada enquanto o pagamento estiver em andamento.

Tipos Web e React Native#

Formatos de retorno públicosJavaScript
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;
};

Gerencie os erros por categoria, mantendo o código do provedor ou da experiência para diagnóstico de suporte:

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

Tipos de erro nativos#

Os SDKs para iOS e Android normalizam os erros de pagamento em PaymentsError com type, opcional metadata, e um opcional order snapshot.

CategoriaAndroidiOSSignificado
ConectividadeNO_INTERNET_CONNECTIONnoInternetConnectionO dispositivo não consegue alcançar o serviço.
SímboloINVALID_ORDER_TOKENinvalidOrderTokenO token está vazio ou inválido para a experiência.
InicializaçãoINITIALIZATION_FAILEDinitializationFailedO widget não pôde ser preparado ou apresentado.
RecuperaçãoORDER_COULD_NOT_BE_RETRIEVED, ORDER_NOT_FOUNDorderCouldNotBeRetrieved, orderNotFoundA busca do pedido falhou. Reconcilie no backend antes de tentar novamente.
PagamentoPAYMENT_ERRORpaymentErrorA experiência de pagamento reportou um erro. Leia os metadados.
Navegação—errorWhileLoadingTheURLO iOS não conseguiu carregar a URL do widget.
Cliente—userErrorO iOS recebeu uma categoria de erro voltada para o cliente.
FallbackUNKNOWN_ERRORunknownErrorMantenha os diagnósticos seguros e mostre um caminho de recuperação genérico.
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)
}

O sucesso é específico da experiência#

ExperiênciaO que onSuccess representaPróximo passo
Widget de pagamentoO widget completou seu fluxo de compra e retorna dados em formato de pedido.Reconcilie o pedido no seu backend antes da entrega.
Próxima AçãoA ação necessária do cliente foi concluída e retorna dados em formato de pedido.Recupere o mesmo pedido; não crie outro.
Elementos / Cofre de PagamentosUm fluxo de credenciais ou carteira foi concluído.Envie apenas as credenciais ou resultados documentados para o seu fluxo de backend.
VoucherA apresentação ou ação suportada do voucher foi concluída.Mostre as instruções, e aguarde o status de pagamento assíncrono.

O modelo de pedido evolui independentemente do fluxo de chamadas de retorno do SDK. Use o endpoint da API de referência para o esquema do backend atual, em vez de copiar campos arbitrários de um payload do cliente.

Gerenciamento de redimensionamento integrado#

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

Garanta que o elemento iframe tenha uma altura mínima estável enquanto carrega, e depois... onResize Atualize-o. Em telas menores, evite uma largura fixa em pixels e permita que o host preencha toda a área da tela.

Verificação de segurança#

  • As funções de callback devem ser idempotentes; os sinais de ciclo de vida podem ocorrer durante a navegação ou em tentativas.
  • Desativar a submissão duplicada durante onPaymentProcessing e enquanto submit() está pendente.
  • Exibir cópias legíveis por humanos a partir de uma lista de permissão. Não expor mensagens brutas do provedor por padrão.
  • Log type, código de erro seguro, versão do SDK, ambiente e ID de correlação do comerciante – não credenciais ou dados de cartão.
  • Restaurar o foco quando um modal é fechado e anunciar erros por meio de uma área de notificação acessível.
  • Verifique o estado atual do pedido após o encerramento ambíguo, tempo limite ou interrupção de rede.

Contratos de código aberto#

As estruturas de retorno são verificadas em relação ao estado atual. Interfaces de retorno web, Interfaces de callback React Native, Base de callback para iOS, e Callbacks compartilhados para Android. Utilize a versão instalada pela sua aplicação quando um repositório… main A versão da ramificação é mais recente que a versão que você definiu como principal.