PayPal-мен интеграция мысалы

Бұл оқыту сабағында біз PayPal-мен интеграция жасауды көрсетеміз және жаңа нодаларды қарастырамыз.

1. Тапсырыс жасау оқиғасын бақылау

1.1. "Events" модуліндегі "order created" оқиғасы.

"Integrations" модулінде оқиғаларды бақылау үшін "Events" модулінде оқиға жасаңыз.

Events блогы туралы толық ақпаратты осында таба аласыз.

1.2. Тапсырыс жасау оқиғасын бақылау.

"events" нодасын жұмыс алаңына апарыңыз.
"Set" өрісіндегі мәнді "orderEvent" етіп өзгертіңіз.
Оқиға "msg.orderEvent" объектісінде сақталады және оны басқа нодаларда пайдалануға болады.
Тізімнен "order created" жасалған оқиғаны таңдаңыз және "submit" батырмасын басыңыз.

Бұл мысалда біз тапсырыс жасау оқиғасына жазыламыз және оқиғаны "msg.orderEvent" ішінде сақтаймыз, кейінірек пайдалану үшін.

Events нодасы туралы толық ақпаратты осында таба аласыз.

2. Төлем сессиясын жасау

2.1. Төлем аккаунтын жасаңыз

Интеграцияны бастамас бұрын PayPal үшін кастомды аккаунт жасаңыз.

Оны қалай жасау керектігі туралы ақпаратты осында таба аласыз.

2.2. Төлем сессиясын жасаңыз

"api" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Create Payment Session" әдісін таңдаңыз және төмендегі сипаттамадан кодты "Data" өрісіне қойыңыз.

Мұнда біз "msg.orderEvent" объектісінен тапсырыс идентификаторын шығарып, төлем сессиясын жасауға сұраныс құрамыз. Сессияны жасауға арналған сұраныс "orderId" - идентификатор және "type" - төлем сессиясының түрі (session немесе intent) параметрлерін қабылдайды.

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

API нодасы туралы толық ақпаратты осында таба аласыз.

2.3. Алынған идентификаторды msg.paymentSessionId-ға орнатыңыз

"function" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Function" өрісіне мысалдағы кодты қойыңыз.

Мұнда біз "msg.paymentSessionId" ішіне алдыңғы ноданың орындалу нәтижесінде алынған төлем сессиясының идентификаторын орнатамыз.

msg.paymentSessionId = msg.payload.id;

return msg;

Function нодасы туралы толық ақпаратты осында таба аласыз.

3. PayPal-да аутентификация

3.1. PayPal-да аутентификация параметрлерін орнатыңыз

"function" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Function" өрісіне мысалдағы кодты қойыңыз.

Мұнда біз "msg" объектісіндегі "payload" және "headers" өрістеріне мән орнатамыз. Бұл мәндер келесі ноданы орындау үшін қажет.

// сұраныс денесін орнатамыз
msg.payload = {
  grant_type: 'client_credentials'
};
// заголовкаларды орнатамыз
msg.headers = {
  'Content-Type': 'application/x-www-form-urlencoded',
  'Accept': 'application/json'
}

return msg;

Төлем параметрлері туралы толық ақпаратты PayPal құжаттамасынан таба аласыз.

Function нодасы туралы толық ақпаратты осында таба аласыз.

3.2. Access token алу үшін сұраныс

"http request" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Method" өрісінде "POST" опциясын таңдаңыз.
"Data" өрісінде "Send as request body" опциясын таңдаңыз.
"Link" өрісіне https://api-m.sandbox.paypal.com/v1/oauth2/token сілтемесін қойыңыз.
"Return" өрісінде "Object JSON" опциясын таңдаңыз.
"Use Authentication" опциясын таңдаңыз.
"Username" өрісіне клиент ID-ні, ал "Password" өрісіне PayPal үшін клиент секретін енгізіңіз.

Бұл сұраныс "access_token" алу үшін қажет.

Аутентификация туралы толық ақпаратты PayPal құжаттамасынан таба аласыз.

http request нодасы туралы толық ақпаратты осында таба аласыз.

3.3. Төлем сілтемесін жасау параметрлерін орнатыңыз

"function" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Function" өрісіне мысалдағы кодты қойыңыз.

Бұл мысалда біз алдыңғы нодалардан алынған деректер негізінде төлем сілтемесін жасауға сұраныс құрамыз.

// PayPal үшін access_token, "paypal auth" нодасында алынған
const accessToken = msg.payload.access_token;
// тапсырыс деректері, "order created" нодасында алынған
// order объектісі orders api https://oneentry.cloud/instructions/api-ға сәйкес келеді
const order = msg.orderEvent.order;
// төлем сессиясының идентификаторы, "create payment session" нодасында алынған
const paymentSessionId = msg.paymentSessionId;

// тапсырыс деректеріне негізделген PayPal үшін деректерді құрамыз
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",
      },
    },
  },
}

// Сұраныс денесі
msg.payload = data;
// Сұраныс заголовктары
msg.headers = {
  'Content-Type': 'application/json',
  'Authorization': `Bearer ${accessToken}`,
  'Prefer': 'return=representation',
};

return msg;

Толығырақ ақпаратты PayPal құжаттамасынан таба аласыз.

Function нодасы туралы толық ақпаратты осында таба аласыз.

4. Төлем сілтемесін жасау

Бұл мысалда "http request" нодасы қолданылады. Оны http сұраныстарын жасау үшін пайдалануға болады.

"http request" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Method" өрісінде "POST" опциясын таңдаңыз.
"Data" өрісінде "Send as request body" опциясын таңдаңыз.
"Link" өрісіне https://api-m.sandbox.paypal.com/v2/checkout/orders сілтемесін қойыңыз.
"Return" өрісінде "Object JSON" опциясын таңдаңыз.

Бұл мысалда біз PayPal-ға алдыңғы нодадан алынған деректермен төлем сілтемесін жасау үшін сұраныс жасадық.

Толығырақ ақпаратты PayPal құжаттамасынан таба аласыз.

http request нодасы туралы толық ақпаратты осында таба аласыз.

5. Төлем сессиясын жаңарту

"api" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Update Payment Session" әдісін таңдаңыз және төмендегі сипаттамадан кодты "Data" өрісіне қойыңыз.

Мұнда біз "msg.paymentSessionId" төлем сілтемесінің идентификаторын және "msg.payload.links[0].href" төлем сілтемесін алдыңғы сұраныстардан шығарамыз.

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

Қайтарылатын мәндер туралы толық ақпаратты PayPal құжаттамасынан таба аласыз.

API нодасы туралы толық ақпаратты осында таба аласыз.

6. Төлем сілтемесін алу үшін endpoint қосу

6.1. "createPaymentLink" тақырыбын орнатыңыз

"function" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Function" өрісіне мысалдағы кодты қойыңыз.

Бұл ағымдағы ағынды идентификациялау үшін қажет.

msg.topic = 'createPaymentLink';

return msg;

Function нодасы туралы толық ақпаратты осында таба аласыз.

6.2. Төлем сілтемесін алу үшін endpoint жасаңыз

"http in" нодасын жұмыс алаңына апарыңыз.
"POST" әдісін таңдаңыз.
/get-payment-link сілтемесін енгізіңіз.

Бұл endpoint төлем сілтемесін алу үшін қажет.

http in нодасы туралы толық ақпаратты осында таба аласыз.

6.3. "getPaymentLink" тақырыбын орнатыңыз

"function" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Function" өрісіне мысалдағы кодты қойыңыз.

Бұл ағымдағы ағынды идентификациялау үшін қажет.

msg.topic = 'getPaymentLink';

return msg;

Function нодасы туралы толық ақпаратты осында таба аласыз.

6.4. Деректерді контексте сақтау

"function" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Function" өрісіне мысалдағы кодты қойыңыз.

Бұл жауапты қалыптастыру үшін қажет.

// ағымдағы тапсырыс идентификаторын алу
const orderId = msg.payload.orderId;
// ағымдағы контекст кілті
const contextKey = `payment_link_${orderId}`;
// OneEntry api алу
const api = global.get('api');
// ағымдағы контекст деректері
const contextData = flow.get(contextKey) || {};
// тақырып бойынша контекске деректерді орнату
if (msg.topic === 'createPaymentLink') {
    contextData.paymentSessionId = msg.paymentSessionId;
    contextData.createPaymentLinkCompleted = true;
}
if (msg.topic === 'getPaymentLink') {
    contextData.getPaymentLinkCompleted = true;
    contextData.res = msg.res;
}
// контекст деректерін контекске орнату
flow.set(contextKey, contextData);
// createPaymentLink және getPaymentLink аяқталған жағдайда, ағымдағы сессиямен жауап жіберу
if (contextData.createPaymentLinkCompleted && contextData.getPaymentLinkCompleted) {
  // api-дан идентификатор бойынша төлем сессиясын алу
  const paymentSession = await api.getPaymentSessionById({ id: contextData.paymentSessionId });
  msg.payload = paymentSession;
  msg.res = contextData.res;

  // api-ны тазалау
  flow.set(contextKey, null);

  return msg;
}

return null;

Function нодасы туралы толық ақпаратты осында таба аласыз.

6.5. Төлем сілтемесіне жауап беру

"http response" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.

Бұл сұранысқа жауап беру үшін қажет.

http response нодасы туралы толық ақпаратты осында таба аласыз.

7. PayPal үшін вебхуктарды орнату

7.1. PayPal үшін кіріс нүктелері

"http in" нодасын жұмыс алаңына апарыңыз.
"POST" әдісін таңдаңыз.
/paypal сілтемесін енгізіңіз.

Бұл endpoint PayPal арқылы төлем статусын жаңарту үшін қажет.

http in нодасы туралы толық ақпаратты осында таба аласыз.

7.2. Сұранысқа жауап

"function" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Function" өрісіне мысалдағы кодты қойыңыз.

Бұл жауапты қалыптастыру үшін қажет.

msg.payload = {
  ok: true
}

return msg;

Function нодасы туралы толық ақпаратты осында таба аласыз.

7.3. PayPal үшін шығу нүктесі

"http response" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.

Бұл нода сұранысқа жауап беру үшін қажет.

http response нодасы туралы толық ақпаратты осында таба аласыз.

7.4. Төлем статусын алу

"function" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Function" өрісіне мысалдағы кодты қойыңыз.

Бұл нодада біз "paypal webhook" нодасынан алынған мәнді "msg.status" ішіне жазамыз, кейінгі нодада пайдалану үшін.

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

return msg;

Function нодасы туралы толық ақпаратты осында таба аласыз.

7.5. Төлем статусын тексеру

"swith" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Property" өрісіне "status" мәнін жазыңыз.
Тексеру үшін бірінші ереже қосыңыз. "==" шартын таңдаңыз, мәнге "APPROVED" жазыңыз.
Тексеру үшін екінші ереже қосыңыз. "else" шартын таңдаңыз.

Бұл нода "msg.status" ішіндегі мәнді берілген ережелерге сәйкестігін тексереді. Егер мән "APPROVED" болса, бірінші тармақтың нодалары орындалады, әйтпесе екінші тармақтың нодалары орындалады.

switch нодасы туралы толық ақпаратты осында таба аласыз.

7.6. Төлем сессиясының идентификаторын алу

"function" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Function" өрісіне мысалдағы кодты қойыңыз.

Бұл нодада біз "set payment data" нодасында сақталған төлем сессиясының идентификаторын аламыз.

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

return msg;

Қайтарылатын мәндер туралы толық ақпаратты PayPal құжаттамасынан таба аласыз.

Function нодасы туралы толық ақпаратты осында таба аласыз.

7.7. Төлем статусын жаңарту

"api" нодасын жұмыс алаңына апарыңыз және алдыңғы қадамдағы нодамен қосыңыз.
"Update Payment Session" әдісін таңдаңыз және төмендегі сипаттамадан кодты "Data" өрісіне қойыңыз.

Мұнда біз "msg.paymentSessionId" ішіндегі төлем сессиясының идентификаторын жаңартамыз.

{
  "id": {{paymentSessionId}},
  "status": "completed"
}

api нодасы туралы толық ақпаратты осында таба аласыз.

7. PayPal-да вебхук қосыңыз

Сіздің жобаңыздың сілтемесі + /api/admin/workflows/endpoints/paypal

Мысал:

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

Толығырақ ақпаратты PayPal құжаттамасынан таба аласыз.

8. Интеграцияны тексеру

8.1. Тапсырыс жасаңыз

Тапсырыс жасауды API құжаттамасынан таба аласыз.

8.2. Төлем сілтемесін алыңыз

https://integrations-study.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link сілтемесіне POST сұранысын орындаңыз, https://integrations-study.oneentry.cloud орнына жобаңыздың сілтемесін қойыңыз.
Сұраныс денесінде бұрын жасалған тапсырыстың идентификаторын көрсетіңіз:

{
  "orderId": 15
}

8.3. Тапсырысты төлеңіз

8.4. Тапсырыс статусын тексеріңіз

PayPal-мен интеграция мысалы

1. Тапсырыс жасау оқиғасын бақылау​

1.1. "Events" модуліндегі "order created" оқиғасы.​

1.2. Тапсырыс жасау оқиғасын бақылау.​

2. Төлем сессиясын жасау​

3. PayPal-да аутентификация​

4. Төлем сілтемесін жасау​

5. Төлем сессиясын жаңарту​

6. Төлем сілтемесін алу үшін endpoint қосу​

7. PayPal үшін вебхуктарды орнату​

7. PayPal-да вебхук қосыңыз​

8. Интеграцияны тексеру​

1. Тапсырыс жасау оқиғасын бақылау

1.1. "Events" модуліндегі "order created" оқиғасы.

1.2. Тапсырыс жасау оқиғасын бақылау.

2. Төлем сессиясын жасау

3. PayPal-да аутентификация

4. Төлем сілтемесін жасау

5. Төлем сессиясын жаңарту

6. Төлем сілтемесін алу үшін endpoint қосу

7. PayPal үшін вебхуктарды орнату

7. PayPal-да вебхук қосыңыз

8. Интеграцияны тексеру