Deuna (Banco Pichincha) tramite widget di pagamento

PrerequisitiChiedi ad Athia informazioni#

Prima dell'implementazione Deuna (Banco Pichincha) pagamenti, assicurati di avere:

• Abilitato Deuna (Banco Pichincha) nel pannello di amministrazione di DEUNA
• Generato un gettone dell'ordine tramite l'API DEUNA
• Integrato il DEUNA SDK nel tuo progetto
• Revisionato il Documentazione del widget di pagamento per la tua piattaforma
• Seleziona il tuo preferito modalità di pagamento (Codice numerico o QR) nel pannello di amministrazione

Configurazione del widget di pagamentoChiedi ad Athia informazioni#

Implementazione di base

Inizializza il widget di pagamento con il file deuna_wallet processore:

DeunaSDK.initPaymentWidget({
  orderToken: '',
  paymentMethods: [
    {
      paymentMethod: 'voucher',
      processors: ['deuna_wallet'],
    },
  ],
  callbacks: {
    onSuccess: (data) => {
      console.log('Payment successful:', data);
      // Redirect to success page
    },
    onError: (error) => {
      console.log('Payment failed:', error);
      // Show error message to user
    },
    onPending: (data) => {
      console.log('Payment pending confirmation:', data);
      // Show waiting screen
    },
  },
});

Esempio completo con tutte le opzioni

DeunaSDK.initPaymentWidget({
  orderToken: '',
  paymentMethods: [
    {
      paymentMethod: 'voucher',
      processors: ['deuna_wallet'],
      metadata: {
        // Optional: Pass additional data
        orderId: 'your-internal-order-id',
      },
    },
  ],
  callbacks: {
    onSuccess: (response) => {
      console.log('Payment confirmed:', {
        orderId: response.order_id,
        orderToken: response.order_token,
        status: response.status,
        amount: response.amount,
        currency: response.currency,
      });
      
      // Verify payment on your backend
      fetch('/api/verify-payment', {
        method: 'POST',
        body: JSON.stringify({
          orderToken: response.order_token,
          orderId: response.order_id,
        }),
      })
      .then(res => res.json())
      .then(data => {
        if (data.verified) {
          window.location.href = '/order-confirmation';
        }
      });
    },
    
    onError: (error) => {
      console.error('Payment error:', {
        code: error.code,
        message: error.message,
      });
      
      // Show user-friendly error message
      showErrorModal({
        title: 'Payment Failed',
        message: 'Unable to process your payment. Please try again.',
      });
    },
    
    onPending: (response) => {
      console.log('Payment pending user confirmation:', {
        orderId: response.order_id,
        expiresAt: response.expires_at,
      });
    },
    
    onExpired: (response) => {
      console.log('Payment code/QR expired:', {
        orderId: response.order_id,
        expiredAt: response.expired_at,
      });
    },
  },
});

Modalità di pagamentoChiedi ad Athia informazioni#

Comprendere le due modalità

Il tuo account commerciante è configurato con una di queste modalità nel pannello di amministrazione:

Modalità 1: codice numerico (finestra di 3 minuti)

Cosa vede il cliente:

• Un codice numerico di 6 cifre visualizzato sullo schermo
• Conto alla rovescia che mostra il tempo rimanente (0:00-3:00)
• Istruzioni per aprire l'app Deuna e inserire il codice

Flusso di clienti:

1. Prende nota del codice a 6 cifre
2. Apre l'app Deuna
3. Seleziona "Paga con codice"
4. Inserisce il codice a 6 cifre
5. Conferma il pagamento nell'app
6. DEUNA elabora lo stato del pagamento finale in modo asincrono

Configurazione: Impostalo nel Pannello di amministrazione sotto le impostazioni del processore Deuna (Banco Pichincha).

Modalità 2: codice QR (finestra di 15 minuti)

Cosa vede il cliente:

• Un codice QR dinamico sullo schermo
• Conto alla rovescia che mostra il tempo rimanente (0:00-15:00)
• Due opzioni per procedere:
  • Scansiona QR con la fotocamera dell'app Deuna
  • Fare clic su QR per aprire direttamente l'app

Flusso di clienti:

1. Opzione A - Scansione:

   • Apre la fotocamera dell'app Deuna
   • Esegue la scansione del codice QR
   • La pagina di pagamento si apre automaticamente
   • Conferma il pagamento nell'app
   • DEUNA elabora lo stato del pagamento finale in modo asincrono

2. Opzione B: fare clic su:

   • Fare clic sul codice QR o sul pulsante
   • Apre direttamente l'app Deuna
   • Mostra la schermata di conferma del pagamento
   • Conferma il pagamento
   • DEUNA elabora lo stato del pagamento finale in modo asincrono

Configurazione: Impostalo nel Pannello di amministrazione sotto le impostazioni del processore Deuna (Banco Pichincha).

Nota: La selezione della modalità avviene una volta durante la configurazione iniziale nel pannello di amministrazione. Tutti gli ordini successivi utilizzeranno la modalità configurata. Contattare il supporto DEUNA per cambiare modalità.

Gestione della conferma del pagamentoChiedi ad Athia informazioni#

Deuna (Banco Pichincha) non definisce un payload webhook commerciante separato. Segue lo standard modello di elaborazione asincrona dello stato dei pagamenti.

Utilizza il widget callback per aggiornare l'interfaccia cliente, quindi recuperare l'ordine originale e prendere decisioni di evasione dallo stato di pagamento finale. Se il risultato rimane irrisolto, interroga l'endpoint dell'ordine con una cadenza limitata:

const pollOrderStatus = async (orderToken) => {
  const maxAttempts = 60; // 3 minutes for numeric code
  let attempts = 0;
  
  while (attempts < maxAttempts) {
    try {
      const response = await fetch(`/api/order/${orderToken}`);
      const order = await response.json();
      
      if (order.status === 'confirmed') {
        handlePaymentSuccess(order);
        return;
      }
      
      if (order.status === 'expired') {
        handlePaymentExpired(order);
        return;
      }
      
      // Wait 3 seconds before polling again
      await new Promise(resolve => setTimeout(resolve, 3000));
      attempts++;
      
    } catch (error) {
      console.error('Polling error:', error);
    }
  }
  
  handlePaymentExpired();
};

Oggetti di rispostaChiedi ad Athia informazioni#

Risposta di successo

Una volta confermato il pagamento, onSuccess la richiamata riceve:

{
  order_id: "order_abc123def456",
  order_token: "token_xyz789",
  status: "confirmed",
  payment_method: "deuna_wallet",
  amount: 99.99,
  currency: "USD",
  timestamp: "2024-03-20T14:30:45Z",
  metadata: {
    // Any metadata passed during initialization
  }
}

Risposta all'errore

Quando il pagamento fallisce, onError la richiamata riceve:

{
  code: "PAYMENT_FAILED",
  message: "Unable to process payment",
  order_id: "order_abc123def456",
  details: {
    reason: "Insufficient funds in Deuna wallet"
  }
}

In attesa di risposta

Durante l'attesa della conferma dell'utente, onPending la richiamata riceve:

{
  order_id: "order_abc123def456",
  order_token: "token_xyz789",
  status: "pending",
  payment_method: "deuna_wallet",
  code_or_qr: "123456", // For numeric code mode
  expires_at: "2024-03-20T14:33:45Z",
  expires_in_seconds: 180
}

Risposta scaduta

Quando il codice/QR scade, onExpired la richiamata riceve:

{
  order_id: "order_abc123def456",
  order_token: "token_xyz789",
  status: "expired",
  payment_method: "deuna_wallet",
  expired_at: "2024-03-20T14:33:45Z",
  message: "Code has expired"
}

Best practice per l'interfaccia utenteChiedi ad Athia informazioni#

Per la modalità codice numerico

• Mostra il codice in modo ben visibile - Carattere grande e chiaro
• Mostra il conto alla rovescia - Aggiorna ogni secondo
• Visualizza istruzioni chiare:
  • "Apri l'app Deuna"
  • "Seleziona Paga con codice"
  • "Inserisci questo codice di 6 cifre"
  • "Conferma pagamento"
• Mostra lo stato di scadenza - Quando il codice scade dopo 3 minuti
• Fornire l'opzione di rigenerazione - Pulsante "Genera nuovo codice".

Per la modalità codice QR

• Visualizza il codice QR in modo ben visibile - Centrato, scalabile
• Mostra il conto alla rovescia - Aggiorna ogni secondo
• Fornire due opzioni di interazione:
  • Scansiona QR con l'app Deuna
  • Fare clic su QR per aprire direttamente l'app
• Visualizza istruzioni chiare
• Mostra lo stato di scadenza - Quando il QR scade dopo 15 minuti
• Fornire l'opzione di rigenerazione - Pulsante "Genera nuovo codice".

Linee guida generali

• Mantieni la modalità/schermata aperta - Non reindirizzare o chiudere fino alla conferma o alla scadenza del pagamento
• Disabilita altri metodi di pagamento - Impedire la selezione di un altro metodo durante l'attesa
• Mobile reattivo - Garantire la leggibilità su schermi di piccole dimensioni
• Accessibilità - Includi testo alternativo per QR, contrasto cromatico chiaro per i timer
• Stati di caricamento - Mostra lo spinner durante la generazione del codice/QR

Modelli di implementazione comuniChiedi ad Athia informazioni#

Modello di aggancio di reazione

import { useEffect, useState } from 'react';

export const useDeunaWalletPayment = (orderToken) => {
  const [status, setStatus] = useState('idle'); // idle | pending | success | error | expired
  const [expiresAt, setExpiresAt] = useState(null);

  useEffect(() => {
    if (!orderToken) return;

    DeunaSDK.initPaymentWidget({
      orderToken,
      paymentMethods: [
        {
          paymentMethod: 'voucher',
          processors: ['deuna_wallet'],
        },
      ],
      callbacks: {
        onPending: (data) => {
          setStatus('pending');
          setExpiresAt(data.expires_at);
        },
        onSuccess: (data) => {
          setStatus('success');
        },
        onError: (error) => {
          setStatus('error');
        },
        onExpired: () => {
          setStatus('expired');
        },
      },
    });
  }, [orderToken]);

  const regenerate = () => {
    setStatus('idle');
    window.location.reload();
  };

  return { status, expiresAt, regenerate };
};