Ejemplo de integración con PayPal

En este tutorial mostramos cómo integrar PayPal y vemos nodos nuevos.

1. Seguimiento del evento de creación de pedido

1.1. Evento "order created" en el módulo "Events"

Para hacer seguimiento de eventos en el módulo "Integrations", crea un evento en el módulo "Events".

Aquí se describe en detalle el bloque Events.

1.2. Seguimiento del evento de creación de pedido

Arrastra el nodo "events" al área de trabajo.
Cambia el valor del campo "Set" a "orderEvent".
El evento se guardará en el objeto "msg.orderEvent" y podrás usarlo en otros nodos.
Selecciona en la lista el evento "order created" que creaste y haz clic en "submit".

En este ejemplo nos suscribimos al evento de creación de pedido y guardamos el evento en "msg.orderEvent" para usarlo más adelante.

Aquí encontrarás más detalles sobre el nodo Events.

2. Creación de una sesión de pago

2.1. Crea una cuenta de pago

Antes de empezar la integración, crea una cuenta personalizada para PayPal.

Aquí se explica cómo hacerlo.

2.2. Crea una sesión de pago

Arrastra el nodo "admin-api" al área de trabajo y conéctalo con el nodo del paso anterior.
Selecciona el método "Creating a payment session" y pega el siguiente código en el campo "Request body".

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

Aquí tomamos el identificador del pedido del objeto "msg.orderEvent" y formamos la solicitud para crear la sesión de pago. La solicitud recibe los parámetros "orderId" (identificador) y "type" (tipo de sesión de pago: session o intent).

Aquí encontrarás más detalles sobre el nodo admin-api.

2.3. Guarda el identificador obtenido en msg.paymentSessionId

Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
Pega el código del ejemplo en el campo "Function".

Aquí guardamos en "msg.paymentSessionId" el identificador de la sesión de pago que devolvió el nodo anterior.

msg.paymentSessionId = msg.payload.id

return msg

Aquí encontrarás más detalles sobre el nodo Function.

3. Autenticación en PayPal

3.1. Define los parámetros de autenticación en PayPal

Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
Pega el código del ejemplo en el campo "Function".

Aquí asignamos valores a los campos "payload" y "headers" del objeto "msg". El siguiente nodo necesita estos valores para ejecutarse.

// definimos el cuerpo de la solicitud
msg.payload = {
    grant_type: 'client_credentials',
}
// definimos los encabezados
msg.headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
    Accept: 'application/json',
}

return msg

Consulta la documentación de PayPal para más información sobre los parámetros de pago.

Aquí encontrarás más detalles sobre el nodo Function.

3.2. Solicitud del access token

Arrastra el nodo "http request" al área de trabajo y conéctalo con el nodo del paso anterior.
En el campo Method, selecciona "POST".
En el campo Data, selecciona "Send as request body".
En el campo Link, pega la URL https://api-m.sandbox.paypal.com/v1/oauth2/token.
En el campo Return, selecciona "Object JSON".
Selecciona "Use Authentication".
En el campo "Username", introduce tu client ID de PayPal, y en el campo "Password", tu client secret.

Esta solicitud sirve para obtener el "access_token".

Consulta la documentación de PayPal para más información sobre la autenticación.

Aquí encontrarás más detalles sobre el nodo http request.

3.3. Define los parámetros para crear el enlace de pago

Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
Pega el código del ejemplo en el campo "Function".

En este ejemplo se forma la solicitud para crear el enlace de pago a partir de los datos de los nodos anteriores.

// access_token de PayPal obtenido en el nodo "paypal auth"
const accessToken = msg.payload.access_token
// datos del pedido obtenidos en el nodo "order created"
// el objeto order corresponde a un pedido de la orders api https://oneentry.cloud/instructions/api
const order = msg.orderEvent.order
// identificador de la sesión de pago obtenido en el nodo "create payment session"
const paymentSessionId = msg.paymentSessionId

// formamos los datos para PayPal a partir de los datos del pedido
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',
            },
        },
    },
}

// Cuerpo de la solicitud
msg.payload = data
// Encabezados de la solicitud
msg.headers = {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
    Prefer: 'return=representation',
}

return msg

Encontrarás más información en la documentación de PayPal.

Aquí encontrarás más detalles sobre el nodo Function.

4. Creación del enlace de pago

En este ejemplo se usa el nodo "http request", con el que puedes hacer solicitudes HTTP.

Arrastra el nodo "http request" al área de trabajo y conéctalo con el nodo del paso anterior.
En el campo Method, selecciona "POST".
En el campo Data, selecciona "Send as request body".
En el campo Link, pega la URL https://api-m.sandbox.paypal.com/v2/checkout/orders.
En el campo Return, selecciona "Object JSON".

En este ejemplo enviamos a PayPal una solicitud para generar el enlace de pago con los datos del nodo anterior.

Encontrarás más información en la documentación de PayPal.

Aquí encontrarás más detalles sobre el nodo http request.

5. Actualización de la sesión de pago

Arrastra el nodo "admin-api" al área de trabajo y conéctalo con el nodo del paso anterior.
Selecciona el método "Payment session update".
Pega el siguiente código en el campo "Query parameters".

{
  "id": {{paymentSessionId}}
}

Pega el siguiente código en el campo "Request body".

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

Aquí tomamos de las solicitudes anteriores el identificador del enlace de pago "msg.paymentSessionId" y el enlace de pago "msg.payload.links[0].href".

Consulta la documentación de PayPal para más información sobre los valores devueltos.

Aquí encontrarás más detalles sobre el nodo admin-api.

6. Agregar un endpoint para obtener el enlace de pago

6.1. Define el tópico "createPaymentLink"

Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
Pega el código del ejemplo en el campo "Function".

Sirve para identificar el flujo actual.

msg.topic = 'createPaymentLink'

return msg

Aquí encontrarás más detalles sobre el nodo Function.

6.2. Crea un endpoint para obtener el enlace de pago

Arrastra el nodo "http in" al área de trabajo.
Selecciona el método "POST".
Introduce la URL /get-payment-link.

Este endpoint servirá para obtener el enlace de pago actualizado.

Aquí encontrarás más detalles sobre el nodo http in.

6.3. Define el tópico "getPaymentLink"

Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
Pega el código del ejemplo en el campo "Function".

Sirve para identificar el flujo actual.

msg.topic = 'getPaymentLink'

return msg

Aquí encontrarás más detalles sobre el nodo Function.

6.4. Guarda los datos en el contexto

Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
Pega el código del ejemplo en el campo "Function".

Sirve para formar la respuesta.

// obtener el id del pedido actual
const orderId = msg.payload.orderId
// clave del contexto actual
const contextKey = `payment_link_${orderId}`
// obtener la API de OneEntry
const api = global.get('api')
// datos del contexto actual
const contextData = flow.get(contextKey) || {}
// guardar datos en el contexto según el tópico
if (msg.topic === 'createPaymentLink') {
    contextData.paymentSessionId = msg.paymentSessionId
    contextData.createPaymentLinkCompleted = true
}
if (msg.topic === 'getPaymentLink') {
    contextData.getPaymentLinkCompleted = true
    contextData.res = msg.res
}
// guardar los datos del contexto en el contexto
flow.set(contextKey, contextData)
// si createPaymentLink y getPaymentLink se completaron, enviar la respuesta con la sesión actual
if (
    contextData.createPaymentLinkCompleted &&
    contextData.getPaymentLinkCompleted
) {
    // obtener de la API la sesión de pago por id
    const paymentSession = await api.getPaymentSessionById({
        id: contextData.paymentSessionId,
    })
    msg.payload = paymentSession
    msg.res = contextData.res

    // limpiar la API
    flow.set(contextKey, null)

    return msg
}

return null

Aquí encontrarás más detalles sobre el nodo Function.

6.5. Punto de salida para el enlace de pago

Arrastra el nodo "http response" al área de trabajo y conéctalo con el nodo del paso anterior.

Sirve para devolver la respuesta a la solicitud.

Aquí encontrarás más detalles sobre el nodo http response.

7. Configuración de webhooks para PayPal

7.1. Punto de entrada para PayPal

Arrastra el nodo "http in" al área de trabajo.
Selecciona el método "POST".
Introduce la URL /paypal.

Este endpoint servirá para actualizar el estado del pago a través de PayPal.

Aquí encontrarás más detalles sobre el nodo http in.

7.2. Respuesta a la solicitud

Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
Pega el código del ejemplo en el campo "Function".

Sirve para formar la respuesta.

msg.payload = {
    ok: true,
}

return msg

Aquí encontrarás más detalles sobre el nodo function.

7.3. Punto de salida para PayPal

Arrastra el nodo "http response" al área de trabajo y conéctalo con el nodo del paso anterior.

Este nodo sirve para devolver la respuesta a la solicitud.

Aquí encontrarás más detalles sobre el nodo http response.

7.4. Obtención del estado del pago

Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
Pega el código del ejemplo en el campo "Function".

En este nodo tomamos el valor recibido del nodo "paypal webhook" y lo guardamos en "msg.status" para usarlo en el siguiente nodo.

msg.status = msg.payload.resource.status

return msg

Aquí encontrarás más detalles sobre el nodo Function.

7.5. Comprobación del estado del pago

Arrastra el nodo "switch" al área de trabajo y conéctalo con el nodo del paso anterior.
En "Property", escribe el valor "status".
Agrega la primera regla: selecciona la condición "==" e introduce el valor "APPROVED".
Agrega la segunda regla: selecciona la condición "else".

Este nodo comprobará si el valor de "msg.status" cumple las reglas definidas. Si el valor es "APPROVED", se ejecutarán los nodos de la primera rama; si no, los de la segunda.

Aquí encontrarás más detalles sobre el nodo switch.

7.6. Obtención del identificador de la sesión de pago

Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
Pega el código del ejemplo en el campo "Function".

En este nodo tomamos el identificador de la sesión de pago que guardamos en el nodo "set payment data".

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

return msg

Consulta la documentación de PayPal para más información sobre los valores devueltos.

Aquí encontrarás más detalles sobre el nodo Function.

7.7. Actualización del estado del pago

Arrastra el nodo "admin-api" al área de trabajo y conéctalo con el nodo del paso anterior.
Selecciona el método "Payment session update".
Pega el siguiente código en el campo "Query parameters".

{
    "id": {{paymentSessionId}}
}

Pega el siguiente código en el campo "Request body".

{
    "status": "completed"
}

Aquí actualizamos el estado del pago según su identificador, tomado de "msg.paymentSessionId".

Aquí encontrarás más detalles sobre el nodo admin-api.

7.8. Agrega el webhook en tu cuenta de PayPal

Enlace a tu proyecto + /api/admin/workflows/endpoints/paypal

Ejemplo:

https://<tu-proyecto>.oneentry.cloud/api/admin/workflows/endpoints/paypal

Encontrarás más información en la documentación de PayPal.

8. Comprobación de la integración

8.1. Crea un pedido

Postman: solicitud POST a orders-storage/marker/order_storage/orders con las cabeceras Authorization y x-app-token, respuesta "201 Created" con el pedido id 15

Sección "Orders", almacenamiento "order storage": pedido n.º 15 por 2.00 usd, pago con Paypal, estado "order created"

Cómo crear un pedido se explica en la documentación de la API.

8.2. Obtén el enlace de pago

Postman: solicitud POST a workflows/endpoints/get-payment-link con cuerpo orderId 15, respuesta "200 OK" con estado waiting y un paymentUrl de PayPal

Envía una solicitud POST a https://<tu-proyecto>.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link, sustituyendo https://<tu-proyecto>.oneentry.cloud por el enlace a tu proyecto.
En el cuerpo de la solicitud, indica el identificador del pedido que creaste antes:

{
    "orderId": 15
}

8.3. Paga el pedido

Página de pago de PayPal por 2,00 US$: método "PayPal balance" seleccionado, botón "Complete Purchase" abajo

8.4. Comprueba el estado del pedido

Sección "Orders", almacenamiento "order storage": el pedido n.º 15 ahora tiene estado "order completed", con un icono de candado en la columna "Actions"

1. Seguimiento del evento de creación de pedido​

1.1. Evento "order created" en el módulo "Events"​

1.2. Seguimiento del evento de creación de pedido​

2. Creación de una sesión de pago​

3. Autenticación en PayPal​

4. Creación del enlace de pago​

5. Actualización de la sesión de pago​

6. Agregar un endpoint para obtener el enlace de pago​

7. Configuración de webhooks para PayPal​

8. Comprobación de la integración​

1. Seguimiento del evento de creación de pedido

1.1. Evento "order created" en el módulo "Events"

1.2. Seguimiento del evento de creación de pedido

2. Creación de una sesión de pago

3. Autenticación en PayPal

4. Creación del enlace de pago

5. Actualización de la sesión de pago

6. Agregar un endpoint para obtener el enlace de pago

7. Configuración de webhooks para PayPal

8. Comprobación de la integración