Exemple d'intégration avec PayPal

Ce tutoriel montre comment intégrer PayPal et présente de 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 des é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'espace de travail.
Remplacez la valeur du champ "Set" par "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 "order created" que vous avez créé, puis 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 l'utiliser par la suite.

Le nœud Events est décrit en détail 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.

La procédure est décrite ici.

2.2. Créez 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 "Creating a payment session" et collez le code ci-dessous dans le champ "Request body".

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

Ce code extrait l'identifiant de la commande de l'objet "msg.orderEvent" et construit la requête de création de la session de paiement. Cette requête prend deux paramètres : "orderId", l'identifiant, et "type", le type de session de paiement (session ou intent).

Le nœud admin-api est décrit en détail ici.

2.3. Enregistrez l'identifiant obtenu 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.
Collez le code de l'exemple dans le champ "Function".

Ce code place dans "msg.paymentSessionId" l'identifiant de la session de paiement renvoyé par le nœud précédent.

msg.paymentSessionId = msg.payload.id

return msg

Le nœud Function est décrit en détail ici.

3. Authentification auprès de PayPal

3.1. Définissez les paramètres d'authentification PayPal

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

Ce code renseigne les champs "payload" et "headers" de l'objet "msg". Le nœud suivant a besoin de ces valeurs pour s'exécuter.

// 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

Pour en savoir plus sur les paramètres de paiement, consultez la documentation PayPal.

Le nœud Function est décrit en détail ici.

3.2. Requête d'obtention de l'access token

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

Cette requête permet d'obtenir l'"access_token".

Pour en savoir plus sur l'authentification, consultez la documentation PayPal.

Le nœud http request est décrit en détail ici.

3.3. Définissez les paramètres de création du 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.
Collez le code de l'exemple dans le champ "Function".

Ce code construit la requête de création du lien de paiement à partir des données des nœuds précédents.

// access_token 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 à une 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

// construire les données pour PayPal à partir des données de la commande
const items = order.products.map((product) => {
    return {
        name: product.title,
        description: 'your 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: 'en-US',
                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

Pour en savoir plus, consultez la documentation PayPal.

Le nœud Function est décrit en détail ici.

4. Création du lien de paiement

Cet exemple utilise le nœud "http request", qui permet d'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.
Dans le champ Method, sélectionnez "POST".
Dans le champ Data, sélectionnez "Send as request body".
Dans le champ Link, collez l'URL https://api-m.sandbox.paypal.com/v2/checkout/orders.
Dans le champ Return, sélectionnez "Object JSON".

Ce nœud demande à PayPal de générer un lien de paiement à partir des données du nœud précédent.

Pour en savoir plus, consultez la documentation PayPal.

Le nœud http request est décrit en détail 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 "Payment session update".
Collez le code ci-dessous dans le champ "Query parameters".

{
  "id": {{paymentSessionId}}
}

Collez le code ci-dessous dans le champ "Request body".

{
  "paymentUrl": "{{{payload.links.1.href}}}"
}

Ce code récupère dans les requêtes précédentes l'identifiant du lien de paiement "msg.paymentSessionId" et le lien de paiement "msg.payload.links[0].href".

Pour en savoir plus sur les valeurs renvoyées, consultez la documentation PayPal.

Le nœud admin-api est décrit en détail ici.

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

6.1. Définissez 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.
Collez le code de l'exemple dans le champ "Function".

Le sujet sert à identifier le flux en cours.

msg.topic = 'createPaymentLink'

return msg

Le nœud Function est décrit en détail ici.

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

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

Cet endpoint servira à obtenir le lien de paiement à jour.

Le nœud http in est décrit en détail ici.

6.3. Définissez 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.
Collez le code de l'exemple dans le champ "Function".

Le sujet sert à identifier le flux en cours.

msg.topic = 'getPaymentLink'

return msg

Le nœud Function est décrit en détail ici.

6.4. Enregistrez 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.
Collez le code de l'exemple dans le champ "Function".

Ce nœud sert à construire la réponse.

// obtenir l'identifiant de la commande en cours
const orderId = msg.payload.orderId
// clé de contexte en cours
const contextKey = `payment_link_${orderId}`
// obtenir l'API OneEntry
const api = global.get('api')
// données de contexte en cours
const contextData = flow.get(contextKey) || {}
// enregistrer les données dans le contexte selon le sujet
if (msg.topic === 'createPaymentLink') {
    contextData.paymentSessionId = msg.paymentSessionId
    contextData.createPaymentLinkCompleted = true
}
if (msg.topic === 'getPaymentLink') {
    contextData.getPaymentLinkCompleted = true
    contextData.res = msg.res
}
// écrire 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 en cours
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

Le nœud Function est décrit en détail 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.

Ce nœud renvoie la réponse à la requête.

Le nœud http response est décrit en détail ici.

7. Configuration des webhooks PayPal

7.1. Point d'entrée pour PayPal

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

Cet endpoint servira à mettre à jour le statut du paiement via PayPal.

Le nœud http in est décrit en détail 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.
Collez le code de l'exemple dans le champ "Function".

Ce nœud sert à construire la réponse.

msg.payload = {
    ok: true,
}

return msg

Le nœud function est décrit en détail 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 renvoie la réponse à la requête.

Le nœud http response est décrit en détail ici.

7.4. Obtention du statut du paiement

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

Ce nœud récupère la valeur reçue du nœud "paypal webhook" et l'écrit dans "msg.status" pour que le nœud suivant puisse l'utiliser.

msg.status = msg.payload.resource.status

return msg

Le nœud Function est décrit en détail ici.

7.5. Vérification du statut du 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 "Property", saisissez "status".
Ajoutez une première règle de vérification : sélectionnez la condition "==" et saisissez "APPROVED" comme valeur.
Ajoutez une deuxième règle de vérification : sélectionnez la condition "else".

Ce nœud compare la valeur de "msg.status" aux règles définies. Si elle vaut "APPROVED", les nœuds de la première branche s'exécutent, sinon ceux de la deuxième.

Le nœud switch est décrit en détail ici.

7.6. Obtention de l'identifiant de la 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.
Collez le code de l'exemple dans le champ "Function".

Ce nœud récupère l'identifiant de la session de paiement enregistré dans le nœud "set payment data".

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

return msg

Pour en savoir plus sur les valeurs renvoyées, consultez la documentation PayPal.

Le nœud Function est décrit en détail ici.

7.7. Mise à jour du statut du 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 "Payment session update".
Collez le code ci-dessous dans le champ "Query parameters".

{
    "id": {{paymentSessionId}}
}

Collez le code ci-dessous dans le champ "Request body".

{
    "status": "completed"
}

Ce nœud met à jour le statut du paiement à partir de son identifiant stocké dans "msg.paymentSessionId".

Le nœud admin-api est décrit en détail ici.

7.8. Ajoutez un webhook dans votre compte PayPal

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

Exemple :

https://<votre-projet>.oneentry.cloud/api/admin/workflows/endpoints/paypal

Pour en savoir plus, consultez la documentation PayPal.

8. Vérification de l'intégration

8.1. Créez une commande

Postman : requête POST vers orders-storage/marker/order_storage/orders avec les en-têtes Authorization et x-app-token, réponse « 201 Created » avec la commande id 15

Section « Orders », stockage « order storage » : commande n° 15 de 2.00 usd, paiement Paypal, statut « order created »

La création d'une commande est décrite dans la documentation de l'API.

8.2. Obtenez le lien de paiement

Postman : requête POST vers workflows/endpoints/get-payment-link avec le corps orderId 15, réponse « 200 OK » avec le statut waiting et un lien paymentUrl vers PayPal

Envoyez une requête POST à https://<votre-projet>.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link, en remplaçant https://<votre-projet>.oneentry.cloud par le lien de 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

Page de paiement PayPal de 2.00 $ : moyen « PayPal balance » sélectionné, bouton « Complete Purchase » en bas

8.4. Vérifiez le statut de la commande

Section « Orders », stockage « order storage » : la commande n° 15 a désormais le statut « order completed », avec une icône de cadenas dans la colonne « Actions »

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 du lien de paiement​

5. Mise à jour de la session de paiement​

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

7. Configuration des webhooks 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 du lien de paiement

5. Mise à jour de la session de paiement

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

7. Configuration des webhooks PayPal

8. Vérification de l'intégration