Exemple d'intégration avec PayPal

Dans ce tutoriel, nous allons montrer comment intégrer PayPal et examiner les nouveaux nœuds.

1. Suivi de l'événement de création de commande

1.1. Événement "order created" dans le module "Events".

Pour suivre les événements dans le module "Integrations", créez un événement dans le module "Events".

Le bloc Events est décrit en détail ici.

1.2. Suivi de l'événement de création de commande.

Faites glisser le nœud "events" sur l'aire de travail.
Modifiez la valeur dans le champ "Set" en "orderEvent".
L'événement sera enregistré dans l'objet "msg.orderEvent" et pourra être utilisé dans d'autres nœuds.
Sélectionnez dans la liste l'événement créé "order created" et cliquez sur "submit".

Dans cet exemple, nous nous abonnons à l'événement de création de commande et enregistrons l'événement dans "msg.orderEvent" pour une utilisation ultérieure.

Des informations détaillées sur le nœud Events peuvent être trouvées ici.

2. Création d'une session de paiement

2.1. Créez un compte de paiement

Avant de commencer l'intégration, créez un compte personnalisé pour PayPal.

Des informations sur la façon de le faire sont décrites ici.

2.2. Créez une session de paiement

Faites glisser le nœud "api" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Sélectionnez la méthode "Create Payment Session" et collez le code de la description ci-dessous dans le champ "Data".

Ici, nous extrayons l'identifiant de la commande de l'objet "msg.orderEvent" et formons une requête pour créer une session de paiement. La requête pour créer une session prend en entrée les paramètres : "orderId" - identifiant et "type" - type de session de paiement (session ou intent).

{
  "orderId": {{orderEvent.order.id}},
  "type": "session"
}

Des informations détaillées sur le nœud API peuvent être trouvées ici.

2.3. Définissez l'identifiant obtenu dans msg.paymentSessionId

Faites glisser le nœud "function" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Collez le code de l'exemple dans le champ "Function".

Ici, nous définissons dans "msg.paymentSessionId" l'identifiant de la session de paiement obtenu à la suite de l'exécution du nœud précédent.

msg.paymentSessionId = msg.payload.id;

return msg;

Des informations détaillées sur le nœud Function peuvent être trouvées ici.

3. Authentification auprès de PayPal

3.1. Définissez les paramètres pour l'authentification auprès de PayPal

Faites glisser le nœud "function" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Collez le code de l'exemple dans le champ "Function".

Ici, nous définissons les valeurs dans les champs "payload" et "headers" de l'objet "msg". Ces valeurs sont nécessaires pour l'exécution du nœud suivant.

// définissons le corps de la requête
msg.payload = {
  grant_type: 'client_credentials'
};
// définissons les en-têtes
msg.headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

return msg;

Des informations détaillées sur les paramètres de paiement peuvent être trouvées dans la documentation PayPal.

Des informations détaillées sur le nœud Function peuvent être trouvées ici.

3.2. Requête pour obtenir un access token

Faites glisser le nœud "http request" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Sélectionnez dans le champ Method l'option "POST".
Sélectionnez dans le champ Data l'option "Send as request body".
Collez dans le champ Link le lien https://api-m.sandbox.paypal.com/v1/oauth2/token.
Sélectionnez dans le champ Return l'option "Object JSON".
Sélectionnez "Use Authentication".
Dans le champ "Username", entrez votre client ID, et dans le champ "Password", votre client secret pour PayPal.

Cette requête est nécessaire pour obtenir un "access_token".

Des informations détaillées sur l'authentification peuvent être trouvées dans la documentation PayPal.

Des informations détaillées sur le nœud http request peuvent être trouvées ici.

3.3. Définissez les paramètres pour créer un lien de paiement

Faites glisser le nœud "function" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Collez le code de l'exemple dans le champ "Function".

Dans cet exemple, nous formons une requête pour créer un lien de paiement sur la base des données des nœuds précédents.

// access_token pour paypal, obtenu dans le nœud "paypal auth"
const accessToken = msg.payload.access_token;
// données de la commande, obtenues dans le nœud "order created"
// l'objet order correspond à la commande de l'API orders https://oneentry.cloud/instructions/api
const order = msg.orderEvent.order;
// identifiant de la session de paiement, obtenu dans le nœud "create payment session"
const paymentSessionId = msg.paymentSessionId;

// formons les données pour paypal sur la base des données de la commande
const items = order.products.map(product => {
  return {
    name: product.title,
    description: 'votre description',
    quantity: String(product.quantity),
    unit_amount: {
      currency_code: order.currency,
      value: product.price
    }
  }
})

const totalSum = parseFloat(order.totalSum)

const data = {
  intent: 'CAPTURE',
  purchase_units: [
    {
      items,
      custom_id: String(paymentSessionId),
      amount: {
        currency_code: order.currency,
        value: totalSum,
        breakdown: {
          item_total: {
            currency_code: order.currency,
            value: totalSum,
          },
        },
      },
      payment_instruction: {
        billingId: String(order.id),
      },
    },
  ],
  payment_source: {
    paypal: {
      experience_context: {
        payment_method_preference: 'UNRESTRICTED',
        payment_method_selected: 'PAYPAL',
        brand_name: 'EXAMPLE INC',
        locale: 'fr-FR',
        landing_page: 'LOGIN',
        shipping_preference: 'NO_SHIPPING',
        user_action: 'PAY_NOW',
        return_url: "https://example.com/return",
        cancel_url: "https://example.com/cancel",
      },
    },
  },
}

// Corps de la requête
msg.payload = data;
// En-têtes de la requête
msg.headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${accessToken}`,
  'Prefer': 'return=representation',
};

return msg;

Des informations détaillées peuvent être trouvées dans la documentation PayPal.

Des informations détaillées sur le nœud Function peuvent être trouvées ici.

4. Création d'un lien de paiement

Dans cet exemple, nous utilisons le nœud "http request". Il peut être utilisé pour effectuer des requêtes http.

Faites glisser le nœud "http request" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Sélectionnez dans le champ Method l'option "POST".
Sélectionnez dans le champ Data l'option "Send as request body".
Collez dans le champ Link le lien https://api-m.sandbox.paypal.com/v2/checkout/orders.
Sélectionnez dans le champ Return l'option "Object JSON".

Dans cet exemple, nous avons fait une requête à PayPal pour générer un lien de paiement avec les données du nœud précédent.

Des informations détaillées peuvent être trouvées dans la documentation PayPal.

Des informations détaillées sur le nœud http request peuvent être trouvées ici.

5. Mise à jour de la session de paiement

Faites glisser le nœud "api" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Sélectionnez la méthode "Update Payment Session" et collez le code de la description ci-dessous dans le champ "Data".

Ici, nous extrayons l'identifiant du lien de paiement "msg.paymentSessionId" et le lien de paiement "msg.payload.links[0].href" des requêtes précédentes.

{
  "id": {{paymentSessionId}},
  "paymentUrl": "{{{payload.links.1.href}}}"
}

Des informations détaillées sur les valeurs retournées peuvent être trouvées dans la documentation PayPal.

Des informations détaillées sur le nœud API peuvent être trouvées ici.

6. Ajout d'un endpoint pour obtenir un lien de paiement

6.1. Définissez le sujet "createPaymentLink"

Faites glisser le nœud "function" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Collez le code de l'exemple dans le champ "Function".

Ceci est nécessaire pour identifier le flux actuel.

msg.topic = 'createPaymentLink';

return msg;

Des informations détaillées sur le nœud Function peuvent être trouvées ici.

6.2. Créez un endpoint pour obtenir un lien de paiement

Faites glisser le nœud "http in" sur l'aire de travail.
Sélectionnez la méthode "POST".
Entrez le lien /get-payment-link.

Cet endpoint sera nécessaire pour obtenir le lien de paiement actuel.

Des informations détaillées sur le nœud http in peuvent être trouvées ici.

6.3. Définissez le sujet "getPaymentLink"

Faites glisser le nœud "function" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Collez le code de l'exemple dans le champ "Function".

Ceci est nécessaire pour identifier le flux actuel.

msg.topic = 'getPaymentLink';

return msg;

Des informations détaillées sur le nœud Function peuvent être trouvées ici.

6.4. Enregistrez les données dans le contexte

Faites glisser le nœud "function" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Collez le code de l'exemple dans le champ "Function".

Ceci est nécessaire pour former la réponse.

// obtenir l'identifiant de la commande actuel
const orderId = msg.payload.orderId;
// clé de contexte actuelle
const contextKey = `payment_link_${orderId}`;
// obtenir l'API OneEntry
const api = global.get('api');
// données de contexte actuelles
const contextData = flow.get(contextKey) || {};
// définir les données dans le contexte par sujet
if (msg.topic === 'createPaymentLink') {
    contextData.paymentSessionId = msg.paymentSessionId;
    contextData.createPaymentLinkCompleted = true;
}
if (msg.topic === 'getPaymentLink') {
    contextData.getPaymentLinkCompleted = true;
    contextData.res = msg.res;
}
// définir les données de contexte dans le contexte
flow.set(contextKey, contextData);
// si createPaymentLink et getPaymentLink sont complétés, envoyer la réponse avec la session actuelle
if (contextData.createPaymentLinkCompleted && contextData.getPaymentLinkCompleted) {
  // obtenir la session de paiement par id de l'API
  const paymentSession = await api.getPaymentSessionById({ id: contextData.paymentSessionId });
  msg.payload = paymentSession;
  msg.res = contextData.res;

  // effacer l'API
  flow.set(contextKey, null);

  return msg;
}

return null;

Des informations détaillées sur le nœud Function peuvent être trouvées ici.

6.5. Point de sortie pour le lien de paiement

Faites glisser le nœud "http response" sur l'aire de travail et connectez-le au nœud de l'étape précédente.

Ceci est nécessaire pour renvoyer la réponse à la requête.

Des informations détaillées sur le nœud http response peuvent être trouvées ici.

7. Configuration des webhooks pour PayPal

7.1. Point d'entrée pour PayPal

Faites glisser le nœud "http in" sur l'aire de travail.
Sélectionnez la méthode "POST".
Entrez le lien /paypal.

Cet endpoint sera nécessaire pour mettre à jour le statut de paiement via PayPal.

Des informations détaillées sur le nœud http in peuvent être trouvées ici.

7.2. Réponse à la requête

Faites glisser le nœud "function" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Collez le code de l'exemple dans le champ "Function".

Ceci est nécessaire pour former la réponse.

msg.payload = {
  ok: true
}

return msg;

Des informations détaillées sur le nœud function peuvent être trouvées ici.

7.3. Point de sortie pour PayPal

Faites glisser le nœud "http response" sur l'aire de travail et connectez-le au nœud de l'étape précédente.

Ce nœud est nécessaire pour renvoyer la réponse à la requête.

Des informations détaillées sur le nœud http response peuvent être trouvées ici.

7.4. Obtention du statut de paiement

Faites glisser le nœud "function" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Collez le code de l'exemple dans le champ "Function".

Dans ce nœud, nous prenons la valeur obtenue du nœud "paypal webhook" et l'enregistrons dans "msg.status" pour l'utiliser dans le nœud suivant.

msg.status = msg.payload.resource.status;

return msg;

Des informations détaillées sur le nœud Function peuvent être trouvées ici.

7.5. Vérification du statut de paiement

Faites glisser le nœud "switch" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Dans "Property", écrivez la valeur "status".
Ajoutez la première règle pour la vérification. Sélectionnez la condition "==", dans la valeur entrez "APPROVED".
Ajoutez la deuxième règle pour la vérification. Sélectionnez la condition "else".

Ce nœud vérifiera la valeur de "msg.status" par rapport aux règles définies. Si la valeur est "APPROVED", les nœuds de la première branche seront exécutés, sinon ceux de la deuxième.

Des informations détaillées sur le nœud switch peuvent être trouvées ici.

7.6. Obtention de l'identifiant de la session de paiement

Faites glisser le nœud "function" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Collez le code de l'exemple dans le champ "Function".

Dans ce nœud, nous prenons l'identifiant de la session de paiement que nous avons enregistré dans le nœud "set payment data".

msg.paymentSessionId = parseInt(msg.payload.resource.purchase_units[0].custom_id, 10);

return msg;

Des informations détaillées sur les valeurs retournées peuvent être trouvées dans la documentation PayPal.

Des informations détaillées sur le nœud Function peuvent être trouvées ici.

7.7. Mise à jour du statut de paiement

Faites glisser le nœud "api" sur l'aire de travail et connectez-le au nœud de l'étape précédente.
Sélectionnez la méthode "Update Payment Session" et collez le code de la description ci-dessous dans le champ "Data".

Ici, nous mettons à jour le statut du paiement par son identifiant à partir de "msg.paymentSessionId".

{
  "id": {{paymentSessionId}},
  "status": "completed"
}

Des informations détaillées sur le nœud API peuvent être trouvées ici.

7. Ajoutez un webhook dans le tableau de bord PayPal

Lien vers votre projet + /api/admin/workflows/endpoints/paypal

Exemple :

https://integrations-study.oneentry.cloud/api/admin/workflows/endpoints/paypal

Des informations détaillées peuvent être trouvées dans la documentation PayPal.

8. Vérification de l'intégration

8.1. Créez une commande

Des informations sur la façon de créer une commande sont décrites dans la documentation API.

8.2. Obtenez un lien de paiement

Effectuez une requête POST à https://integrations-study.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link, au lieu de https://integrations-study.oneentry.cloud, remplacez par le lien vers votre projet.
Dans le corps de la requête, indiquez l'identifiant de la commande créée précédemment :

{
  "orderId": 15
}

8.3. Payez la commande

8.4. Vérifiez le statut de la commande

Exemple d'intégration avec PayPal

1. Suivi de l'événement de création de commande​

1.1. Événement "order created" dans le module "Events".​

1.2. Suivi de l'événement de création de commande.​

2. Création d'une session de paiement​

3. Authentification auprès de PayPal​

4. Création d'un lien de paiement​

5. Mise à jour de la session de paiement​

6. Ajout d'un endpoint pour obtenir un lien de paiement​

7. Configuration des webhooks pour PayPal​

7. Ajoutez un webhook dans le tableau de bord PayPal​

8. Vérification de l'intégration​

1. Suivi de l'événement de création de commande

1.1. Événement "order created" dans le module "Events".

1.2. Suivi de l'événement de création de commande.

2. Création d'une session de paiement

3. Authentification auprès de PayPal

4. Création d'un lien de paiement

5. Mise à jour de la session de paiement

6. Ajout d'un endpoint pour obtenir un lien de paiement

7. Configuration des webhooks pour PayPal

7. Ajoutez un webhook dans le tableau de bord PayPal

8. Vérification de l'intégration