Aller au contenu principal

Exemple d'intégration avec PayPal

Dans ce tutoriel, nous allons vous montrer comment intégrer PayPal et explorer de nouveaux nœuds.

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

1.1. L'événement "commande créée" dans le module "Événements".​

Pour suivre les événements dans le module "Intégrations", créez un événement dans le module "Événements".

Le bloc Événements est décrit en détail ici.

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

  • Faites glisser le nœud "événements" sur l'espace de travail.
  • Changez la valeur dans le champ "Définir" en "orderEvent".
  • L'événement sera enregistré dans l'objet "msg.orderEvent" et pourra être utilisé dans d'autres nœuds.
  • Sélectionnez l'événement créé "commande créée" dans la liste et cliquez sur "soumettre".

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 future.

Plus de détails sur le nœud Événements peuvent être trouvés ici.

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

2.1. Créer un compte de paiement

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

Les instructions sur la façon de procéder sont décrites ici.

2.2. Créer une session de paiement

  • Faites glisser le nœud "admin-api" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Sélectionnez la méthode "Créer une session de paiement" et insérez le code de la description ci-dessous dans le champ "Corps de la requête".
{
  "orderId": {{orderEvent.order.id}},
  "type": "session"
}

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

Plus de détails sur le nœud admin-api peuvent être trouvés ici.

2.3. Définir l'identifiant reçu dans msg.paymentSessionId

  • Faites glisser le nœud "function" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Insérez le code de l'exemple dans le champ "Fonction".

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

msg.paymentSessionId = msg.payload.id

return msg

Plus de détails sur le nœud Fonction peuvent être trouvés ici.

3. Authentification avec PayPal​

3.1. Définir les paramètres pour l'authentification avec PayPal

  • Faites glisser le nœud "function" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Insérez le code de l'exemple dans le champ "Fonction".

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

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

return msg

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

Plus de détails sur le nœud Fonction peuvent être trouvés ici.

3.2. Demande de jeton d'accès

  • Faites glisser le nœud "http request" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Sélectionnez "POST" dans le champ Méthode.
  • Sélectionnez "Envoyer comme corps de requête" dans le champ Données.
  • Insérez le lien https://api-m.sandbox.paypal.com/v1/oauth2/token dans le champ Lien.
  • Sélectionnez "Objet JSON" dans le champ Retour.
  • Choisissez "Utiliser l'authentification".
  • Entrez votre ID client dans le champ "Nom d'utilisateur" et votre secret client pour PayPal dans le champ "Mot de passe".

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

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

Plus de détails sur le nœud http request peuvent être trouvés ici.

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

  • Faites glisser le nœud "function" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Insérez le code de l'exemple dans le champ "Fonction".

Dans cet exemple, nous formons une requête pour créer un lien de paiement basé sur les 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 commande, obtenues dans le nœud "commande créée"
// l'objet commande correspond à la commande de l'API des commandes https://oneentry.cloud/instructions/api
const order = msg.orderEvent.order
// ID de session de paiement, obtenu dans le nœud "créer une session de paiement"
const paymentSessionId = msg.paymentSessionId

// former des données pour paypal basées sur les données de 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

Plus de détails peuvent être trouvés dans la documentation PayPal.

Plus de détails sur le nœud Fonction peuvent être trouvés ici.

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

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

  • Faites glisser le nœud "http request" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Sélectionnez "POST" dans le champ Méthode.
  • Sélectionnez "Envoyer comme corps de requête" dans le champ Données.
  • Insérez le lien https://api-m.sandbox.paypal.com/v2/checkout/orders dans le champ Lien.
  • Sélectionnez "Objet JSON" dans le champ Retour.

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.

Plus de détails peuvent être trouvés dans la documentation PayPal.

Plus de détails sur le nœud http request peuvent être trouvés ici.

5. Mise à jour de la session de paiement​

  • Faites glisser le nœud "admin-api" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Sélectionnez la méthode "Mise à jour de la session de paiement".
  • Insérez le code de la description ci-dessous dans le champ "Paramètres de requête".
{
  "id": {{paymentSessionId}}
}
  • Insérez le code de la description ci-dessous dans le champ "Corps de la requête".
{
  "paymentUrl": "{{{payload.links.1.href}}}"
}

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.

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

Plus de détails sur le nœud admin-api peuvent être trouvés ici.

6. Ajout d'un point de terminaison pour récupérer le lien de paiement​

6.1. Définir le sujet "createPaymentLink"

  • Faites glisser le nœud "function" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Insérez le code de l'exemple dans le champ "Fonction".

Ceci est nécessaire pour identifier le flux actuel.

msg.topic = 'createPaymentLink'

return msg

Plus de détails sur le nœud Fonction peuvent être trouvés ici.

6.2. Créer un point de terminaison pour récupérer le lien de paiement

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

Ce point de terminaison sera nécessaire pour récupérer le lien de paiement actuel.

Plus de détails sur le nœud http in peuvent être trouvés ici.

6.3. Définir le sujet "getPaymentLink"

  • Faites glisser le nœud "function" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Insérez le code de l'exemple dans le champ "Fonction".

Ceci est nécessaire pour identifier le flux actuel.

msg.topic = 'getPaymentLink'

return msg

Plus de détails sur le nœud Fonction peuvent être trouvés ici.

6.4. Enregistrer les données dans le contexte

  • Faites glisser le nœud "function" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Insérez le code de l'exemple dans le champ "Fonction".

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

// obtenir l'ID de 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 terminés, envoyer la réponse avec la session actuelle
if (
    contextData.createPaymentLinkCompleted &&
    contextData.getPaymentLinkCompleted
) {
    // obtenir la session de paiement par ID depuis 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

Plus de détails sur le nœud Fonction peuvent être trouvés ici.

6.5. Point de sortie pour le lien de paiement

  • Faites glisser le nœud "http response" sur l'espace 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.

Plus de détails sur le nœud http response peuvent être trouvés ici.

7. Configuration des webhooks pour PayPal​

7.1. Point d'entrée pour PayPal

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

Ce point de terminaison sera nécessaire pour mettre à jour le statut de paiement via PayPal.

Plus de détails sur le nœud http in peuvent être trouvés ici.

7.2. Réponse à la requête

  • Faites glisser le nœud "function" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Insérez le code de l'exemple dans le champ "Fonction".

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

msg.payload = {
    ok: true,
}

return msg

Plus de détails sur le nœud fonction peuvent être trouvés ici.

7.3. Point de sortie pour PayPal

  • Faites glisser le nœud "http response" sur l'espace 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.

Plus de détails sur le nœud http response peuvent être trouvés ici.

7.4. Obtenir le statut de paiement

  • Faites glisser le nœud "function" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Insérez le code de l'exemple dans le champ "Fonction".

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

msg.status = msg.payload.resource.status

return msg

Plus de détails sur le nœud Fonction peuvent être trouvés ici.

7.5. Vérification du statut de paiement

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

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

Plus de détails sur le nœud switch peuvent être trouvés ici.

7.6. Obtenir l'ID de session de paiement

  • Faites glisser le nœud "function" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Insérez le code de l'exemple dans le champ "Fonction".

Dans ce nœud, nous prenons l'ID de session de paiement que nous avons enregistré dans le nœud "définir les données de paiement".

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

return msg

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

Plus de détails sur le nœud Fonction peuvent être trouvés ici.

7.7. Mise à jour du statut de paiement

  • Faites glisser le nœud "admin-api" sur l'espace de travail et connectez-le au nœud de l'étape précédente.
  • Sélectionnez la méthode "Mise à jour de la session de paiement".
  • Insérez le code de la description ci-dessous dans le champ "Paramètres de requête".
{
    "id": {{paymentSessionId}}
}
  • Insérez le code de la description ci-dessous dans le champ "Corps de la requête".
{
    "status": "completed"
}

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

Plus de détails sur le nœud admin-api peuvent être trouvés ici.

7. Ajouter un webhook dans votre compte PayPal​

Le lien vers votre projet + /api/admin/workflows/endpoints/paypal.

Exemple :

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

Plus de détails peuvent être trouvés dans la documentation PayPal.

8. Tester l'intégration​

8.1. Créer une commande

IMG1

IMG2

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

8.2. Obtenir le lien de paiement

IMG3

  • Faites une requête POST à https://integrations-study.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link, en remplaçant https://integrations-study.oneentry.cloud par le lien vers votre projet.

  • Dans le corps de la requête, spécifiez l'ID de la commande créée précédemment :

{
    "orderId": 15
}

8.3. Payer la commande

IMG4

8.4. Vérifier le statut de la commande

IMG5.