Pular para o conteúdo principal

Exemplo de integração com PayPal

Neste tutorial, vamos mostrar como integrar o PayPal e discutir novos nós.

1. Rastreando o evento de criação de pedido​

1.1. Evento "pedido criado" no módulo "Eventos".​

Para rastrear eventos no módulo "Integrações", crie um evento no módulo "Eventos".

Os detalhes do bloco Events estão descritos aqui.

1.2. Rastreando o evento de criação de pedido.​

  • Arraste o nó "events" para a área de trabalho.
  • Altere o valor no campo "Set" para "orderEvent".
  • O evento será salvo no objeto "msg.orderEvent" e poderá ser usado em outros nós.
  • Selecione da lista o evento criado "pedido criado" e clique em "submit".

Neste exemplo, estamos nos inscrevendo no evento de criação de pedido e salvando o evento em "msg.orderEvent" para uso posterior.

Mais detalhes sobre o nó Events podem ser encontrados aqui.

2. Criando uma sessão de pagamento​

2.1. Crie uma conta de pagamento

Antes de começar a integração, crie uma conta personalizada para o PayPal.

Como fazer isso está descrito aqui.

2.2. Crie uma sessão de pagamento

  • Arraste o nó "api" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione o método "Create Payment Session" e cole o código da descrição abaixo no campo "Data".

Aqui, estamos extraindo o identificador do pedido do objeto "msg.orderEvent" e formando uma solicitação para criar uma sessão de pagamento. A solicitação para criar a sessão aceita os parâmetros: "orderId" - identificador e "type" - tipo de sessão de pagamento (session ou intent).

{
  "orderId": {{orderEvent.order.id}},
  "type": "session"
}
Mais detalhes sobre o nó API podem ser encontrados aqui.

2.3. Defina o identificador obtido em msg.paymentSessionId

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Cole o código do exemplo no campo "Function".

Aqui, estamos definindo em "msg.paymentSessionId" o identificador da sessão de pagamento obtido como resultado da execução do nó anterior.

msg.paymentSessionId = msg.payload.id;

return msg;
Mais detalhes sobre o nó Function podem ser encontrados aqui.

3. Autenticação no PayPal​

3.1. Defina os parâmetros para autenticação no PayPal

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Cole o código do exemplo no campo "Function".

Aqui, estamos definindo valores nos campos "payload" e "headers" do objeto "msg". Esses valores são necessários para a execução do próximo nó.

// definindo o corpo da solicitação
msg.payload = {
  grant_type: 'client_credentials'
};
// definindo os cabeçalhos
msg.headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

return msg;

Mais detalhes sobre os parâmetros para pagamento podem ser encontrados na documentação do PayPal.

Mais detalhes sobre o nó Function podem ser encontrados aqui.

3.2. Solicitação para obter o token de acesso

  • Arraste o nó "http request" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione a opção "POST" no campo Method.
  • Selecione a opção "Send as request body" no campo Data.
  • Cole o link https://api-m.sandbox.paypal.com/v1/oauth2/token no campo Link.
  • Selecione a opção "Object JSON" no campo Return.
  • Selecione "Use Authentication".
  • No campo "Username", insira seu client ID, e no campo "Password", seu client secret para o PayPal.

Esta solicitação é necessária para obter o "access_token".

Mais detalhes sobre autenticação podem ser encontrados na documentação do PayPal.

Mais detalhes sobre o nó http request podem ser encontrados aqui.

3.3. Defina os parâmetros para criar o link de pagamento

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Cole o código do exemplo no campo "Function".

Neste exemplo, estamos formando uma solicitação para criar um link de pagamento com base nos dados dos nós anteriores.

// access_token para paypal, obtido no nó "paypal auth"
const accessToken = msg.payload.access_token;
// dados do pedido, obtidos no nó "pedido criado"
// o objeto order corresponde ao pedido da API de pedidos https://oneentry.cloud/instructions/api
const order = msg.orderEvent.order;
// identificador da sessão de pagamento, obtido no nó "criar sessão de pagamento"
const paymentSessionId = msg.paymentSessionId;

// formamos os dados para o paypal com base nos dados do pedido
const items = order.products.map(product => {
  return {
    name: product.title,
    description: 'sua descrição',
    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: 'pt-BR',
        landing_page: 'LOGIN',
        shipping_preference: 'NO_SHIPPING',
        user_action: 'PAY_NOW',
        return_url: "https://example.com/return",
        cancel_url: "https://example.com/cancel",
      },
    },
  },
}

// Corpo da solicitação
msg.payload = data;
// Cabeçalhos da solicitação
msg.headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${accessToken}`,
  'Prefer': 'return=representation',
};

return msg;

Mais detalhes podem ser encontrados na documentação do PayPal.

Mais detalhes sobre o nó Function podem ser encontrados aqui.

Neste exemplo, usamos o nó "http request". Ele pode ser usado para fazer solicitações http.

  • Arraste o nó "http request" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione a opção "POST" no campo Method.
  • Selecione a opção "Send as request body" no campo Data.
  • Cole o link https://api-m.sandbox.paypal.com/v2/checkout/orders no campo Link.
  • Selecione a opção "Object JSON" no campo Return.

Neste exemplo, fizemos uma solicitação ao PayPal para gerar um link de pagamento com os dados do nó anterior.

Mais detalhes podem ser encontrados na documentação do PayPal.

Mais detalhes sobre o nó http request podem ser encontrados aqui.

5. Atualizando a sessão de pagamento​

  • Arraste o nó "api" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione o método "Update Payment Session" e cole o código da descrição abaixo no campo "Data".

Aqui, estamos extraindo o identificador do link de pagamento "msg.paymentSessionId" e o link de pagamento "msg.payload.links[0].href" das solicitações anteriores.

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

Mais detalhes sobre os valores retornados podem ser encontrados na documentação do PayPal.

Mais detalhes sobre o nó API podem ser encontrados aqui.

6.1. Defina o tópico "createPaymentLink"

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Cole o código do exemplo no campo "Function".

Isso é necessário para identificar o fluxo atual.

msg.topic = 'createPaymentLink';

return msg;
Mais detalhes sobre o nó Function podem ser encontrados aqui.

6.2. Crie um endpoint para obter o link de pagamento

  • Arraste o nó "http in" para a área de trabalho.
  • Selecione o método "POST".
  • Digite o link /get-payment-link.

Este endpoint será necessário para obter o link de pagamento atual.

Mais detalhes sobre o nó http in podem ser encontrados aqui.

6.3. Defina o tópico "getPaymentLink"

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Cole o código do exemplo no campo "Function".

Isso é necessário para identificar o fluxo atual.

msg.topic = 'getPaymentLink';

return msg;
Mais detalhes sobre o nó Function podem ser encontrados aqui.

6.4. Salve os dados no contexto

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Cole o código do exemplo no campo "Function".

Isso é necessário para formar a resposta.

// obter o id do pedido atual
const orderId = msg.payload.orderId;
// chave do contexto atual
const contextKey = `payment_link_${orderId}`;
// obter a API do OneEntry
const api = global.get('api');
// dados do contexto atual
const contextData = flow.get(contextKey) || {};
// definir dados no 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;
}
// definir dados do contexto
flow.set(contextKey, contextData);
// se createPaymentLink e getPaymentLink estiverem completos, envie a resposta com a sessão atual
if (contextData.createPaymentLinkCompleted && contextData.getPaymentLinkCompleted) {
  // obter a sessão de pagamento pelo id da API
  const paymentSession = await api.getPaymentSessionById({ id: contextData.paymentSessionId });
  msg.payload = paymentSession;
  msg.res = contextData.res;

  // limpar a API
  flow.set(contextKey, null);

  return msg;
}

return null;
Mais detalhes sobre o nó Function podem ser encontrados aqui.

6.5. Ponto de saída para o link de pagamento

  • Arraste o nó "http response" para a área de trabalho e conecte-o ao nó da etapa anterior.

Isso é necessário para enviar a resposta à solicitação.

Mais detalhes sobre o nó http response podem ser encontrados aqui.

7. Configurando webhooks para PayPal​

7.1. Ponto de entrada para o PayPal

  • Arraste o nó "http in" para a área de trabalho.
  • Selecione o método "POST".
  • Digite o link /paypal.

Este endpoint será necessário para atualizar o status do pagamento através do PayPal.

Mais detalhes sobre o nó http in podem ser encontrados aqui.

7.2. Resposta à solicitação

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Cole o código do exemplo no campo "Function".

Isso é necessário para formar a resposta.

msg.payload = {
  ok: true
}

return msg;
Mais detalhes sobre o nó function podem ser encontrados aqui.

7.3. Ponto de saída para o PayPal

  • Arraste o nó "http response" para a área de trabalho e conecte-o ao nó da etapa anterior.

Este nó é necessário para enviar a resposta à solicitação.

Mais detalhes sobre o nó http response podem ser encontrados aqui.

7.4. Obtendo o status do pagamento

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Cole o código do exemplo no campo "Function".

Neste nó, pegamos o valor obtido do nó "paypal webhook" e o gravamos em "msg.status" para uso no próximo nó.

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

return msg;
Mais detalhes sobre o nó Function podem ser encontrados aqui.

7.5. Verificando o status do pagamento

  • Arraste o nó "switch" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • No "Property", escreva o valor "status".
  • Adicione a primeira regra de verificação. Selecione a condição "==", insira "APPROVED" como valor.
  • Adicione a segunda regra de verificação. Selecione a condição "else".

Este nó irá verificar o valor de "msg.status" em relação às regras definidas. Se o valor for "APPROVED", os nós do primeiro ramo serão executados; caso contrário, os do segundo ramo.

Mais detalhes sobre o nó switch podem ser encontrados aqui.

7.6. Obtendo o identificador da sessão de pagamento

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Cole o código do exemplo no campo "Function".

Neste nó, pegamos o identificador da sessão de pagamento que salvamos no nó "set payment data".

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

return msg;

Mais detalhes sobre os valores retornados podem ser encontrados na documentação do PayPal.

Mais detalhes sobre o nó Function podem ser encontrados aqui.

7.7. Atualizando o status do pagamento

  • Arraste o nó "api" para a área de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione o método "Update Payment Session" e cole o código da descrição abaixo no campo "Data".

Aqui, estamos atualizando o status do pagamento pelo seu identificador de "msg.paymentSessionId".

{
  "id": {{paymentSessionId}},
  "status": "completed"
}
Mais detalhes sobre o nó api podem ser encontrados aqui.

7. Adicione o webhook no painel do PayPal​

Link para seu projeto + /api/admin/workflows/endpoints/paypal

Exemplo:

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

Mais detalhes podem ser encontrados na documentação do PayPal.

8. Verificando a integração​

8.1. Crie um pedido

IMG1

IMG2

Como criar um pedido está descrito na documentação da API.

8.2. Obtenha o link de pagamento

IMG3

  • Execute uma solicitação POST para https://integrations-study.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link, substituindo https://integrations-study.oneentry.cloud pelo link do seu projeto.

  • No corpo da solicitação, insira o identificador do pedido criado anteriormente:

{
  "orderId": 15
}

8.3. Pague o pedido

IMG4

8.4. Verifique o status do pedido

IMG5