Exemplo de integração com PayPal

Este tutorial mostra como integrar o PayPal e apresenta 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 do campo "Set" para "orderEvent".
O evento será salvo no objeto "msg.orderEvent" e poderá ser usado em outros nós.
Selecione na lista o evento "order created" que você criou e clique em "submit".

Neste exemplo, assinamos o evento de criação de pedido e salvamos o evento em "msg.orderEvent" para uso posterior.

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

Veja como fazer isso 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 abaixo no campo "Request body".

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

Aqui, extraímos o identificador do pedido do objeto "msg.orderEvent" e montamos a solicitação de criação da sessão de pagamento. Essa solicitação recebe os parâmetros "orderId" (identificador) e "type" (tipo da sessão de pagamento: session ou intent).

Saiba 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, gravamos em "msg.paymentSessionId" o identificador da sessão de pagamento retornado pelo nó anterior.

msg.paymentSessionId = msg.payload.id

return msg

Saiba mais sobre o nó Function aqui.

3. Autenticação no PayPal

3.1. Defina os parâmetros de 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, definimos os valores dos campos "payload" e "headers" do objeto "msg". O próximo nó precisa desses valores para ser executado.

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

return msg

Saiba mais sobre os parâmetros de pagamento na documentação do PayPal.

Saiba mais sobre o nó Function aqui.

3.2. Solicitação do access token

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

Essa solicitação é usada para obter o "access_token".

Saiba mais sobre autenticação na documentação do PayPal.

Saiba 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, montamos a solicitação de criação do link de pagamento com os dados dos nós anteriores.

// access_token do 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 orders api 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

// montamos os dados para o PayPal com base nos dados do pedido
const items = order.products.map((product) => {
    return {
        name: product.title,
        description: 'your description',
        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',
            },
        },
    },
}

// 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

Saiba mais na documentação do PayPal.

Saiba mais sobre o nó Function aqui.

4. Criando um link de pagamento

Neste exemplo, usamos o nó "http request", que serve para fazer solicitações HTTP.

Arraste o nó "http request" para a área de trabalho e conecte-o ao nó do passo anterior.
No campo Method, selecione "POST".
No campo Data, selecione "Send as request body".
No campo Link, cole https://api-m.sandbox.paypal.com/v2/checkout/orders.
No campo Return, selecione "Object JSON".

Neste exemplo, solicitamos ao PayPal um link de pagamento com os dados do nó anterior.

Saiba mais na documentação do PayPal.

Saiba 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 abaixo no campo "Query parameters".

{
  "id": {{paymentSessionId}}
}

Cole o código abaixo no campo "Request body".

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

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

Saiba mais sobre os valores retornados na documentação do PayPal.

Saiba mais sobre o nó admin-api aqui.

6. Adicionando um endpoint para obter o link de pagamento

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

Saiba 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á usado para obter o link de pagamento atual.

Saiba 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

Saiba 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 montar 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) || {}
// gravar dados no contexto de acordo com o tópico
if (msg.topic === 'createPaymentLink') {
    contextData.paymentSessionId = msg.paymentSessionId
    contextData.createPaymentLinkCompleted = true
}
if (msg.topic === 'getPaymentLink') {
    contextData.getPaymentLinkCompleted = true
    contextData.res = msg.res
}
// salvar os dados no contexto
flow.set(contextKey, contextData)
// se createPaymentLink e getPaymentLink tiverem sido concluídos, enviar a resposta com a sessão atual
if (
    contextData.createPaymentLinkCompleted &&
    contextData.getPaymentLinkCompleted
) {
    // obter a sessão de pagamento pelo id via 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

Saiba mais sobre o nó Function aqui.

6.5. Ponto de saída do 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.

Saiba 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á usado para atualizar o status do pagamento pelo PayPal.

Saiba 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 montar a resposta.

msg.payload = {
    ok: true,
}

return msg

Saiba 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ó envia a resposta à solicitação.

Saiba 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 recebido do nó "paypal webhook" e o gravamos em "msg.status" para usá-lo no próximo nó.

msg.status = msg.payload.resource.status

return msg

Saiba 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.
Em "Property", insira 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ó verifica se o valor de "msg.status" corresponde às regras definidas. Se o valor for "APPROVED", são executados os nós do primeiro ramo; caso contrário, os do segundo.

Saiba 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

Saiba mais sobre os valores retornados na documentação do PayPal.

Saiba 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 abaixo no campo "Query parameters".

{
    "id": {{paymentSessionId}}
}

Cole o código abaixo no campo "Request body".

{
    "status": "completed"
}

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

Saiba mais sobre o nó admin-api aqui.

7.8. Adicione o webhook no painel do PayPal

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

Exemplo:

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

Saiba mais na documentação do PayPal.

8. Verificando a integração

8.1. Crie um pedido

Postman: requisição POST para orders-storage/marker/order_storage/orders com os cabeçalhos Authorization e x-app-token, resposta "201 Created" com o pedido id 15

Seção "Orders", armazenamento "order storage": pedido nº 15 de 2.00 usd, pagamento Paypal, status "order created"

A criação de pedidos é descrita na documentação da API.

8.2. Obtenha o link de pagamento

Postman: requisição POST para workflows/endpoints/get-payment-link com corpo orderId 15, resposta "200 OK" com status waiting e um paymentUrl do PayPal

Envie 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, informe o identificador do pedido criado anteriormente:

{
    "orderId": 15
}

8.3. Pague o pedido

Página de pagamento do PayPal de US$ 2,00: método "PayPal balance" selecionado, botão "Complete Purchase" na parte inferior

8.4. Verifique o status do pedido

Seção "Orders", armazenamento "order storage": o pedido nº 15 agora tem status "order completed", com um ícone de cadeado na coluna "Actions"

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

1.1. Evento "order created" no módulo "Events".​

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

2. Criando uma sessão de pagamento​

3. Autenticação no PayPal​

4. Criando um link de pagamento​

5. Atualizando a sessão de pagamento​

6. Adicionando um endpoint para obter o link de pagamento​

7. Configurando webhooks para o PayPal​

8. Verificando a integração​

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

1.1. Evento "order created" no módulo "Events".

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

2. Criando uma sessão de pagamento

3. Autenticação no PayPal

4. Criando um link de pagamento

5. Atualizando a sessão de pagamento

6. Adicionando um endpoint para obter o link de pagamento

7. Configurando webhooks para o PayPal

8. Verificando a integração