Ejemplo de Integración con PayPal

En este tutorial, te mostraremos cómo integrar PayPal y explorar nuevos nodos.

1. Seguimiento del Evento de Creación de Pedido

1.1. El evento "pedido creado" en el módulo "Eventos".

Para rastrear eventos en el módulo "Integraciones", crea un evento en el módulo "Eventos".

El bloque de Eventos se describe en detalle aquí.

1.2. Seguimiento del Evento de Creación de Pedido.

• Arrastra el nodo "eventos" al espacio de trabajo.
• Cambia el valor en el campo "Establecer" a "orderEvent".
• El evento se guardará en el objeto "msg.orderEvent" y se podrá usar en otros nodos.
• Selecciona el evento creado "pedido creado" de la lista y haz clic en "enviar".

En este ejemplo, nos suscribimos al evento de creación de pedido y guardamos el evento en "msg.orderEvent" para su uso futuro.

Más detalles sobre el nodo de Eventos se pueden encontrar aquí.

2. Creando una Sesión de Pago

2.1. Crear una Cuenta de Pago

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

Las instrucciones sobre cómo hacer esto se describen aquí.

2.2. Crear una Sesión de Pago

• Arrastra el nodo "admin-api" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Selecciona el método "Creando una sesión de pago" e inserta el código de la descripción a continuación en el campo "Cuerpo de la solicitud".

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

Aquí, extraemos el ID del pedido del objeto "msg.orderEvent" y formamos una solicitud para crear una sesión de pago. La solicitud de creación de sesión toma parámetros: "orderId" - el identificador y "type" - el tipo de sesión de pago (session o intent).

Más detalles sobre el nodo admin-api se pueden encontrar aquí.

2.3. Establecer el Identificador Recibido en msg.paymentSessionId

• Arrastra el nodo "function" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Inserta el código del ejemplo en el campo "Función".

Aquí, establecemos el ID de la sesión de pago obtenido del nodo anterior en "msg.paymentSessionId".

msg.paymentSessionId = msg.payload.id

return msg

Más detalles sobre el nodo Función se pueden encontrar aquí.

3. Autenticación con PayPal

3.1. Establecer Parámetros para la Autenticación con PayPal

• Arrastra el nodo "function" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Inserta el código del ejemplo en el campo "Función".

Aquí, establecemos valores en los campos "payload" y "headers" del objeto "msg". Estos valores son necesarios para el siguiente nodo.

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

return msg

Más sobre los parámetros de pago se pueden encontrar en la documentación de PayPal.

Más detalles sobre el nodo Función se pueden encontrar aquí.

3.2. Solicitud de Token de Acceso

• Arrastra el nodo "http request" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Selecciona "POST" en el campo Método.
• Selecciona "Enviar como cuerpo de solicitud" en el campo Datos.
• Inserta el enlace https://api-m.sandbox.paypal.com/v1/oauth2/token en el campo Enlace.
• Selecciona "Objeto JSON" en el campo Retorno.
• Elige "Usar Autenticación".
• Ingresa tu ID de cliente en el campo "Nombre de usuario" y tu secreto de cliente para PayPal en el campo "Contraseña".

Esta solicitud es necesaria para obtener el "access_token".

Más sobre autenticación se puede encontrar en la documentación de PayPal.

Más detalles sobre el nodo de solicitud http se pueden encontrar aquí.

3.3. Establecer Parámetros para Crear un Enlace de Pago

• Arrastra el nodo "function" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Inserta el código del ejemplo en el campo "Función".

En este ejemplo, formamos una solicitud para crear un enlace de pago basado en datos de los nodos anteriores.

// access_token para paypal, obtenido en el nodo "paypal auth"
const accessToken = msg.payload.access_token
// datos del pedido, obtenidos en el nodo "pedido creado"
// el objeto de pedido corresponde al pedido de la API de pedidos https://oneentry.cloud/instructions/api
const order = msg.orderEvent.order
// ID de la sesión de pago, obtenido en el nodo "crear sesión de pago"
const paymentSessionId = msg.paymentSessionId

// formar datos para paypal basados en datos del pedido
const items = order.products.map((product) => {
    return {
        name: product.title,
        description: 'tu descripción',
        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

Más detalles se pueden encontrar en la documentación de PayPal.

Más detalles sobre el nodo Función se pueden encontrar aquí.

4. Creando un Enlace de Pago

En este ejemplo, se utiliza el nodo "http request". Se puede usar para hacer solicitudes HTTP.

• Arrastra el nodo "http request" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Selecciona "POST" en el campo Método.
• Selecciona "Enviar como cuerpo de solicitud" en el campo Datos.
• Inserta el enlace https://api-m.sandbox.paypal.com/v2/checkout/orders en el campo Enlace.
• Selecciona "Objeto JSON" en el campo Retorno.

En este ejemplo, hicimos una solicitud a PayPal para generar un enlace de pago con datos del nodo anterior.

Más detalles se pueden encontrar en la documentación de PayPal.

Más detalles sobre el nodo de solicitud http se pueden encontrar aquí.

5. Actualizando la Sesión de Pago

• Arrastra el nodo "admin-api" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Selecciona el método "Actualización de sesión de pago".
• Inserta el código de la descripción a continuación en el campo "Parámetros de consulta".

{
  "id": {{paymentSessionId}}
}

• Inserta el código de la descripción a continuación en el campo "Cuerpo de la solicitud".

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

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

Más sobre los valores devueltos se pueden encontrar en la documentación de PayPal.

Más detalles sobre el nodo admin-api se pueden encontrar aquí.

6. Agregando un Endpoint para Recuperar el Enlace de Pago

6.1. Establecer el Tema "createPaymentLink"

• Arrastra el nodo "function" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Inserta el código del ejemplo en el campo "Función".

Esto es necesario para identificar el flujo actual.

msg.topic = 'createPaymentLink'

return msg

Más detalles sobre el nodo Función se pueden encontrar aquí.

6.2. Crear un Endpoint para Recuperar el Enlace de Pago

• Arrastra el nodo "http in" al espacio de trabajo.
• Selecciona "POST" como método.
• Ingresa el enlace /get-payment-link.

Este endpoint será necesario para recuperar el enlace de pago actual.

Más detalles sobre el nodo http in se pueden encontrar aquí.

6.3. Establecer el Tema "getPaymentLink"

• Arrastra el nodo "function" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Inserta el código del ejemplo en el campo "Función".

Esto es necesario para identificar el flujo actual.

msg.topic = 'getPaymentLink'

return msg

Más detalles sobre el nodo Función se pueden encontrar aquí.

6.4. Guardar Datos en el Contexto

• Arrastra el nodo "function" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Inserta el código del ejemplo en el campo "Función".

Esto es necesario 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) || {}
// establecer datos en el contexto por tema
if (msg.topic === 'createPaymentLink') {
    contextData.paymentSessionId = msg.paymentSessionId
    contextData.createPaymentLinkCompleted = true
}
if (msg.topic === 'getPaymentLink') {
    contextData.getPaymentLinkCompleted = true
    contextData.res = msg.res
}
// establecer datos del contexto en el contexto
flow.set(contextKey, contextData)
// si createPaymentLink y getPaymentLink se completaron, enviar respuesta con la sesión actual
if (
    contextData.createPaymentLinkCompleted &&
    contextData.getPaymentLinkCompleted
) {
    // obtener la sesión de pago por id de la api
    const paymentSession = await api.getPaymentSessionById({
        id: contextData.paymentSessionId,
    })
    msg.payload = paymentSession
    msg.res = contextData.res

    // limpiar api
    flow.set(contextKey, null)

    return msg
}

return null

Más detalles sobre el nodo Función se pueden encontrar aquí.

6.5. Punto de Salida para el Enlace de Pago

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

Esto es necesario para enviar la respuesta a la solicitud.

Más detalles sobre el nodo de respuesta http se pueden encontrar aquí.

7. Configurando Webhooks para PayPal

7.1. Punto de Entrada para PayPal

• Arrastra el nodo "http in" al espacio de trabajo.
• Selecciona "POST" como método.
• Ingresa el enlace /paypal.

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

Más detalles sobre el nodo http in se pueden encontrar aquí.

7.2. Respuesta a la Solicitud

• Arrastra el nodo "function" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Inserta el código del ejemplo en el campo "Función".

Esto es necesario para formar la respuesta.

msg.payload = {
    ok: true,
}

return msg

Más detalles sobre el nodo Función se pueden encontrar aquí.

7.3. Punto de Salida para PayPal

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

Este nodo es necesario para enviar la respuesta a la solicitud.

Más detalles sobre el nodo de respuesta http se pueden encontrar aquí.

7.4. Obtener el Estado del Pago

• Arrastra el nodo "function" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Inserta el código del ejemplo en el campo "Función".

En este nodo, tomamos el valor obtenido del nodo "paypal webhook" y lo escribimos en "msg.status" para su uso en el siguiente nodo.

msg.status = msg.payload.resource.status

return msg

Más detalles sobre el nodo Función se pueden encontrar aquí.

7.5. Comprobando el Estado del Pago

• Arrastra el nodo "switch" al espacio de trabajo y conéctalo al nodo del paso anterior.
• En "Propiedad", escribe el valor "status".
• Agrega la primera regla para la comprobación. Selecciona la condición "==", y escribe "APPROVED" como valor.
• Agrega la segunda regla para la comprobación. Selecciona la condición "else".

Este nodo comprobará el valor de "msg.status" contra las reglas especificadas. Si el valor es "APPROVED", se ejecutarán los nodos de la primera rama; de lo contrario, se ejecutarán los de la segunda rama.

Más detalles sobre el nodo switch se pueden encontrar aquí.

7.6. Obtener el ID de la Sesión de Pago

• Arrastra el nodo "function" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Inserta el código del ejemplo en el campo "Función".

En este nodo, tomamos el ID de la sesión de pago que guardamos en el nodo "establecer datos de pago".

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

return msg

Más sobre los valores devueltos se pueden encontrar en la documentación de PayPal.

Más detalles sobre el nodo Función se pueden encontrar aquí.

7.7. Actualizando el Estado del Pago

• Arrastra el nodo "admin-api" al espacio de trabajo y conéctalo al nodo del paso anterior.
• Selecciona el método "Actualización de sesión de pago".
• Inserta el código de la descripción a continuación en el campo "Parámetros de consulta".

{
    "id": {{paymentSessionId}}
}

• Inserta el código de la descripción a continuación en el campo "Cuerpo de la solicitud".

{
    "status": "completed"
}

Aquí, actualizamos el estado del pago por su identificador de "msg.paymentSessionId".

Más detalles sobre el nodo admin-api se pueden encontrar aquí.

7. Agrega un Webhook en Tu Cuenta de PayPal

El enlace a tu proyecto + /api/admin/workflows/endpoints/paypal.

Ejemplo:

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

Más detalles se pueden encontrar en la documentación de PayPal.

8. Probando la Integración

8.1. Crear un Pedido

Las instrucciones sobre cómo crear un pedido se describen en la documentación de la API.

8.2. Obtener el Enlace de Pago

• Realiza una solicitud POST a https://integrations-study.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link, reemplazando https://integrations-study.oneentry.cloud con el enlace a tu proyecto.

• En el cuerpo de la solicitud, especifica el ID del pedido creado anteriormente:

{
    "orderId": 15
}

8.3. Pagar el Pedido

8.4. Comprobar el Estado del Pedido

.