Autenticazione e chiavi API

Le credenziali di DEUNA rispondono a due domande diverse: Quale applicazione del commerciante sta effettuando la chiamata?, e, quando applicabile, Quale cliente autenticato lo sta utilizzando. Iniziare identificando il punto di partenza della richiesta e l'autorità necessaria, per poi confermare i requisiti esatti. catalogo degli endpoint.

Decidere quale credenziale utilizzareChiedi ad Athia informazioni#

Porre le seguenti domande in ordine:

1. La richiesta viene eseguita in un browser o in un'applicazione mobile? Utilizzare la chiave API pubblica o il contesto dell'applicazione documentato per l'SDK o l'endpoint. Non inserire la chiave privata in tale client.
2. Il vostro backend esegue operazioni di commerciante? Utilizzare la chiave API privata in X-Api-Key per chiamate tra server, come la creazione, il recupero, il pagamento, il rimborso o l'annullamento di un ordine.
3. È necessario che DEUNA riconosca il cliente autenticato? Aggiungere il token di accesso a breve durata del cliente come Authorization: Bearer … solo quando l'endpoint lo supporta. Questo fornisce alla richiesta il contesto specifico del cliente per risorse come i dati del profilo, gli indirizzi, gli strumenti di pagamento salvati o i flussi di pagamento autorizzati dal cliente.

Scegli la corretta credenzialiChiedi ad Athia informazioni#

Chiave API pubblica: integrazione lato clientChiedi ad Athia informazioni#

Utilizzare la chiave API pubblica quando il codice di DEUNA viene eseguito in un ambiente non attendibile, come un browser o un'applicazione mobile. Utilizzi tipici includono l'inizializzazione di un widget o SDK di DEUNA e l'identificazione del commerciante e dell'ambiente per la tokenizzazione e le esperienze di pagamento lato client supportate.

La chiave pubblica è intenzionalmente sicura da includere nella configurazione del client, ma non è una chiave segreta e non concede l'autorizzazione per eseguire transazioni, rimborsi, annullamenti o altre operazioni lato server del commerciante. Mantenere la chiave pubblica associata all'ambiente sandbox o di produzione corretto.

Chiave API privata: autorizzazione server-a-serverChiedi ad Athia informazioni#

Utilizzare la chiave API privata quando il vostro backend attendibile chiama un endpoint del commerciante. Le operazioni del commerciante che utilizzano l'autorizzazione tramite chiave API richiedono la chiave privata in X-Api-Key, mai Authorization: Bearer ….

curl --request GET \
  --url https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN \
  --header "X-Api-Key: YOUR_PRIVATE_API_KEY"

const response = await fetch("https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN", {
  method: "GET",
  headers: {
    "X-Api-Key": "YOUR_PRIVATE_API_KEY"
  }
});

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

import requests

response = requests.request(
    "GET",
    "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN",
    headers={
        "X-Api-Key": "YOUR_PRIVATE_API_KEY"
    },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-Api-Key: YOUR_PRIVATE_API_KEY"
  ]
]);

$response = curl_exec($curl);
curl_close($curl);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
  public static void main(String[] args) throws Exception {
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN"))
      .header("X-Api-Key", "YOUR_PRIVATE_API_KEY")
      .method("GET", HttpRequest.BodyPublishers.noBody())
      .build();

    HttpResponse<String> response = HttpClient.newHttpClient().send(
      request, HttpResponse.BodyHandlers.ofString()
    );
    System.out.println(response.body());
  }
}

package main

import (
  "fmt"
  "io"
  "net/http"
)

func main() {
  request, err := http.NewRequest("GET", "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN", nil)
  if err != nil { panic(err) }
  request.Header.Set("X-Api-Key", "YOUR_PRIVATE_API_KEY")

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()

  body, _ := io.ReadAll(response.Body)
  fmt.Println(string(body))
}

Token di accesso del cliente: contesto di un utente autenticatoChiedi ad Athia informazioni#

Utilizzare un token di accesso del cliente quando l'operazione deve agire nel contesto di un cliente attivo di DEUNA e l'endpoint supporta l'autenticazione tramite token. Inviatelo nell' Authorization header:

Authorization: Bearer USER_ACCESS_TOKEN

Il token Bearer è la risposta. quale cliente È in funzione. La chiave API fornisce le risposte. quale applicazione o backend del commerciante sta richiedendo l'accesso. A seconda dell'endpoint, una richiesta del cliente può quindi richiedere sia una chiave API per l'applicazione che il token Bearer del cliente.

Non inviare un token Bearer per un flusso di accesso ospite semplicemente perché l'header è disponibile. Non utilizzare una chiave privata del commerciante come token Bearer, né trattare un token del cliente come autorizzazione per operazioni riservate al commerciante. Se il tuo backend inoltra il contesto del cliente, fallo solo a un endpoint che supporti esplicitamente la combinazione.

AmbientiChiedi ad Athia informazioni#

Sandbox e produzione sono isolati. Ogni ambiente ha il proprio URL di base, chiavi API, configurazione del commerciante, connessioni, dati e stato del pagamento.

Conservare e ruotare i tastiChiedi ad Athia informazioni#

• Conservare le chiavi private in un gestore segreto o in una configurazione runtime protetta.
• Portare l'accesso al servizio e all'ambiente che hanno bisogno della chiave.
• Ridurre le credenziali dai registri delle richieste e dagli allegati di supporto.
• Distribuire una chiave di ricambio prima di rivocare la vecchia chiave, quindi il traffico di produzione continua in modo sicuro.
• Coordinate l'emissione e la rotazione delle chiavi con il vostro operatore di amministrazione autorizzato o DEUNA TAM.

Fallimenti di autenticazioneChiedi ad Athia informazioni#

Un'autorizzazione di ritorno normalmente 401 Unauthorized o 403 Forbidden. Prima di riprovare, verificare:

1. La credenziale è presente nell'intestazione documentata.
2. La chiave appartiene all'ambiente richiesto e commerciante.
3. Il endpoint supporta il metodo di autorizzazione che hai inviato.
4. Il token chiave o cliente non è scaduto o è stato revocato.
5. Qualsiasi contesto commerciale, commerciale o cliente richiesto è presente.

Non riprovare un errore di autorizzazione indefinitamente. Conservare la risposta request_id quando disponibile e includerlo quando contatta il supporto.

Limiti di tassoChiedi ad Athia informazioni#

DEUNA non applica un singolo limite di richieste al secondo a tutte le integrazioni. L'API Gateway valuta i limiti configurati come un numero massimo di richieste all'interno di una finestra temporale. Il limite effettivo può variare in base al commerciante, all'ambiente, al metodo HTTP e all'endpoint.

Quando una richiesta supera un limite applicabile, il gateway restituisce 429 Too Many Requests con Retry-After header. La risposta a livello di percorso ha la seguente forma:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1

{
  "error": "rate_limit_exceeded",
  "message": "maximum requests",
  "code": 429,
  "endpoint": "/merchants/orders",
  "total_requests": 101,
  "retry_after": "1s"
}

I campi di risposta possono differire quando una misura di sicurezza a livello di gateway rifiuta la richiesta. Considerare lo stato HTTP e Retry-After header come autorevoli.

Maniglia 429 Gestire le risposte in modo sicuro

1. Sospendere l'invio di richieste per almeno il numero di secondi specificato in Retry-After.
2. Riprovare con backoff esponenziale e jitter invece di rilasciare immediatamente il traffico in attesa come un nuovo picco.
3. Per la stessa operazione di pagamento, utilizzare la chiave idempotenza originale e lo stesso corpo della richiesta.
4. Coordinare il throttling tra worker e istanze dell'applicazione; i loop di retry a livello di processo possono superare collettivamente un limite condiviso per merchant o endpoint.
5. Se 429 Le risposte continuano dopo la riduzione del traffico, conservando il corpo della risposta e l'ID della richiesta, quindi contattare il supporto DEUNA o il Technical Account Manager (TAM).

Richiedere un aumento del limite

Chiedere al supporto DEUNA o al TAM di rivedere il limite prima di un aumento pianificato del traffico. Includere:

• L'ambiente e l'ID del merchant.
• I metodi HTTP e gli endpoint interessati.
• I tassi di richiesta sostenuti e di picco previsti, la durata del picco e la data di implementazione pianificata.
• Gli indirizzi IP pubblici o i CIDR di uscita utilizzati dai sistemi del merchant che chiamano DEUNA.

Non includere API key, token Bearer o altre informazioni riservate nelle richieste di supporto.

ContinuaChiedi ad Athia informazioni#