SDK Headless (Paiement Web)

👍

SDK recommandé

Nous recommandons d'utiliser le Seamless Web SDK pour une expérience d'intégration fluide. Cette option offre une solution de paiement flexible avec des composants d'interface utilisateur (UI) pré-intégrés et des options de personnalisation.

Le SDK Headless de Yuno vous permet de créer des paiements. Notez que lors de l'utilisation du SDK Headless, vous devrez demander et envoyer via API tous les champs obligatoires requis par le fournisseur de paiement pour générer le paiement dans son API.

Le SDK Headless de Yuno vous permet de créer des paiements selon deux scénarios différents :

• Créer un Token à usage unique en utilisant les informations de votre carte de crédit, puis créez un paiement.
• Créer un Token à usage unique à l'aide d'un vaulted_token d'une carte de crédit précédemment enregistrée, puis créer un paiement.

Les étapes suivantes décrivent la création d'un paiement à l'aide du SDK Headless de Yuno.

Étape 1 : Inclure la bibliothèque dans votre projet

Avant de procéder à l'implémentation du SDK Headless, consultez l'aperçu de l'intégration du SDK pour des instructions détaillées sur la manière d'intégrer correctement le SDK dans votre projet.

Le guide d'intégration propose trois méthodes flexibles :

1. Inclusion directe du script HTML
2. Injection dynamique en JavaScript
3. Installation du module NPM

Choisissez la méthode d'intégration qui convient le mieux à votre flux de développement. Après avoir terminé l'intégration du SDK, vous pouvez procéder aux étapes suivantes pour implémenter la fonctionnalité de paiement Headless.

📘

Bibliothèque TypeScript

Si vous utilisez TypeScript, Yuno fournit une bibliothèque que vous pouvez utiliser pour voir toutes les méthodes disponibles dans le SDK Web de Yuno.

Étape 2 : Initialiser le SDK Headless avec la clé publique

Dans votre application JavaScript, créez une instance de la classe Yuno en fournissant une PUBLIC_API_KEY.

const yuno = await Yuno.initialize(PUBLIC_API_KEY);

📘

Identifiants

Pour plus d'informations, Consultez la page des identifiants : https://docs.y.uno/reference/authentication

Étape 3 : Démarrer le processus de paiement

Ensuite, vous démarrerez le processus de paiement en utilisant la fonction apiClientPayment en fournissant les paramètres de configuration nécessaires.

Paramètres

Configurez le paiement avec les options suivantes :

const apiClientPayment = yuno.apiClientPayment({
  country_code: "US",
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3"
});

Étape 4 : Générer un token

Après avoir collecté toutes les informations utilisateur, vous pouvez démarrer le paiement. Tout d'abord, vous devez créer un token à usage unique (OTT) à l'aide de la fonction  apiClientpayment.generateToken. Comme il s'agit d'une fonction asynchrone, vous pouvez utiliser try/catch pour vous assurer que vous gérez correctement les erreurs déclenchées. Les exemples suivants montrent différents scénarios pour créer le token à usage unique :

1. Exemple 1: créer un token à usage unique en utilisant une carte comme méthode de paiement et en incluant toutes les informations nécessaires sur la carte.
2. Exemple 2: Créer un token à usage unique en utilisant les informations du vaulted_token .

📘

Avantages d'utiliser un Token Sécurisé

Lorsque vous utilisez un token sécurisé avec le SDK, toutes les informations de fraude des fournisseurs que vous avez configurés dans votre routage de carte sont collectées et attachées au token à usage unique. De plus, vous pouvez ajouter des informations de versement et un code de sécurité si le fournisseur l'exige.

const oneTimeToken = await apiClientPayment.generateToken({
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
  payment_method: {
    type: "CARD",
    vaulted_token: null,
    card: {
      save: false,
      detail: {
        expiration_month: 11,
        expiration_year: 25,
        number: "4111111111111111",
        security_code: "123",
        holder_name: "ANDREA B",
        type: "DEBIT"
      },
      installment: {
        id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
        value: 1
      }
    },
    customer: {},
    device_fingerprint: "0753b47f-bb43-86ab-647b-d735b67baac6",
    third_party_session_id: "QbJU2KolVUm1fhQR0s9qgrS0ArEQmEfE"
  }
});

Paramètres de l'exemple 1

const oneTimeToken = await apiClientPayment.generateToken({
  checkout_session: "eec6578e-ac2f-40a0-8065-25b5957f6dd3",
  payment_method: {
    type: "CARD",
    vaulted_token: "aad8578e-ac2f-40a0-8065-25b5957f6555",
    card: {
      detail: {
        security_code: "123"
      },
      installment: {
        id: "64ceacef-0886-4c81-9779-b2b3029c4e8b",
        value: 1
      }
    }
  }
});

Paramètres de l'exemple 2

Le bloc de code suivant montre les réponses de la fonction apiClientPayment.generateToken pour les deux exemples ci-dessus :

{
  "token": "ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d",
  "vaulted_token": null,
  "vault_on_success": false,
  "type": "CARD",
  "card_data": {
    "holder_name": "ANDREA B",
    "iin": "41111111",
    "lfd": "1111",
    "number_length": 16,
    "security_code_length": 3,
    "brand": "VISA",
    "type": "CREDIT",
    "category": "CREDIT",
    "issuer_name": "JPMORGAN CHASE BANK N A",
    "issuer_code": null
  },
  "customer": {
    "first_name": "Cesar",
    "last_name": "Sanchez",
    "email": "[email protected]",
    "gender": "",
    "phone": null,
    "billing_address": null,
    "document": null,
    "browser_info": {
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36",
      "accept_header": "*/*",
      "accept_content": "*/*",
      "accept_browser": "*/*",
      "color_depth": "24",
      "screen_height": "1080",
      "screen_width": "2560",
      "javascript_enabled": true,
      "java_enabled": false,
      "browser_time_difference": "300",
      "language": "en-US"
    },
    "device_fingerprint": "19764508-c9df-a90b-a365-83b2d718c12e"
  },
  "installment": null,
  "country": "CO"
}

{
  token: 'ee78bc2a-63b4-45bb-bd28-3e6829ab1c3d',
  vaulted_token: aad8578e-ac2f-40a0-8065-25b5957f6555,
  vault_on_success: false,
  type: 'CARD',
  card_data: {
    holder_name: 'ANDREA B',
    iin: '41111111',
    lfd: '1111',
    number_length: 16,
    security_code_length: 3,
    brand: 'VISA',
    type: 'CREDIT',
    category: 'CREDIT',
    issuer_name: 'JPMORGAN CHASE BANK N A',
    issuer_code: null,
  },
  customer: {
    first_name: 'Cesar',
    last_name: 'Sanchez',
    email: '[email protected]',
    gender: '',
    phone: null,
    billing_address: null,
    document: null,
    browser_info: {
      user_agent:
        'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/121.0.0.0 Safari/537.36',
      accept_header: '*/*',
      accept_content: '*/*',
      accept_browser: '*/*',
      color_depth: '24',
      screen_height: '1080',
      screen_width: '2560',
      javascript_enabled: true,
      java_enabled: false,
      browser_time_difference: '300',
      language: 'en-US',
    },
    device_fingerprint: '19764508-c9df-a90b-a365-83b2d718c12e',
  },
  installment: null,
  country: 'CO',
}

Étape 5 : Créer le Paiement

Après avoir reçu le token à usage unique, vous pouvez créer le paiement à l'aide du endpoint  Créer Paiement  pour obtenir le résultat de paiement final. Vous informerez le token à usage unique reçu à l' Étape 4  via le paramètre payment_method.token de la requête. Le bloc de code suivant montre un exemple de requête pour la création d'un paiement :

{
  "merchant_order_id": "0000022",
  "country": "US",
  "account_id": "<Your account_id>",
  "description": "Test",
  "amount": {
    "currency": "USD",
    "value": 500
  },
  "customer_payer": {
    "id": "cfae0941-7234-427a-a739-ef4fce966c79"
  },
  "checkout": {
    "session": "<checkout session>"
  },
  "workflow": "SDK_CHECKOUT",
  "payment_method": {
    "type": "CARD",
    "token": "2cd31999-e44e-4de3-bbe4-179981ff4295"
  }
}

La réponse du endpoint fournit le paramètre sdk_action_required qui définit si des actions supplémentaires sont nécessaires pour conclure le paiement :

• Si votre client sélectionne une méthode de paiement synchrone, le paiement est effectué instantanément. Dans ce scénario, le champ sdk_action_required dans la réponse de l'API sera false, et le processus de paiement se termine à cette étape.
• Lorsqu'une interaction supplémentaire du SDK est nécessaire pour compléter le flux de paiement, sdk_action_required sera true. Si tel est le cas, vous devez suivre les instructions de l' l'Étape 6.

Étape 6 : Obtenir l'URL de défi 3DS

Comme décrit sur la page Vérification de la carte 3DS, un paiement avec 3DS peut nécessiter une vérification supplémentaire de l'identité du client. Si une étape de vérification supplémentaire est nécessaire en raison d'un défi de vérification 3DS, la réponse du endpoint Créer un paiement contiendra les informations suivantes :

• A THREE_D_SECURE .
• Un statut égal à PENDING et un sous-statut égal à WAITING_ADDITIONAL_STEP.
• Le champ sdk_action_required défini sur true.

Pour obtenir l'URL du défi 3DS, vous devez appeler la fonction getThreeDSecureChallenge , en fournissant la checkoutSession utilisé pour créer le paiement.

const data = await apiClientPayment.getThreeDSecureChallenge(checkoutSession?: string): Promise<{url: string}>

Si la carte ne nécessite pas de défi pour vérifier l'identité du client, l' url retournera null.

Dans un navigateur web, vous pouvez ouvrir l'URL dans un nouvel onglet ou une IFrame. Pour ouvrir l'URL dans une iframe, vous devez définir le paramètre embedded = true. Sinon, vous pouvez omettre ce paramètre, dont la valeur par défaut est false. Le bloc de code suivant montre un exemple d'affichage du contenu du défi 3DS dans une IFrame :

document.querySelector('#element').innerHTML = `
   <iframe
     src="${data.url}&embedded=true"
     height="700px"
     width="100%"
     border="0"
     frameBorder="0">
   </iframe>
 `;

window.addEventListener('message', (event) => {
   if (
        !event.origin.toLocaleLowerCase().includes('sdk-3ds') ||
        event?.data?.origin !== 'CHALLENGE'
   ) {
     return
   }
   document.querySelector('#element').innerHTML = '';
   if (event.data.status === 'ERROR') {
     document.querySelector('#element').innerHTML = 'There was an error';
   } else {
     document.querySelector('#element').innerHTML = 'Challenge was finished';
   }
});

Vous êtes responsable de rediriger vos clients vers l'URL fournie par la fonction redirect_url pour compléter le défi. Une fois que le client a réussi le défi 3DS, il sera automatiquement redirigé vers le callback_url, que vous avez fournie lors de la création de la checkout_session avec l'objet  Créer une session de paiement .

Pour compléter le flux de paiement du Headless SDK , vous devez utiliser les Webhooks Yuno, qui vous informeront rapidement du résultat du défi 3DS et du statut final du paiement. L'utilisation de webhooks garantit que vous recevez des mises à jour en temps réel sur la progression de la transaction de paiement. En plus des webhooks, vous pouvez récupérer les informations de paiement à l'aide du endpoint Récupérer Paiement par ID.

Étape 7 : Obtenir les actions de paiement

Parfois, le paiement peut nécessiter une action supplémentaire pour continuer le flux de paiement. Pour déterminer l'action nécessaire, vous devez appeler la méthode getContinuePaymentAction , en fournissant la checkoutSession utilisé pour créer le paiement.

const data = await apiClientPayment.getContinuePaymentAction({ checkoutSession: string }): Promise<ContinuePaymentAction>

Le champ getContinuePaymentAction retourne un objet ContinuePaymentAction qui décrit l'action spécifique requise pour continuer le flux de paiement, en fonction du fournisseur et de l'étape spécifique requise.

ContinuePaymentAction Structure de la réponse

La réponse contient des informations sur le type d'action requis et les données nécessaires pour effectuer cette action :

type ContinuePaymentAction = {
  type: Provider.Type;
  action: Provider.Action;
  payment_code?: {
    code: string;
    reference: string;
    expiration_time?: number;
  };
  image?: {
    type: string;
    value: string;
    reference: string;
    expiration_time?: number;
    additional_data?: Record<string, undefined>;
  };
  redirect?: {
    init_url: string;
    success_url: string;
    error_url: string;
  };
  otp?: {
    length: number;
    expiration_time: number;
    retries: {
      accepts: boolean;
      number: number;
    };
    resend: {
      timer: number;
      number: number;
    };
    payment_instructions: string;
  };
  three_d_secure_redirect?: {
    init_url: string;
    access_token: string;
    redirect_url?: string;
  };
  transaction_id?: string;
  request_html?: {
    body?: Record<string, string>;
    headers?: Record<string, string>;
    method?: "POST" | "GET" | "PUT" | "PATCH" | "DELETE";
    url: string;
  };
  sdk_provider?: {
    client_id?: string;
    intent?: string;
    components?: string;
    gateway: string;
    init_url?: string;
    merchant_id: string;
    amount: {
      currency: string;
      value: number;
    };
    protocol_version?: string;
    provider_id?: string;
    payment_methods?: string[];
    supported_networks?: string[];
    session?: {
      epoch_timestamp: number;
      expires_at: number;
      merchant_session_identifier: string;
      nonce: string;
      merchant_identifier: string;
      domain_name: string;
      display_name: string;
      signature: string;
      operational_analytics_identifier: string;
      retries: number;
      psp_id: string;
    };
    provider_token_id?: string;
  };
  render_html?: {
    content?: string;
    redirect_url?: string;
  };
  info?: {
    screen_info?: string;
  };
  render_iframe: {
    init_url: string;
    access_token: string;
    redirect_url?: string;
  };
};

ContinuePaymentAction Champs

Types et Actions de Fournisseurs

Les énumérations suivantes définissent les fournisseurs de paiement pris en charge et les actions possibles :

export declare namespace Provider {
  enum Type {
    MERCADO_PAGO = "MERCADO_PAGO",
    WOMPI = "WOMPI",
    PAYMENTEZ = "PAYMENTEZ",
    GETNET = "GETNET",
    TRANSFEERA = "TRANSFEERA",
    CYBERSOURCE_3DS = "CYBERSOURCE_3DS",
    NETCETERA_3DS = "NETCETERA_3DS",
    XENDIT_3DS = "XENDIT_3DS",
    DLOCAL = "DLOCAL",
    CIELO = "CIELO",
    INSWITCH = "INSWITCH",
    PAGALEVE = "PAGALEVE",
    UNLIMINT_3DS = "UNLIMINT_3DS"
  }

  enum Action {
    PAYMENT_CODE = "PAYMENT_CODE",
    IMAGE = "IMAGE",
    REDIRECT_URL = "REDIRECT_URL",
    FORM = "FORM",
    INFO = "INFO",
    OTP = "OTP",
    SDK_PROVIDER = "SDK_PROVIDER",
    THREE_D_SECURE_REDIRECT_URL = "THREE_D_SECURE_REDIRECT_URL",
    REQUEST_HTML = "REQUEST_HTML",
    RENDER_HTML = "RENDER_HTML",
    RENDER_IFRAME = "RENDER_IFRAME"
  }
}

Types et Actions de Fournisseurs

Gestion des différents types d'actions

Selon le champ action dans la réponse, vous devez gérer chaque type d'action en conséquence :

REDIRECT_URL Action

Lorsque l'action est REDIRECT_URL, vous devez rediriger l'utilisateur vers l'URL fournie dans data.redirect.init_url:

if (data.action === "REDIRECT_URL") {
  window.location.href = data.redirect.init_url;
}

Autres types d'actions

Chaque type d'action nécessite une gestion spécifique basée sur les données fournies :

• PAYMENT_CODE: Afficher le code de paiement et la référence à l'utilisateur
• IMAGE: Afficher un code QR ou toute autre image à l'utilisateur
• OTP: Présenter un formulaire de saisie OTP à l'utilisateur
• SDK_PROVIDER: Initialiser le SDK du fournisseur spécifique
• RENDER_IFRAME: Afficher une iframe avec l'interface du fournisseur

📘

Gestion des Actions de Paiement

L'implémentation spécifique pour la gestion de chaque type d'action dépendra du framework UI et des exigences de votre application. Assurez-vous de gérer tous les types d'actions possibles que vos fournisseurs de paiement configurés pourraient retourner.

📘

Application Démo

En plus des exemples de code fournis, vous pouvez accéder à l'Application Démo pour une implémentation complète des SDK Yuno.

Restez informé

Visitez le journal des modifications pour les dernières mises à jour du SDK et l'historique des versions.