API diretta
Costruire un'esperienza di pagamento di proprietà dei commercianti con le API del server DEUNA.
In questa pagina
- Seguire la procedura di integrazione
- 1. Configurare il commerciante e l'ambiente
- 2. Raccogliere i dati di pagamento in modo sicuro
- 3. Creare e gestire il pagamento
- 4. Gestire la risposta e l'azione del cliente
- 5. Confermare i risultati asincroni
- 6. Implementare operazioni post-pagamento
- Controllo di prontezza per l'ambiente di produzione
Controlla l’interfaccia e coordina i pagamenti dal tuo backend.
Crea il percorso cliente nella tua applicazione e usa le API DEUNA per operazioni di pagamento, utenti, carte e orchestrazione.
- Interfaccia
- Frontend e backend gestiti dal merchant
- Modello di distribuzione
- API server-to-server con supporto client dove necessario
- Ideale per
- Team che richiedono il massimo controllo del prodotto
Utilizza l'API diretta quando il tuo team gestisce l'interfaccia di checkout e interagisce con DEUNA tramite un backend di un partner fidato. Il tuo cliente raccoglie o tokenizza lo strumento di pagamento, il tuo backend crea il pagamento, e entrambi i livelli gestiscono qualsiasi azione del cliente necessaria prima dello stato finale del pagamento.
Seguire la procedura di integrazione#
1. Configurare il commerciante e l'ambiente#
Prima di inviare la richiesta di pagamento:
- Completare Impostazione account e ottenere le credenziali per l'ambiente di test.
- Leggi Autenticazione e chiavi API per separare le credenziali del cliente, le credenziali del backend e, facoltativamente, l'identità del cliente.
- Configurare almeno una connessione di pagamento e una strategia di routing idonee. Utilizzare Funzionalità dei provider per verificare il supporto per paese, metodo, valuta e operazione, quindi rivedere Strategie di pagamento.
- Applicare i requisiti dell'ambiente e della rete condivisi in Elementi essenziali per l’integrazione API.
- Utilizzare le API supportate Raccolta Postman quando si desidera ispezionare le richieste di test prima di implementare un client.
Ambienti di test e di produzione utilizzano URL di base, credenziali, connessioni al provider e dati di pagamento diversi. Non mescolare le risorse tra gli ambienti.
2. Raccogliere i dati di pagamento in modo sicuro#
Il commerciante possiede l'interfaccia API diretta, ma la gestione dei dati della carta dipende comunque dal suo ambito PCI.
- Se il client deve evitare di gestire i dati della carta grezzi sul backend del commerciante, utilizzare le API supportate Flusso di tokenizzazione della carta e inviare il token del metodo di pagamento risultante al backend.
- Se il fornitore di servizi antifrode configurato richiede dati del browser o del dispositivo, implementare Flusso API diretto per l'identificazione del dispositivo.
- Per portafogli e metodi di pagamento alternativi, iniziare con Funzionalità dei provider, quindi seguire la guida di connessione collegata per i requisiti necessari.
payment_source,specific_fields, reindirizzamento, codice QR, buono regalo, o comportamento di callback. - Se è disponibile un token di ordine esistente, il backend può recuperare la sua configurazione. Metodi di pagamento Prima dell'elaborazione.
3. Creare e gestire il pagamento#
Le nuove integrazioni dovrebbero iniziare con POST /v2/merchants/orders/purchase. Supporta due modelli di richiesta validi:
| Modello | Quando usarlo | Documentazione |
|---|---|---|
| Ordine inline · Consigliato | Creare l'ordine e gestire il pagamento tramite una singola richiesta Purchase V2. | Contratto per la richiesta di pagamento e Esempi completi di implementazione |
| Token di ordine esistente · Facoltativo | Creare l'ordine solo quando un altro canale o esperienza ne ha bisogno order_token prima di effettuare il pagamento. | Creare ordine, quindi Elaborare l'ordine esistente |
Usa il Esempio di test per pagamenti per il flusso backend più breve e funzionale. catalogo degli endpoint è la fonte ufficiale delle operazioni pubblicate e dei chiamanti supportati.
Per ogni richiesta di modifica del pagamento supportata, generare un identificativo stabile. X-Idempotency-Key nel backend. Utilizzare la stessa chiave e lo stesso corpo identico byte per byte quando si tenta nuovamente un tentativo incerto. Seguire la procedura completa. Linee guida per richieste idempotenti, comprese la sua durata di conservazione e le modalità di gestione dei conflitti.
4. Gestire la risposta e l'azione del cliente#
Un HTTP 2xx La risposta indica che la richiesta API è stata accettata o elaborata; non prova di per sé che siano stati effettuati pagamenti. order.payment.data.status e qualsiasi azione successiva restituita.
Seleziona il ciclo di vita appropriato per il metodo scelto:
Non utilizzare l'URL di ritorno del browser, la callback dell'SDK o il reindirizzamento del fornitore come prova di pagamento. Mantenere l'elaborazione bloccata durante l'attesa, l'elaborazione, la revisione o l'attesa dell'azione del cliente.
5. Confermare i risultati asincroni#
Configura webhook per lo stato dell'ordine e del pagamento Per il commerciante e l'ambiente. Verifica la firma, accetta le consegne ripetute in modo idempotente e conferma la richiesta prima di eseguire operazioni complesse.
Quando la risposta sincrona viene persa o la notifica è in ritardo, recuperare l'ordine originale con GET /merchants/orders/{order_token}. Verificare lo stato del pagamento recuperato prima di procedere con l'elaborazione o prima di tentare nuovamente.
Per i timeout di rete, seguire Gestione dei timeout del clienteUn timeout del cliente non indica che il pagamento è fallito.
6. Implementare operazioni post-pagamento#
Esporre solo le operazioni supportate dalla connessione selezionata e dallo stato corrente del pagamento:
Per un comportamento avanzato, consultare la sezione Rimborso Parziale Multiplo, Rimborsi multipli parzialie Rimborso asincrono.
Controllo di prontezza per l'ambiente di produzione#
- Le chiavi private sono memorizzate solo nella configurazione backend protetta e sono eliminate dai log.
- Ambienti di test e di produzione: credenziali, URL di base, connessioni e dati sono isolati.
- Ogni punto raggiungibile stato del pagamento e l'azione richiesta al cliente viene implementata.
- Il backend conserva gli identificatori degli ordini, i corpi delle richieste e le chiavi idempotenti per il recupero.
- Vengono testate le firme dei webhook, la consegna duplicata, la consegna ritardata e gli aggiornamenti fuori sequenza.
- Il comportamento del timeout del client segue il modello concordato per timeout e riconciliazione..
-
429E gli errori della piattaforma seguono le linee guida per il rate limiting. e la Riferimento all'errore. - I controlli per la cattura, l'annullamento e il rimborso sono visualizzati solo se supportati dalla connessione e dallo stato corrente.
- I scenari di successo, rifiuto, 3DS, in attesa, timeout, riprova e fallimento del fornitore sono certificati prima dell'implementazione.