Flussi di consenso | DEUNA Docs

In questa pagina

Fornitori e comportamenti supportati
Ciclo di vita
Prima di iniziare
Crea il consenso
Approvazione completa del fornitore
Leggi l'ultimo stato
Gestire il consenso webhooks
Utilizzare il consenso approvato
comportamento di riprovazione sicuro
Elenco di controllo dell'integrazione

Consent è l'autorizzazione del cliente che un portafoglio supportato richiede prima che DEUNA possa recuperare le opzioni di pagamento, memorizzare un account, o completare un acquisto. DEUNA espone un contratto di consenso pubblico durante l'adattamento del flusso specifico del fornitore dietro di esso.

Fornitori e comportamenti supportati#

Fornitore	Chi utilizza il consenso	Esperienza di approvazione	Fonte di stato	Ritiro
NuPay	Cliente ospite o autenticato, quando abilitato per la connessione	Il cliente approva l'esperienza Nubank	Provider webhook; `GET /merchants/orders/{order_token}/consent` restituisce l'ultimo stato DEUNA	Bound all'ordine e all'identità del cliente; l'autorizzazione scaduta può essere rinnovata quando supportata
Portafoglio PayPal	Cliente autenticato utilizzando PayPal Vault	Reindirizza il cliente al reso `redirect_url`	DEUNA presenta PayPal quando il consenso diventa idoneo alla verifica	L'account PayPal approvato è esposto come metodo di pagamento memorizzato per gli acquisti successivi

Altri metodi di pagamento possono utilizzare reindirizzamenti, OTP o 3DS, ma non utilizzano questa API di consenso. Non chiamare gli endpoint del consenso a meno che la connessione del portafoglio selezionata non sia configurata per il consenso.

Ciclo di vita#

Diagramma di sequenza

Commerciante o clienteDEUNAProvider o processore

La normale progressione dello stato è pending a success. Trattamenti failed e expired come terminale. Trattare qualsiasi stato non riconosciuto o negato come non riuscito e non inviare l'acquisto con esso.

Prima di iniziare#

Configurare la connessione NuPay o PayPal Wallet per il corretto negozio e ambiente.
Crea un ordine e conservarne order_token.
Per i conti PayPal riutilizzabili, autenticare il cliente e inviare il token del portatore dell'utente su richieste di consenso.
Leggi la risposta del metodo di pagamento. Per PayPal Vault, authorization.required: true e authorization.flow: "consent" indicare che il cliente ha bisogno di consenso. Utilizzare i campi di polling restituiti invece di codificare duramente una cadenza.
Configurazione order.webhook_urls.notify_order così il tuo backend riceve modifiche di stato di consenso.

POST /merchants/orders/{order_token}/consent

Il percorso pubblico API Gateway non include intenzionalmente l'interno /api/v1 servizio prefisso.

curl --request POST \
  --url 'https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN/consent' \
  --header 'X-API-KEY: YOUR_PRIVATE_API_KEY' \
  --header 'X-Store-Code: all' \
  --header 'Authorization: Bearer USER_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "payment_method": "wallet",
    "payment_method_id": "MERCHANT_PAYMENT_METHOD_ID",
    "identity_document": "58188896454",
    "identity_document_type": "CPF"
  }'

const response = await fetch("https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN/consent", {
  method: "POST",
  headers: {
    "X-API-KEY": "YOUR_PRIVATE_API_KEY",
    "X-Store-Code": "all",
    "Authorization": "Bearer USER_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "payment_method": "wallet",
    "payment_method_id": "MERCHANT_PAYMENT_METHOD_ID",
    "identity_document": "58188896454",
    "identity_document_type": "CPF"
  })
});

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

import requests

response = requests.request(
    "POST",
    "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN/consent",
    headers={
        "X-API-KEY": "YOUR_PRIVATE_API_KEY",
        "X-Store-Code": "all",
        "Authorization": "Bearer USER_TOKEN",
        "Content-Type": "application/json"
    },
    json={
          "payment_method": "wallet",
          "payment_method_id": "MERCHANT_PAYMENT_METHOD_ID",
          "identity_document": "58188896454",
          "identity_document_type": "CPF"
        },
)
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/consent",
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: YOUR_PRIVATE_API_KEY",
    "X-Store-Code: all",
    "Authorization: Bearer USER_TOKEN",
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode([
      "payment_method" => "wallet",
      "payment_method_id" => "MERCHANT_PAYMENT_METHOD_ID",
      "identity_document" => "58188896454",
      "identity_document_type" => "CPF"
    ])
]);

$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/consent"))
      .header("X-API-KEY", "YOUR_PRIVATE_API_KEY")
      .header("X-Store-Code", "all")
      .header("Authorization", "Bearer USER_TOKEN")
      .header("Content-Type", "application/json")
      .method("POST", HttpRequest.BodyPublishers.ofString("{\n    \"payment_method\": \"wallet\",\n    \"payment_method_id\": \"MERCHANT_PAYMENT_METHOD_ID\",\n    \"identity_document\": \"58188896454\",\n    \"identity_document_type\": \"CPF\"\n  }"))
      .build();

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

package main

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

func main() {
  request, err := http.NewRequest("POST", "https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN/consent", strings.NewReader("{\n    \"payment_method\": \"wallet\",\n    \"payment_method_id\": \"MERCHANT_PAYMENT_METHOD_ID\",\n    \"identity_document\": \"58188896454\",\n    \"identity_document_type\": \"CPF\"\n  }"))
  if err != nil { panic(err) }
  request.Header.Set("X-API-KEY", "YOUR_PRIVATE_API_KEY")
  request.Header.Set("X-Store-Code", "all")
  request.Header.Set("Authorization", "Bearer USER_TOKEN")
  request.Header.Set("Content-Type", "application/json")

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

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

Campo	Obbligatorio	Descrizione
`payment_method`	Raccomandazioni	Uso `wallet`. Se omesso, DEUNA utilizza il metodo di pagamento sull'ordine.
`payment_method_id`	Raccomandazioni	L'identificatore di connessione è restituito dalla risposta del pagamento-metodo dell'ordine. Evita l'ambiguità quando è abilitata più di una connessione al portafoglio.
`identity_document`	NuPay	Documento di identità del cliente. Se omesso, DEUNA può derivare dall'indirizzo dell'ordine quando presente.
`identity_document_type`	NuPay	Tipo di documento, come `CPF`. Se omesso, DEUNA può derivare dall'indirizzo dell'ordine quando presente.

Per un utente autenticato, il token del portatore consente a DEUNA di associare il consenso di successo a tale utente e connessione. Un consenso degli ospiti rimane in ordine.

Busta di risposta

JSON

{
  "id": "1625a32a-df4c-4d9b-aec1-4510b3625865",
  "type": "transaction.authentication.pending",
  "created": "1740608931",
  "data": {
    "request_id": "req_01JQ7X",
    "order": {
      "order_token": "7e975d44-a061-4d70-af0f-673f6ee56445",
      "transaction_id": "merchant-order-1042",
      "external_transaction_id": ""
    },
    "consent": {
      "id": "6fe9a045-9a46-4b25-8b60-d5a9586494c5",
      "status": "pending",
      "expires_at": "2026-10-02T18:30:00Z",
      "authorization_id": "provider-authorization-id",
      "redirect_url": "https://provider.example/approve"
    }
  }
}

Store data.consent.id, ma guidare l'UI da data.consent.status. Aprire redirect_url solo quando è presente. NuPay può richiedere l'approvazione nell'app del fornitore senza restituire un reindirizzamento del browser.

Approvazione completa del fornitore#

Per il portafoglio PayPal, invia al cliente data.consent.redirect_url. Il fornitore ritorna attraverso il consenso di DEUNA reindirizzare il percorso e DEUNA verifica lo stato del fornitore finale. Se il cliente annulla, il consenso viene contrassegnato come fallito e non deve essere utilizzato per l'acquisto.

Per NuPay, istruire al cliente di approvare la richiesta nell'esperienza Nubank. Il provider webhook aggiorna il consenso memorizzato da DEUNA.

Non costruire mai URL di approvazione del fornitore o DEUNA reindirizzare URL da soli. Usa gli URL nella risposta.

Leggi l'ultimo stato#

GET /merchants/orders/{order_token}/consent

curl --request GET \
  --url 'https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN/consent?payment_method=wallet&payment_method_id=MERCHANT_PAYMENT_METHOD_ID' \
  --header 'X-API-KEY: YOUR_PRIVATE_API_KEY' \
  --header 'X-Store-Code: all' \
  --header 'Authorization: Bearer USER_TOKEN'

const response = await fetch("https://api.sandbox.deuna.io/merchants/orders/ORDER_TOKEN/consent?payment_method=wallet&payment_method_id=MERCHANT_PAYMENT_METHOD_ID", {
  method: "GET",
  headers: {
    "X-API-KEY": "YOUR_PRIVATE_API_KEY",
    "X-Store-Code": "all",
    "Authorization": "Bearer USER_TOKEN"
  }
});

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/consent?payment_method=wallet&payment_method_id=MERCHANT_PAYMENT_METHOD_ID",
    headers={
        "X-API-KEY": "YOUR_PRIVATE_API_KEY",
        "X-Store-Code": "all",
        "Authorization": "Bearer USER_TOKEN"
    },
)
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/consent?payment_method=wallet&payment_method_id=MERCHANT_PAYMENT_METHOD_ID",
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: YOUR_PRIVATE_API_KEY",
    "X-Store-Code: all",
    "Authorization: Bearer USER_TOKEN"
  ]
]);

$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/consent?payment_method=wallet&payment_method_id=MERCHANT_PAYMENT_METHOD_ID"))
      .header("X-API-KEY", "YOUR_PRIVATE_API_KEY")
      .header("X-Store-Code", "all")
      .header("Authorization", "Bearer USER_TOKEN")
      .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/consent?payment_method=wallet&payment_method_id=MERCHANT_PAYMENT_METHOD_ID", nil)
  if err != nil { panic(err) }
  request.Header.Set("X-API-KEY", "YOUR_PRIVATE_API_KEY")
  request.Header.Set("X-Store-Code", "all")
  request.Header.Set("Authorization", "Bearer USER_TOKEN")

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

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

Uso authorization.start_polling_after_in_seconds e authorization.polling_interval_in_seconds dalla risposta del metallo di pagamento quando fornito. Smettere di inquinare non appena lo stato non è più pendingQuando expires_at è raggiunto, o quando il cliente lascia il flusso.

La risposta GET utilizza la stessa busta che crea il consenso. Controllare sempre entrambi data.consent.status e data.error; un risultato terminale di livello aziendale può essere rappresentato nella busta anche quando la richiesta HTTP stessa è riuscita.

DEUNA invia aggiornamenti di consenso all'ordine webhook_urls.notify_order URL. Gestire questi tipi di eventi:

Tipo di evento	Significato
`transaction.authentication.pending`	L'autorizzazione è stata creata e ha ancora bisogno di un'azione del cliente o del fornitore.
`transaction.authentication.updated`	L'autorizzazione è riuscita; il consenso può essere utilizzato.
`transaction.authentication.failed`	L'autorizzazione è fallita o il cliente ha annullato.
`transaction.authentication.expired`	Il consenso è scaduto prima che possa essere utilizzato.

Risponde con 2xx rapidamente, deduplicato dall'evento id, e quindi prendere l'ultimo consenso se il trattamento dipende dallo stato attuale. Consegna di Webhook e GET polling complemento uno all'altro; il vostro checkout dovrebbe tollerare o arrivare prima. Vedi Webhook.

NuPay

Dopo success, richiedere i metodi di pagamento dell'ordine e le opzioni di installazione NuPay. DEUNA utilizza l'autorizzazione valida per il consenso durante il recupero di tali opzioni e durante l'elaborazione dell'acquisto del portafoglio. Se l'autorizzazione è scaduta e il fornitore supporta il rinfresco, DEUNA tenta di rinfrescarlo.

Portafoglio PayPal

Per un utente autenticato, l'account PayPal approvato appare in stored_payment_methods. Inviare l'identificatore di metodo memorizzato come acquisto payment_method; DEUNA verifica che il consenso appartiene allo stesso utente, commerciante e connessione PayPal prima di utilizzarlo.

Rimuovere il metodo di pagamento del portafoglio memorizzato rimuove anche il consenso riutilizzabile associato.

DELETE /users/payment-methods/{payment_method_id}/tokens/{payment_method}

Uso payment_method_id per l'identificatore di connessione PayPal e payment_method per l'identificatore del metodo memorizzato restituito nel stored_payment_methods. Questo endpoint autenticato dall'utente rimuove l'account portafoglio al fornitore ed elimina il relativo consenso riutilizzabile in DEUNA.

curl --request DELETE \
  --url 'https://api.sandbox.deuna.io/users/payment-methods/MERCHANT_PAYMENT_METHOD_ID/tokens/STORED_PAYMENT_METHOD_ID' \
  --header 'Authorization: Bearer USER_TOKEN' \
  --header 'X-Merchant-ID: MERCHANT_ID'

const response = await fetch("https://api.sandbox.deuna.io/users/payment-methods/MERCHANT_PAYMENT_METHOD_ID/tokens/STORED_PAYMENT_METHOD_ID", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer USER_TOKEN",
    "X-Merchant-ID": "MERCHANT_ID"
  }
});

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

import requests

response = requests.request(
    "DELETE",
    "https://api.sandbox.deuna.io/users/payment-methods/MERCHANT_PAYMENT_METHOD_ID/tokens/STORED_PAYMENT_METHOD_ID",
    headers={
        "Authorization": "Bearer USER_TOKEN",
        "X-Merchant-ID": "MERCHANT_ID"
    },
)
response.raise_for_status()
data = response.json()

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.deuna.io/users/payment-methods/MERCHANT_PAYMENT_METHOD_ID/tokens/STORED_PAYMENT_METHOD_ID",
  CURLOPT_CUSTOMREQUEST => "DELETE",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer USER_TOKEN",
    "X-Merchant-ID: MERCHANT_ID"
  ]
]);

$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/users/payment-methods/MERCHANT_PAYMENT_METHOD_ID/tokens/STORED_PAYMENT_METHOD_ID"))
      .header("Authorization", "Bearer USER_TOKEN")
      .header("X-Merchant-ID", "MERCHANT_ID")
      .method("DELETE", 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("DELETE", "https://api.sandbox.deuna.io/users/payment-methods/MERCHANT_PAYMENT_METHOD_ID/tokens/STORED_PAYMENT_METHOD_ID", nil)
  if err != nil { panic(err) }
  request.Header.Set("Authorization", "Bearer USER_TOKEN")
  request.Header.Set("X-Merchant-ID", "MERCHANT_ID")

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

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

Un successo di cancellazione ritorna 204 No Content. Se il fornitore segnala che l'account memorizzato è invalido durante un acquisto, DEUNA rimuove anche il consenso riutilizzabile non valido in modo che non venga offerto di nuovo.

comportamento di riprovazione sicuro#

Prima di creare un nuovo consenso, leggere lo stato attuale se la risposta precedente è stata persa.
Un'ancora valida pending o success il consenso viene riutilizzato invece di creare un'altra autorizzazione del fornitore.
Non riprova failed o expired Indefinitamente. Avviare un nuovo tentativo di cliente dopo aver risolto la causa.
A 404 significa che DEUNA non ha potuto trovare il consenso per l'ordine o il contesto dell'utente.
A 400 può indicare campi non validi, una connessione non supportata, un flusso di ospiti disabili o un risultato del fornitore di terminali.
Tenere le chiavi API private e i gettoni utente su superfici di fiducia. Non registrate intestazioni di richiesta o dati di autorizzazione del fornitore.

Elenco di controllo dell'integrazione#

L'ordine, la connessione, la valuta, il negozio e l'ambiente corrispondono.
Il documento di identità e il tipo sono disponibili per NuPay.
Il cliente viene autenticato prima di creare il consenso PayPal riutilizzabile.
L'app supporta le esperienze redirect e di approvazione del provider.
Polling utilizza la cadenza restituita da DEUNA e si ferma negli stati terminali.
notify_order accetta e deduplica gli eventi di autenticazione.
L'acquisto inizia solo dopo data.consent.status è success.
In sandbox vengono testati i percorsi di guasto, disdetta, di cancellazione e di riprovazione.