Contoh Integrasi dengan PayPal

Dalam tutorial ini, kami akan menunjukkan cara mengintegrasikan PayPal dan menjelajahi node baru.

1. Melacak Peristiwa Pembuatan Pesanan

1.1. Peristiwa "pesanan dibuat" di modul "Events".

Untuk melacak peristiwa di modul "Integrations", buat peristiwa di modul "Events".

Blok Events dijelaskan secara rinci di sini.

1.2. Melacak Peristiwa Pembuatan Pesanan.

• Seret node "events" ke ruang kerja.
• Ubah nilai di bidang "Set" menjadi "orderEvent".
• Peristiwa akan disimpan dalam objek "msg.orderEvent" dan dapat digunakan di node lain.
• Pilih peristiwa yang dibuat "pesanan dibuat" dari daftar dan klik "submit".

Dalam contoh ini, kami berlangganan pada peristiwa pembuatan pesanan dan menyimpan peristiwa dalam "msg.orderEvent" untuk digunakan di masa mendatang.

Detail lebih lanjut tentang node Events dapat ditemukan di sini.

2. Membuat Sesi Pembayaran

2.1. Buat Akun Pembayaran

Sebelum memulai integrasi, buat akun khusus untuk PayPal.

Instruksi tentang cara melakukan ini dijelaskan di sini.

2.2. Buat Sesi Pembayaran

• Seret node "admin-api" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Pilih metode "Membuat sesi pembayaran" dan masukkan kode dari deskripsi di bawah ini ke dalam bidang "Request body".

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

Di sini, kami mengekstrak ID pesanan dari objek "msg.orderEvent" dan membentuk permintaan untuk membuat sesi pembayaran. Permintaan pembuatan sesi memerlukan parameter: "orderId" - pengidentifikasi dan "type" - jenis sesi pembayaran (session atau intent).

Detail lebih lanjut tentang node admin-api dapat ditemukan di sini.

2.3. Atur Pengidentifikasi yang Diterima di msg.paymentSessionId

• Seret node "function" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Masukkan kode dari contoh ke dalam bidang "Function".

Di sini, kami mengatur ID sesi pembayaran yang diperoleh dari node sebelumnya ke dalam "msg.paymentSessionId".

msg.paymentSessionId = msg.payload.id

return msg

Detail lebih lanjut tentang node Function dapat ditemukan di sini.

3. Autentikasi dengan PayPal

3.1. Atur Parameter untuk Autentikasi dengan PayPal

• Seret node "function" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Masukkan kode dari contoh ke dalam bidang "Function".

Di sini, kami mengatur nilai di bidang "payload" dan "headers" dari objek "msg". Nilai-nilai ini diperlukan untuk node berikutnya.

// set the request body
msg.payload = {
    grant_type: 'client_credentials',
}
// set the headers
msg.headers = {
    'Content-Type': 'application/x-www-form-urlencoded',
    Accept: 'application/json',
}

return msg

Lebih lanjut tentang parameter pembayaran dapat ditemukan di dokumentasi PayPal.

Detail lebih lanjut tentang node Function dapat ditemukan di sini.

3.2. Permintaan untuk Token Akses

• Seret node "http request" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Pilih "POST" di bidang Metode.
• Pilih "Kirim sebagai body permintaan" di bidang Data.
• Masukkan tautan https://api-m.sandbox.paypal.com/v1/oauth2/token di bidang Tautan.
• Pilih "Object JSON" di bidang Kembali.
• Pilih "Gunakan Autentikasi".
• Masukkan ID klien Anda di bidang "Username" dan rahasia klien Anda untuk PayPal di bidang "Password".

Permintaan ini diperlukan untuk mendapatkan "access_token".

Lebih lanjut tentang autentikasi dapat ditemukan di dokumentasi PayPal.

Detail lebih lanjut tentang node http request dapat ditemukan di sini.

3.3. Atur Parameter untuk Membuat Tautan Pembayaran

• Seret node "function" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Masukkan kode dari contoh ke dalam bidang "Function".

Dalam contoh ini, kami membentuk permintaan untuk membuat tautan pembayaran berdasarkan data dari node sebelumnya.

// access_token untuk paypal, diperoleh di node "paypal auth"
const accessToken = msg.payload.access_token
// data pesanan, diperoleh di node "pesanan dibuat"
// objek pesanan sesuai dengan pesanan dari API pesanan https://oneentry.cloud/instructions/api
const order = msg.orderEvent.order
// ID sesi pembayaran, diperoleh di node "buat sesi pembayaran"
const paymentSessionId = msg.paymentSessionId

// bentuk data untuk paypal berdasarkan data pesanan
const items = order.products.map((product) => {
    return {
        name: product.title,
        description: 'deskripsi Anda',
        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',
            },
        },
    },
}

// Body permintaan
msg.payload = data
// Header permintaan
msg.headers = {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${accessToken}`,
    Prefer: 'return=representation',
}

return msg

Detail lebih lanjut dapat ditemukan di dokumentasi PayPal.

Detail lebih lanjut tentang node Function dapat ditemukan di sini.

4. Membuat Tautan Pembayaran

Dalam contoh ini, node "http request" digunakan. Node ini dapat digunakan untuk melakukan permintaan HTTP.

• Seret node "http request" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Pilih "POST" di bidang Metode.
• Pilih "Kirim sebagai body permintaan" di bidang Data.
• Masukkan tautan https://api-m.sandbox.paypal.com/v2/checkout/orders di bidang Tautan.
• Pilih "Object JSON" di bidang Kembali.

Dalam contoh ini, kami membuat permintaan ke PayPal untuk menghasilkan tautan pembayaran dengan data dari node sebelumnya.

Detail lebih lanjut dapat ditemukan di dokumentasi PayPal.

Detail lebih lanjut tentang node http request dapat ditemukan di sini.

5. Memperbarui Sesi Pembayaran

• Seret node "admin-api" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Pilih metode "Pembaruan sesi pembayaran".
• Masukkan kode dari deskripsi di bawah ini ke dalam bidang "Query parameters".

{
  "id": {{paymentSessionId}}
}

• Masukkan kode dari deskripsi di bawah ini ke dalam bidang "Request body".

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

Di sini, kami mengekstrak pengidentifikasi tautan pembayaran "msg.paymentSessionId" dan tautan pembayaran "msg.payload.links[0].href" dari permintaan sebelumnya.

Lebih lanjut tentang nilai yang dikembalikan dapat ditemukan di dokumentasi PayPal.

Detail lebih lanjut tentang node admin-api dapat ditemukan di sini.

6. Menambahkan Endpoint untuk Mengambil Tautan Pembayaran

6.1. Atur Topik "createPaymentLink"

• Seret node "function" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Masukkan kode dari contoh ke dalam bidang "Function".

Ini diperlukan untuk mengidentifikasi alur saat ini.

msg.topic = 'createPaymentLink'

return msg

Detail lebih lanjut tentang node Function dapat ditemukan di sini.

6.2. Buat Endpoint untuk Mengambil Tautan Pembayaran

• Seret node "http in" ke ruang kerja.
• Pilih "POST" sebagai metode.
• Masukkan tautan /get-payment-link.

Endpoint ini akan diperlukan untuk mengambil tautan pembayaran saat ini.

Detail lebih lanjut tentang node http in dapat ditemukan di sini.

6.3. Atur Topik "getPaymentLink"

• Seret node "function" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Masukkan kode dari contoh ke dalam bidang "Function".

Ini diperlukan untuk mengidentifikasi alur saat ini.

msg.topic = 'getPaymentLink'

return msg

Detail lebih lanjut tentang node Function dapat ditemukan di sini.

6.4. Simpan Data di Konteks

• Seret node "function" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Masukkan kode dari contoh ke dalam bidang "Function".

Ini diperlukan untuk membentuk respons.

// ambil ID pesanan saat ini
const orderId = msg.payload.orderId
// kunci konteks saat ini
const contextKey = `payment_link_${orderId}`
// ambil API OneEntry
const api = global.get('api')
// data konteks saat ini
const contextData = flow.get(contextKey) || {}
// set data ke konteks berdasarkan topik
if (msg.topic === 'createPaymentLink') {
    contextData.paymentSessionId = msg.paymentSessionId
    contextData.createPaymentLinkCompleted = true
}
if (msg.topic === 'getPaymentLink') {
    contextData.getPaymentLinkCompleted = true
    contextData.res = msg.res
}
// set data konteks ke konteks
flow.set(contextKey, contextData)
// jika createPaymentLink dan getPaymentLink selesai, kirim respons dengan sesi saat ini
if (
    contextData.createPaymentLinkCompleted &&
    contextData.getPaymentLinkCompleted
) {
    // ambil sesi pembayaran berdasarkan id dari api
    const paymentSession = await api.getPaymentSessionById({
        id: contextData.paymentSessionId,
    })
    msg.payload = paymentSession
    msg.res = contextData.res

    // bersihkan api
    flow.set(contextKey, null)

    return msg
}

return null

Detail lebih lanjut tentang node Function dapat ditemukan di sini.

6.5. Titik Keluaran untuk Tautan Pembayaran

• Seret node "http response" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.

Ini diperlukan untuk mengeluarkan respons terhadap permintaan.

Detail lebih lanjut tentang node http response dapat ditemukan di sini.

7. Mengatur Webhook untuk PayPal

7.1. Titik Masukan untuk PayPal

• Seret node "http in" ke ruang kerja.
• Pilih "POST" sebagai metode.
• Masukkan tautan /paypal.

Endpoint ini akan diperlukan untuk memperbarui status pembayaran melalui PayPal.

Detail lebih lanjut tentang node http in dapat ditemukan di sini.

7.2. Respons terhadap Permintaan

• Seret node "function" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Masukkan kode dari contoh ke dalam bidang "Function".

Ini diperlukan untuk membentuk respons.

msg.payload = {
    ok: true,
}

return msg

Detail lebih lanjut tentang node function dapat ditemukan di sini.

7.3. Titik Keluaran untuk PayPal

• Seret node "http response" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.

Node ini diperlukan untuk mengeluarkan respons terhadap permintaan.

Detail lebih lanjut tentang node http response dapat ditemukan di sini.

7.4. Mendapatkan Status Pembayaran

• Seret node "function" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Masukkan kode dari contoh ke dalam bidang "Function".

Di node ini, kami mengambil nilai yang diperoleh dari node "paypal webhook" dan menuliskannya ke "msg.status" untuk digunakan di node berikutnya.

msg.status = msg.payload.resource.status

return msg

Detail lebih lanjut tentang node Function dapat ditemukan di sini.

7.5. Memeriksa Status Pembayaran

• Seret node "switch" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Di "Property", tulis nilai "status".
• Tambahkan aturan pertama untuk pemeriksaan. Pilih kondisi "==", dan masukkan "APPROVED" sebagai nilai.
• Tambahkan aturan kedua untuk pemeriksaan. Pilih kondisi "else".

Node ini akan memeriksa nilai dari "msg.status" terhadap aturan yang ditentukan. Jika nilai adalah "APPROVED", node dari cabang pertama akan dieksekusi; jika tidak, node dari cabang kedua akan dieksekusi.

Detail lebih lanjut tentang node switch dapat ditemukan di sini.

7.6. Mendapatkan ID Sesi Pembayaran

• Seret node "function" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Masukkan kode dari contoh ke dalam bidang "Function".

Di node ini, kami mengambil ID sesi pembayaran yang kami simpan di node "set payment data".

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

return msg

Lebih lanjut tentang nilai yang dikembalikan dapat ditemukan di dokumentasi PayPal.

Detail lebih lanjut tentang node Function dapat ditemukan di sini.

7.7. Memperbarui Status Pembayaran

• Seret node "admin-api" ke ruang kerja dan hubungkan ke node dari langkah sebelumnya.
• Pilih metode "Pembaruan sesi pembayaran".
• Masukkan kode dari deskripsi di bawah ini ke dalam bidang "Query parameters".

{
    "id": {{paymentSessionId}}
}

• Masukkan kode dari deskripsi di bawah ini ke dalam bidang "Request body".

{
    "status": "completed"
}

Di sini, kami memperbarui status pembayaran berdasarkan pengidentifikasi dari "msg.paymentSessionId".

Detail lebih lanjut tentang node admin-api dapat ditemukan di sini.

7. Tambahkan Webhook di Akun PayPal Anda

Tautan ke proyek Anda + /api/admin/workflows/endpoints/paypal.

Contoh:

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

Detail lebih lanjut dapat ditemukan di dokumentasi PayPal.

8. Menguji Integrasi

8.1. Buat Pesanan

Instruksi tentang cara membuat pesanan dijelaskan di dokumentasi API.

8.2. Dapatkan Tautan Pembayaran

• Lakukan permintaan POST ke https://integrations-study.oneentry.cloud/api/admin/workflows/endpoints/get-payment-link, mengganti https://integrations-study.oneentry.cloud dengan tautan ke proyek Anda.

• Di body permintaan, tentukan ID pesanan yang dibuat sebelumnya:

{
    "orderId": 15
}

8.3. Bayar untuk Pesanan

8.4. Periksa Status Pesanan