Saltar al contenido principal

Ejemplo de integración con PayPal

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

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

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

Para rastrear eventos en el módulo "Integrations", crea un evento en el módulo "Events".

Se describe en detalle el bloque Events aquí.

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

  • Arrastra el nodo "events" al área de trabajo.
  • Cambia el valor en el campo "Set" a "orderEvent".
  • El evento se guardará en el objeto "msg.orderEvent" y se podrá utilizar en otros nodos.
  • Selecciona de la lista el evento creado "order created" 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 su uso posterior.

Puedes obtener más información sobre el nodo Events aquí.

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

2.1. Crea una cuenta de pago

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

Se describe aquí cómo hacerlo.

2.2. Crea una sesión de pago

  • Arrastra el nodo "api" al área de trabajo y conéctalo con el nodo del paso anterior.
  • Selecciona el método "Create Payment Session" e inserta el código de la descripción a continuación en el campo "Data".

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

{
  "orderId": {{orderEvent.order.id}},
  "type": "session"
}
Puedes obtener más información sobre el nodo API aquí.

2.3. Establece el identificador obtenido en msg.paymentSessionId

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

Aquí establecemos en "msg.paymentSessionId" el identificador de la sesión de pago obtenido como resultado de la ejecución del nodo anterior.

msg.paymentSessionId = msg.payload.id;

return msg;
Puedes obtener más información sobre el nodo Function aquí.

3. Autenticación en PayPal​

3.1. Establece los parámetros para la autenticación en PayPal

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

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

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

return msg;

Puedes obtener más información sobre los parámetros de pago en la documentación de PayPal.

Puedes obtener más información sobre el nodo Function aquí.

3.2. Solicitud para obtener el token de acceso

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

Esta solicitud es necesaria para obtener el "access_token".

Puedes obtener más información sobre la autenticación en la documentación de PayPal.

Puedes obtener más información sobre el nodo http request aquí.

3.3. Establece 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.
  • Inserta el código del ejemplo en el campo "Function".

En este ejemplo, se forma una solicitud para crear un enlace de pago basada en los 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 "order created"
// el objeto order corresponde al pedido de la API de orders 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 basados en los 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;

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

Puedes obtener más información sobre el nodo Function aquí.

4. Creación del enlace de pago​

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

  • Arrastra el nodo "http request" al área de trabajo y conéctalo con el nodo del paso anterior.
  • Selecciona en el campo Method la opción "POST".
  • Selecciona en el campo Data la opción "Send as request body".
  • Inserta en el campo Link el enlace https://api-m.sandbox.paypal.com/v2/checkout/orders.
  • Selecciona en el campo Return la opción "Object JSON".

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

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

Puedes obtener más información sobre el nodo http request aquí.

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

  • Arrastra el nodo "api" al área de trabajo y conéctalo con el nodo del paso anterior.
  • Selecciona el método "Update Payment Session" e inserta el código de la descripción a continuación en el campo "Data".

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

{
  "id": {{paymentSessionId}},
  "paymentUrl": "{{{payload.links.1.href}}}"
}

Puedes obtener más información sobre los valores devueltos en la documentación de PayPal.

Puedes obtener más información sobre el nodo API aquí.

6. Agregar endpoint para obtener el enlace de pago​

6.1. Establece el tópico "createPaymentLink"

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

Esto es necesario para identificar el flujo actual.

msg.topic = 'createPaymentLink';

return msg;
Puedes obtener más información sobre el nodo Function aquí.

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".
  • Ingresa el enlace /get-payment-link.

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

Puedes obtener más información sobre el nodo http in aquí.

6.3. Establece el tópico "getPaymentLink"

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

Esto es necesario para identificar el flujo actual.

msg.topic = 'getPaymentLink';

return msg;
Puedes obtener más información sobre el nodo Function aquí.

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.
  • Inserta el código del ejemplo en el campo "Function".

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 tópico
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 la API
  flow.set(contextKey, null);

  return msg;
}

return null;
Puedes obtener más información sobre el nodo Function aquí.

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.

Esto es necesario para devolver la respuesta a la solicitud.

Puedes obtener más información sobre el nodo http response aquí.

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".
  • Ingresa el enlace /paypal.

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

Puedes obtener más información sobre el nodo http in aquí.

7.2. Respuesta a la solicitud

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

Esto es necesario para formar la respuesta.

msg.payload = {
  ok: true
}

return msg;
Puedes obtener más información sobre el nodo function aquí.

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 es necesario para devolver la respuesta a la solicitud.

Puedes obtener más información sobre el nodo http response aquí.

7.4. Obtener el estado del pago

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

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

msg.status = msg.payload.resource.status;

return msg;
Puedes obtener más información sobre el nodo Function aquí.

7.5. Verificació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 para la verificación. Selecciona la condición "==", en el valor ingresa "APPROVED".
  • Agrega la segunda regla para la verificación. Selecciona la condición "else".

Este nodo verificará el valor de "msg.status" en relación con las reglas establecidas. Si el valor es igual a "APPROVED", se ejecutarán los nodos de la primera rama, de lo contrario, se ejecutarán los de la segunda.

Puedes obtener más información sobre el nodo switch aquí.

7.6. Obtener el identificador de la sesión de pago

  • Arrastra el nodo "function" al área de trabajo y conéctalo con el nodo del paso anterior.
  • Inserta 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;

Puedes obtener más información sobre los valores devueltos en la documentación de PayPal.

Puedes obtener más información sobre el nodo Function aquí.

7.7. Actualización del estado del pago

  • Arrastra el nodo "api" al área de trabajo y conéctalo con el nodo del paso anterior.
  • Selecciona el método "Update Payment Session" e inserta el código de la descripción a continuación en el campo "Data".

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

{
  "id": {{paymentSessionId}},
  "status": "completed"
}
Puedes obtener más información sobre el nodo api aquí.

7. Agrega el webhook en el panel de control de PayPal​

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

Ejemplo:

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

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

8. Verificación de la integración​

8.1. Crea un pedido

IMG1

IMG2

Se describe cómo crear un pedido en la documentación de la API.

8.2. Obtén el enlace de pago

IMG3

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

  • En el cuerpo de la solicitud, indica el identificador del pedido creado anteriormente:

{
  "orderId": 15
}

8.3. Paga el pedido

IMG4

8.4. Verifica el estado del pedido

IMG5