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'espace 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.

Plus d'informations 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.

Comment faire cela est décrit 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"
}

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

Plus d'informations sur le nœud admin-api peuvent être trouvées ici.

2.3. Définissez 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".

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

Plus d'informations 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'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".

Ici, nous définissons les valeurs dans les champs "payload" et "headers" de l'objet "msg". Ces valeurs sont nécessaires pour exécuter le 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

Pour plus d'informations sur les paramètres de paiement, vous pouvez consulter la documentation de PayPal.

Plus d'informations 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'espace de travail et connectez-le au nœud de l'étape précédente.
Sélectionnez "POST" dans le champ Method.
Sélectionnez "Send as request body" dans le champ Data.
Collez l'URL https://api-m.sandbox.paypal.com/v1/oauth2/token dans le champ Link.
Sélectionnez "Object JSON" dans le champ Return.
Cochez "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".

Pour plus d'informations sur l'authentification, vous pouvez consulter la documentation de PayPal.

Plus d'informations 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'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".

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

Pour plus d'informations, vous pouvez consulter la documentation de PayPal.

Plus d'informations 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'espace de travail et connectez-le au nœud de l'étape précédente.
Sélectionnez "POST" dans le champ Method.
Sélectionnez "Send as request body" dans le champ Data.
Collez l'URL https://api-m.sandbox.paypal.com/v2/checkout/orders dans le champ Link.
Sélectionnez "Object JSON" dans le champ Return.

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.

Pour plus d'informations, vous pouvez consulter la documentation de PayPal.

Plus d'informations sur le nœud http request peuvent être trouvées 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}}}"
}

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.

Pour plus d'informations sur les valeurs retournées, vous pouvez consulter la documentation de PayPal.

Plus d'informations sur le nœud admin-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'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".

Ceci est nécessaire pour identifier le flux actuel.

msg.topic = 'createPaymentLink'

return msg

Plus d'informations 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'espace de travail.
Sélectionnez "POST".
Entrez le lien /get-payment-link.

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

Plus d'informations 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'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".

Ceci est nécessaire pour identifier le flux actuel.

msg.topic = 'getPaymentLink'

return msg

Plus d'informations 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'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".

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

// obtenir l'identifiant de la commande actuelle
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 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 d'informations 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'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 d'informations 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'espace de travail.
Sélectionnez "POST".
Entrez le lien /paypal.

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

Plus d'informations 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'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".

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

msg.payload = {
    ok: true,
}

return msg

Plus d'informations 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'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 d'informations sur le nœud http response peuvent être trouvées 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".

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

Plus d'informations sur le nœud Function peuvent être trouvées 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", écrivez "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 "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.

Plus d'informations 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'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".

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

Pour plus d'informations sur les valeurs retournées, vous pouvez consulter la documentation de PayPal.

Plus d'informations sur le nœud Function peuvent être trouvées 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"
}

Ici, nous mettons à jour le statut du paiement en fonction de son identifiant dans "msg.paymentSessionId".

Plus d'informations sur le nœud admin-api peuvent être trouvées ici.

7.8. Ajoutez un webhook dans votre compte PayPal

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

Exemple :

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

Pour plus d'informations, vous pouvez consulter la documentation de PayPal.

8. Vérification de l'intégration

8.1. Créez une commande

Comment créer une commande est décrit dans la documentation de l'API.

8.2. Obtenez un lien de paiement

Effectuez 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

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​

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

8. Vérification de l'intégration