Elementi essenziali per l’integrazione API

Configura questi aspetti condivisi prima di integrare una risorsa dell’API DEUNA. Le stesse regole di ambiente, rete, nuovo tentativo e timeout valgono per ordini, pagamenti, utenti, link di pagamento e abbonamenti.

AmbientiChiedi ad Athia informazioni#

Ambienti di test e di produzione sono isolati e utilizzano credenziali, dati, connessioni al provider e stato di pagamento differenti.

Vedi Autenticazione e ambienti per i tipi di credenziali, la rotazione e gli esempi di richiesta.

Raccolta PostmanChiedi ad Athia informazioni#

Usa la raccolta Postman di DEUNA per esplorare le richieste prima di sviluppare un client.

Apri la raccolta DEUNA in Postman

1. Accedi a Postman e crea un fork della raccolta nel tuo workspace.
2. Seleziona l’ambiente sandbox o produzione.
3. Imposta merchant_id, public_api_keye private_api_key con i valori dell’ambiente.
4. Inizia da un’operazione del catalogo degli endpoint.

Indirizzi IPChiedi ad Athia informazioni#

Preferire l'elenco di domini supportato quando la politica di rete lo consente. Se un provider di pagamento o di frodi richiede l'elenco di indirizzi IP, utilizzare gli indirizzi indicati di seguito.

Codici di rispostaChiedi ad Athia informazioni#

Le operazioni riuscite restituiscono una risposta 2xx . Una risposta 4xx indica che autenticazione, autorizzazioni, dati o stato della risorsa devono cambiare. Una risposta 5xx è un errore temporaneo di DEUNA o del provider e deve essere ritentata solo quando l’operazione può essere ripetuta in sicurezza.

Usa il riferimento per risposte e codici di errore per identificare causa, policy di nuovo tentativo e azione correttiva.

Richieste idempotentiChiedi ad Athia informazioni#

Invia una X-Idempotency-Key per ogni operazione supportata che crea o modifica lo stato di pagamento. Riutilizzare la stessa chiave e lo stesso corpo di richiesta byte per byte quando si riprova dopo un errore di rete o un timeout del client. Utilizzare una nuova chiave per un nuovo tentativo di business.

X-Api-Key: YOUR_PRIVATE_API_KEY
X-Store-Code: STORE_CODE
X-Idempotency-Key: order_1042-attempt_1
Content-Type: application/json

Le risposte di successo vengono conservate per 24 ore per impostazione predefinita. Leggi Richieste idempotenti Per gli endpoint supportati, gestione delle risposte di errore, intestazioni di riproduzione, conflitti e verifica dell'ambiente di test.

Timeout del clientChiedi ad Athia informazioni#

Un timeout del client significa che il chiamante ha smesso di attendere; non dimostra che il pagamento sia fallito. L’elaborazione può proseguire attraverso controlli antifrode, instradamento e provider dopo la disconnessione.

Quando una richiesta di pagamento scade:

1. Mantieni bloccato il fulfillment e contrassegna il tentativo come in attesa di riconciliazione nel tuo sistema.
2. Conserva l’ID ordine, il corpo e la chiave di idempotenza originale.
3. Ritenta solo quando l’operazione è idonea, con la stessa chiave e un corpo identico.
4. Riconciliare lo stato finale tramite il modello supportato di elaborazione asincrona e un'appropriata ricerca dell'ordine nel catalogo degli endpoint.
5. Mostra il risultato riconciliato all’acquirente e completa eventuali storni o rimborsi prima del fulfillment.