Webhooks untuk Pembayaran

Ringkasan

Berlangganan Webhooks

Untuk berlangganan Webhooks Pembayaran, pertama-tama, buat URL endpoint publik yang menerima GET HTTPS untuk verifikasi langganan dan POST HTTPS untuk permintaan data perubahan. Struktur dari kedua jenis permintaan ini dijelaskan di bawah. Selanjutnya, siapkan langganan ke objek payment aplikasi Anda. Ada 2 cara untuk melakukannya:

• Berlangganan melalui Dasbor Aplikasi
• Berlangganan melalui Graph API

Di kedua kasus, endpoint Anda akan menerima data yang sama dengan cara yang sama. Lihat Server Panggilan Balik Anda untuk informasi selengkapnya tentang apa yang akan diterima server Anda.

Berlangganan melalui Dasbor Aplikasi

Cara termudah untuk menyiapkan aplikasi Anda agar menerima pembaruan Webhooks adalah dengan menggunakan panel Pembayaran Dasbor Aplikasi. Temukan aplikasi Anda di dasbor, lalu klik tab Payments. Bagian Webhooks akan berada di bawah bagian Pengaturan perusahaan Anda.

Webhooks untuk Pembayaran

Layar ini kemudian akan mencantumkan status langganan aplikasi Anda, apakah itu telah ditambahkan melalui panel ini atau API. Dari sini, ada kemungkinan untuk mengubah URL panggilan balik langganan dan mengujinya.

Di kolom 'Panggilan Balik', Anda harus menyediakan endpoint server valid yang bisa diakses publik. Ini adalah alamat yang akan kami gunakan untuk memverifikasi langganan dan mengirim pembaruan, dan perlu untuk menanggapi seperti yang dijelaskan dalam Server Panggilan Balik Anda.

Akhirnya, berikan 'Token Verifikasi'. Token ini hanya akan dikirim selama fase pendaftaran untuk memverifikasi bahwa langganan berasal dari lokasi yang aman. Token ini tidak akan dikirim pada pembaruan Webhooks reguler.

Menguji pengaturan Anda

Anda harus menguji pengaturan panggilan balik sebelum menyimpan langganan. Ini akan mengeluarkan permintaan GET verifikasi ke endpoint Anda, berisi parameter hub.mode, hub.challenge, dan hub.verify_token, dan akan memastikan Anda menanganinya dengan benar. Contoh: Anda harus yakin endpoint Anda menggemakan hub.challenge kembali ke Facebook:

Menguji pengaturan Anda

Setelah Anda memasukkan detail langganan Anda, pastikan untuk mengeklik tombol 'Simpan Perubahan' di bagian bawah halaman. Mengedit langganan adalah masalah sederhana tentang mengubah konten kolom, menguji ulang, lalu menyimpan formulir lagi.

Berlangganan melalui Graph API

Anda juga bisa menyiapkan dan mendaftarkan langganan secara terprogram, melalui Graph API. Anda membutuhkan access token aplikasi Anda, yang tersedia dari Fitur token akses atau dengan menggunakan endpoint /oauth Graph API

API langganan tersedia di endpoint https://graph.facebook.com/[APP_ID]/subscriptions

Ada 3 tugas yang dapat Anda lakukan dengannya:

• Menambahkan atau mengubah langganan (dengan mengirimkan permintaan POST HTTPS)
• Cantumkan setiap langganan yang sudah ada (dengan mengirimkan permintaan GET HTTPS)

Menambahkan dan mengubah langganan

Untuk menyiapkan langganan, kirim POST dengan parameter berikut. Ingat bahwa parameter ini sesuai dengan kolom dalam formulir yang dijelaskan di atas:

• object - Seperti di atas, jenis objek yang ingin Anda terima pembaruannya. Tentukan payments.
• fields - Daftar yang dipisahkan koma dari properti jenis objek yang ingin Anda terima pembaruannya. Tentukan 'tindakan' dan 'sengketa'.
• callback_url - Endpoint server yang valid dan bisa diakses secara publik.
• verify_token - String arbitrer, yang dikirimkan ke endpoint Anda saat langganan terverifikasi.

Ketika kami menerima permintaan ini, seperti dengan konfigurasi formulir di atas, kami akan melakukan GET ke panggilan balik Anda untuk memastikan bahwa ini valid dan siap menerima pembaruan. Khususnya, Anda harus yakin endpoint Anda menggemakan hub.challenge kembali ke Facebook.

Ingat bahwa, karena satu aplikasi hanya dapat memiliki satu langganan untuk setiap jenis objek, jika ada langganan untuk jenis objek ini, maka data yang baru diposting akan menggantikan data yang sudah ada.

Membuat daftar langganan Anda

Mengeluarkan GET HTTP ke API Langganan mengembalikan konten berenkode JSON yang mencantumkan daftar langganan Anda. Contoh:

[
  {
    "object": "payments",
    "callback_url": "https://www.friendsmash.com/rtu.php",
    "fields": ["actions", "disputes"],
    "active": true
  }
]

Anda dapat menggunakan Graph Explorer untuk bereksperimen dengan API ini secara langsung, jangan lupa gunakan token akses.

Server Panggilan Balik Anda

Server panggilan balik Anda harus menangani 2 jenis permintaan. Pastikan itu ada di URL publik sehingga kami berhasil membuat permintaan ini.

Verifikasi Langganan

Pertama-tama, server Facebook akan membuat GET HTTPS tunggal ke URL panggilan balik Anda ketika Anda mencoba menambahkan atau mengubah langganan. String kueri akan ditambahkan ke URL panggilan balik Anda dengan parameter berikut:

Endpoint harus terlebih dahulu memverifikasi hub.verify_token. Ini memastikan bahwa server Anda mengetahui bahwa permintaan sedang dibuat oleh Facebook dan terkait dengan langganan yang baru saja Anda konfigurasikan.

Server seharusnya hanya menggemakan nilai hub.challenge kembali, yang mengonfirmasi ke Facebook bahwa server ini dikonfigurasi untuk menerima panggilan balik, dan mencegah kerentanan penolakan layanan (DDoS).

Menerima Pembaruan

Setelah berhasil berlangganan, kami akan lanjut mengeluarkan POST HTTPS ke endpoint server Anda setiap kali ada perubahan (pada kolom atau koneksi yang dipilih). Anda harus menanggapi permintaan ini dengan kode HTTP 200.

Permintaan akan memiliki jenis konten application/json dan badan konten akan terdiri dari string berenkode JSON yang berisi satu atau beberapa perubahan.

Catatan untuk developer PHP: Di PHP, untuk mendapatkan data yang dienkode, Anda akan menggunakan kode berikut:

$data = file_get_contents("php://input");
$json = json_decode($data);`

Perhatikan bahwa parameter hub.mode, hub.challenge, dan hub.verify_token tidak dikirim lagi setelah langganan dikonfirmasi.

Berikut adalah contoh khas dari panggilan balik yang dibuat untuk langganan objek payments:

{
  "object": "payments",
  "entry": [
    {
      "id": "296989303750203",
      "time": 1347996346,
      "changed_fields": [
        "actions"
      ]
    }
  ]
}

Penting untuk dicatat bahwa pembaruan Webhooks hanya memberi tahu Anda bahwa pembayaran tertentu, diidentifikasi oleh kolom id telah diubah. Setelah menerima pembaruan, Anda harus meng-kueri Graph API untuk detail transaksi guna menangani perubahan dengan tepat.

Jika pembaruan ke server Anda gagal, kami akan segera mencoba lagi dan kemudian beberapa kali lagi, dengan frekuensi yang menurun, selama 24 jam berikutnya.

Dengan setiap permintaan, kami mengirim header HTTP X-Hub-Signature-256 yang berisi tanda SHA256 dari muatan permintaan, menggunakan rahasia aplikasi sebagai kode, dan diawali dengan sha256=. Endpoint panggilan balik Anda dapat memverifikasi tanda tangan ini untuk memvalidasi integritas dan asal muatan.

Menanggapi Pembaruan

Setelah server Anda menerima pembaruan, Anda harus meng-kueri Graph API menggunakan kolom id untuk detail pada status baru transaksi. Anda harus mengambil tindakan tergantung statusnya.

Bagian-bagian berikut menghitung semua potensi perubahan status yang memicu pengiriman pembaruan. Ini secara luas terbagi menjadi:

• Perubahan pada array tindakan, yang terjadi ketika pembayaran selesai secara asinkron, pengembalian dana dikeluarkan (oleh Anda atau oleh Facebook) atau ketika pengembalian uang terjadi.
• Perubahan pada array sengketa, yang terjadi saat sengketa pesanan diinisiasi oleh konsumen.

Tindakan

Setiap objek payment berisi array berjudul actions, yang berisi koleksi perubahan status kemajuan transaksi. Setiap entri dalam array actions memiliki properti bernama type yang menggambarkan jenis tindakan yang telah terjadi. type dapat memiliki nilai-nilai berikut: charge, refund,chargeback, chargeback_reversal dan decline, yaitu dijelaskan sepenuhnya di sini.

Contoh tanggapan dari Graph API untuk objek pembayaran dengan tindakan terkait ada di bawah:

{
   "id": "3603105474213890",
   "user": {
      "name": "Marco Alvarez",
      "id": "500535225"
   },
   "application": {
      "name": "Friend Smash",
      "namespace": "friendsmashsample",
      "id": "241431489326925"
   },
   "actions": [
      {
         "type": "charge",
         "status": "completed",
         "currency": "USD",
         "amount": "0.99",
         "time_created": "2013-03-22T21:18:54+0000",
         "time_updated": "2013-03-22T21:18:55+0000"
      },
      {
         "type": "refund",
         "status": "completed",
         "currency": "USD",
         "amount": "0.99",
         "time_created": "2013-03-23T21:18:54+0000",
         "time_updated": "2013-03-23T21:18:55+0000"
      }
   ],
   "refundable_amount": {
      "currency": "USD",
      "amount": "0.00"
   },
   "items": [
      {
         "type": "IN_APP_PURCHASE",
         "product": "https://www.friendsmash.com/og/friend_smash_bomb.html",
         "quantity": 1
      }
   ],
   "country": "US",
   "created_time": "2013-03-22T21:18:54+0000",
   "payout_foreign_exchange_rate": 1,}`

Karena Anda berlangganan kolom tindakan saat mendaftar Webhooks, kami akan mengeluarkan pembaruan saat array berubah sebagai berikut:

Biaya

Awalnya, semua pesanan berisi biaya entri dengan "status": "initiated". Pembayaran yang diinisiasi menunjukkan pembayaran hanya diinisiasi dan belum selesai sepenuhnya. Kami tidak akan mengirim pembaruan untuk pembayaran dengan status diinisiasi.

Ketika pembayaran berhasil selesai, "status": "initiated" akan diubah menjadi "status": "completed" dan kami akan mengeluarkan pembaruan. Saat melihat perubahan ini, Anda harus memeriksa catatan pembayaran untuk memastikan apakah ini transaksi baru atau yang sudah ada dan menanggapi sebagai berikut:

• Jika pesanan sudah diketahui oleh Anda, dan telah dipenuhi oleh panggilan balik JavaScript (diutamakan sebagai pilihan pertama), maka Anda dapat mengabaikan pembaruan dengan aman, atau menggunakannya sebagai konfirmasi ekstra.
• Jika pesanan memang Anda ketahui, tetapi pesanan masih berstatus initiated, maka Anda dapat lanjut memenuhi pesanan, mengeluarkan barang atau mata uang virtual terkait kepada konsumen. Pembayaran ini kemudian dapat ditandai sebagai selesai dengan aman.
• Jika pesanan tidak dikenali, itu menandakan bahwa alur di sisi klien tidak selesai, kemungkinan besar karena masalah konektivitas atau konsumen menutup browsernya di tengah-tengah proses pembayaran. Anda masih dapat memenuhi dan menyelesaikan pesanan ini dengan aman, karena Facebook tetap menjadi sumber kebenaran utama mengenai tagihan pengguna.

Anda juga akan menerima pembaruan untuk pembayaran dengan "status": "failed". Pesanan ini jangan dipenuhi.

Pengembalian Dana

Setiap kali Anda mengeluarkan pengembalian dana melalui Graph API, Anda akan menerima pembaruan. Dengan "type": "charge", pengembalian dana juga dapat memiliki status yang berbeda-beda, dan harus Anda ketahui. Terutama, kemungkinan pengembalian dana gagal, biasanya karena kesalahan pemrosesan atau konektivitas - sehingga Anda harus mencoba kembali mengeluarkan pengembalian dana.

Pengembalian Dana, Penolakan Pengembalian Uang, dan Penolakan

Seperti halnya pengembalian dana, Anda pun akan diberi tahu saat pengembalian uang, penolakan pengembalian uang, atau penolakan telah diterbitkan. Objek pengembalian uang, penolakan pengembalian uang, atau penolakan akan ditambahkan ke array tindakan dari data yang ditampilkan Graph API untuk pembayaran.

Sengketa

Kami akan memberi tahu Anda dengan mengeluarkan pembaruan ketika sengketa dimulai. Dalam hal ini, Anda akan melihat array "disputes" baru muncul sebagai bagian dari objek payment. Array akan berisi waktu sengketa dimulai, alasan konsumen menginisiasi tanggapan dan alamat email konsumen, yang dapat Anda gunakan untuk menghubungi mereka secara langsung guna menyelesaikan sengketa.

Contoh lengkap tanggapan dari Graph API untuk transaksi yang diajukan sengketa ada di bawah:

{
   "id": "990361254213890",
   "user": {
      "name": "Marco Alvarez",
      "id": "500535225"
   },
   "application": {
      "name": "Friend Smash",
      "namespace": "friendsmashsample",
      "id": "241431489326925"
   },
   "actions": [
      {
         "type": "charge",
         "status": "completed",
         "currency": "USD",
         "amount": "0.99",
         "time_created": "2013-03-22T21:18:54+0000",
         "time_updated": "2013-03-22T21:18:55+0000"
      }
   ],
   "refundable_amount": {
      "currency": "USD",
      "amount": "0.99"
   },
   "items": [
      {
         "type": "IN_APP_PURCHASE",
         "product": "https://www.friendsmash.com/og/friend_smash_bomb.html",
         "quantity": 1
      }
   ],
   "country": "US",
   "created_time": "2013-03-22T21:18:54+0000",
   "payout_foreign_exchange_rate": 1,
   "disputes": [
      {
         "user_comment": "I didn't receive my item! I want a refund, please!",
         "time_created": "2013-03-24T18:21:02+0000",
         "user_email": "email\u0040domain.com",
         "status": "resolved", 
         "reason": "refunded_in_cash"
      }
   ]
}

Untuk informasi selengkapnya tentang cara menanggapi sengketa dan mengeluarkan pengembalian dana, silakan lihat Cara Pembayaran: Menangani Sengketa dan Pengembalian Dana.