Pular para o conteúdo principal

Exemplo de Integração com PayPal

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

1. Rastreando o Evento de Criação de Pedido​

1.1. O evento "pedido criado" no módulo "Eventos".​

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

O bloco de Eventos é descrito em detalhes aqui.

1.2. Rastreando o Evento de Criação de Pedido.​

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

Neste exemplo, nos inscrevemos no evento de criação de pedido e salvamos o evento em "msg.orderEvent" para uso futuro.

Mais detalhes sobre o nó de Eventos podem ser encontrados aqui.

2. Criando uma Sessão de Pagamento​

2.1. Criar uma Conta de Pagamento

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

Instruções sobre como fazer isso estão descritas aqui.

2.2. Criar uma Sessão de Pagamento

  • Arraste o nó "admin-api" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione o método "Criando uma sessão de pagamento" e insira o código da descrição abaixo no campo "Request body".
{
  "orderId": {{orderEvent.order.id}},
  "type": "session"
}

Aqui, extraímos o ID do pedido do objeto "msg.orderEvent" e formamos uma solicitação para criar uma sessão de pagamento. A solicitação de criação da sessão leva os parâmetros: "orderId" - o identificador e "type" - o tipo de sessão de pagamento (session ou intent).

Mais detalhes sobre o nó admin-api podem ser encontrados aqui.

2.3. Definir o Identificador Recebido em msg.paymentSessionId

  • Arraste o nó "function" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Insira o código do exemplo no campo "Function".

Aqui, definimos o ID da sessão de pagamento obtido do nó anterior em "msg.paymentSessionId".

msg.paymentSessionId = msg.payload.id

return msg

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

3. Autenticação com PayPal​

3.1. Definir Parâmetros para Autenticação com PayPal

  • Arraste o nó "function" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Insira o código do exemplo no campo "Function".

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

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

return msg

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

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

3.2. Solicitação de Token de Acesso

  • Arraste o nó "http request" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione "POST" no campo Método.
  • Selecione "Enviar como corpo da solicitação" no campo Dados.
  • Insira o link https://api-m.sandbox.paypal.com/v1/oauth2/token no campo Link.
  • Selecione "Objeto JSON" no campo Retorno.
  • Escolha "Usar Autenticação".
  • Insira seu ID de cliente no campo "Username" e seu segredo de cliente do PayPal no campo "Password".

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

Mais sobre autenticação pode ser encontrado na documentação do PayPal.

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

3.3. Definir Parâmetros para Criar um Link de Pagamento

  • Arraste o nó "function" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Insira o código do exemplo no campo "Function".

Neste exemplo, formamos 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 do pedido corresponde ao pedido da API de pedidos https://oneentry.cloud/instructions/api
const order = msg.orderEvent.order
// ID da sessão de pagamento, obtido no nó "criar sessão de pagamento"
const paymentSessionId = msg.paymentSessionId

// formar dados para 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, o nó "http request" é usado. Ele pode ser utilizado para fazer solicitações HTTP.

  • Arraste o nó "http request" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione "POST" no campo Método.
  • Selecione "Enviar como corpo da solicitação" no campo Dados.
  • Insira o link https://api-m.sandbox.paypal.com/v2/checkout/orders no campo Link.
  • Selecione "Objeto JSON" no campo Retorno.

Neste exemplo, fizemos uma solicitação ao PayPal para gerar um link de pagamento com 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ó "admin-api" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione o método "Atualização da sessão de pagamento".
  • Insira o código da descrição abaixo no campo "Query parameters".
{
  "id": {{paymentSessionId}}
}
  • Insira o código da descrição abaixo no campo "Request body".
{
  "paymentUrl": "{{{payload.links.1.href}}}"
}

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

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

Mais detalhes sobre o nó admin-api podem ser encontrados aqui.

6.1. Definir o Tópico "createPaymentLink"

  • Arraste o nó "function" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Insira 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. Criar um Endpoint para Recuperar o Link de Pagamento

  • Arraste o nó "http in" para o espaço de trabalho.
  • Selecione "POST" como método.
  • Insira o link /get-payment-link.

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

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

6.3. Definir o Tópico "getPaymentLink"

  • Arraste o nó "function" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Insira 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. Salvar Dados no Contexto

  • Arraste o nó "function" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Insira 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 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 no contexto
flow.set(contextKey, contextData)
// se createPaymentLink e getPaymentLink concluídos, enviar 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 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 o espaço 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 PayPal

  • Arraste o nó "http in" para o espaço de trabalho.
  • Selecione "POST" como método.
  • Insira o link /paypal.

Este endpoint será necessário para atualizar o status do pagamento via PayPal.

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

7.2. Resposta à Solicitação

  • Arraste o nó "function" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Insira 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 PayPal

  • Arraste o nó "http response" para o espaço 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 o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Insira o código do exemplo no campo "Function".

Neste nó, pegamos o valor obtido do nó "paypal webhook" e escrevemos 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 o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Em "Property", escreva o valor "status".
  • Adicione a primeira regra de verificação. Selecione a condição "==", e 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 especificadas. Se o valor for "APPROVED", os nós do primeiro ramo serão executados; caso contrário, os do segundo ramo serão executados.

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

7.6. Obtendo o ID da Sessão de Pagamento

  • Arraste o nó "function" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Insira o código do exemplo no campo "Function".

Neste nó, pegamos o ID da sessão de pagamento que salvamos no nó "definir dados de pagamento".

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

return msg

Mais 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ó "admin-api" para o espaço de trabalho e conecte-o ao nó da etapa anterior.
  • Selecione o método "Atualização da sessão de pagamento".
  • Insira o código da descrição abaixo no campo "Query parameters".
{
    "id": {{paymentSessionId}}
}
  • Insira o código da descrição abaixo no campo "Request body".
{
    "status": "completed"
}

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

Mais detalhes sobre o nó admin-api podem ser encontrados aqui.

7. Adicione um Webhook na Sua Conta do PayPal​

O link para o 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. Testando a Integração​

8.1. Criar um Pedido

IMG1

IMG2

Instruções sobre como criar um pedido estão descritas na documentação da API.

8.2. Obter o Link de Pagamento

IMG3

  • Faça 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, especifique o ID do pedido criado anteriormente:

{
    "orderId": 15
}

8.3. Pagar pelo Pedido

IMG4

8.4. Verificar o Status do Pedido

IMG5.