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. Evento "order created" no módulo "Events".​

Para rastrear eventos no módulo "Integrations", crie um evento no módulo "Events".

O bloco Events é descrito em detalhes 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 o evento criado "order created" na lista 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.

Você pode saber mais sobre o nó Events 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ó "admin-api" para a área de trabalho e conecte-o ao nó do passo anterior.
  • Selecione o método "Creating a payment session" e cole o código da descrição abaixo no campo "Request body".
{
  "orderId": {{orderEvent.order.id}},
  "type": "session"
}

Aqui, estamos extraindo o identificador do pedido do objeto "msg.orderEvent" e formando a 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 da sessão de pagamento (session ou intent).

Você pode saber mais sobre o nó admin-api aqui.

2.3. Defina o identificador obtido em msg.paymentSessionId

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó do passo 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

Você pode saber mais sobre o nó Function 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ó do passo anterior.
  • Cole o código do exemplo no campo "Function".

Aqui, estamos definindo os 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 de pagamento podem ser encontrados na documentação do PayPal.

Você pode saber mais sobre o nó Function aqui.

3.2. Solicitação para obter o access token

  • Arraste o nó "http request" para a área de trabalho e conecte-o ao nó do passo 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.

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

Mais informações sobre autenticação podem ser encontradas na documentação do PayPal.

Você pode saber mais sobre o nó http request 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ó do passo 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 o PayPal, obtido no nó "paypal auth"
const accessToken = msg.payload.access_token
// dados do pedido, obtidos no nó "order created"
// 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ó "create payment session"
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 informações podem ser encontradas na documentação do PayPal.

Você pode saber mais sobre o nó Function 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ó do passo 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 informações podem ser encontradas na documentação do PayPal.

Você pode saber mais sobre o nó http request aqui.

5. Atualizando a sessão de pagamento​

  • Arraste o nó "admin-api" para a área de trabalho e conecte-o ao nó do passo anterior.
  • Selecione o método "Payment session update".
  • Cole o código da descrição abaixo no campo "Query parameters".
{
  "id": {{paymentSessionId}}
}
  • Cole o código da descrição abaixo no campo "Request body".
{
  "paymentUrl": "{{{payload.links.1.href}}}"
}

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.

Mais informações sobre os valores retornados podem ser encontradas na documentação do PayPal.

Você pode saber mais sobre o nó admin-api aqui.

6.1. Defina o tópico "createPaymentLink"

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

Isso é necessário para identificar o fluxo atual.

msg.topic = 'createPaymentLink'

return msg

Você pode saber mais sobre o nó Function 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.

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

Você pode saber mais sobre o nó http in aqui.

6.3. Defina o tópico "getPaymentLink"

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

Isso é necessário para identificar o fluxo atual.

msg.topic = 'getPaymentLink'

return msg

Você pode saber mais sobre o nó Function aqui.

6.4. Salve os dados no contexto

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó do passo 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 OneEntry
const api = global.get('api')
// dados do contexto atual
const contextData = flow.get(contextKey) || {}
// definir dados no contexto pelo 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, 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 a API
    flow.set(contextKey, null)

    return msg
}

return null

Você pode saber mais sobre o nó Function 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ó do passo anterior.

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

Você pode saber mais sobre o nó http response aqui.

7. Configurando webhooks para o 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.

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

Você pode saber mais sobre o nó http in aqui.

7.2. Resposta à solicitação

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

Isso é necessário para formar a resposta.

msg.payload = {
    ok: true,
}

return msg

Você pode saber mais sobre o nó function 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ó do passo anterior.

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

Você pode saber mais sobre o nó http response aqui.

7.4. Obtendo o status do pagamento

  • Arraste o nó "function" para a área de trabalho e conecte-o ao nó do passo 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

Você pode saber mais sobre o nó Function aqui.

7.5. Verificando o status do pagamento

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

Esse 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.

Você pode saber mais sobre o nó switch 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ó do passo 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 informações sobre os valores retornados podem ser encontradas na documentação do PayPal.

Você pode saber mais sobre o nó Function aqui.

7.7. Atualizando o status do pagamento

  • Arraste o nó "admin-api" para a área de trabalho e conecte-o ao nó do passo anterior.
  • Selecione o método "Payment session update".
  • Cole o código da descrição abaixo no campo "Query parameters".
{
    "id": {{paymentSessionId}}
}
  • Cole o código da descrição abaixo no campo "Request body".
{
    "status": "completed"
}

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

Você pode saber mais sobre o nó admin-api aqui.

7.8. Adicione o webhook no painel do PayPal

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

Exemplo:

https://<seu-projeto>.oneentry.cloud/api/admin/workflows/endpoints/paypal

Mais informações podem ser encontradas 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://<seu-projeto>.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link, substituindo https://<seu-projeto>.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