Menggunakan API Meta Pay

Saat Anda memproses pembayaran untuk Meta Pay, Anda harus memberi tahu Meta tentang aktivitas transaksi pembayaran, seperti otorisasi dan pengembalian dana, dengan mengaktifkan webhooks di API Meta Pay. Aktivitas transaksi pembayaran muncul di halaman Pesanan dan pembayaran di akun Facebook pelanggan.

Untuk mempelajari cara menggunakan API Meta, lihat Ringkasan Graph API dan perhatikan bahwa API yang dijelaskan di bawah relatif terhadap URL host Graph API standar (https://graph.facebook.com). Untuk informasi umum selengkapnya, lihat Ringkasan Integrasi Meta Pay.

Penggunaan

Sebelum Anda dapat mulai menggunakan API Meta Pay, Anda harus menyelesaikan hal berikut:

• Menyelesaikan langkah penggunaan umum
• Meninjau Pemrosesan Pembayaran di Meta Pay

Memanggil API Meta Pay

Sebagai bagian dari langkah penggunaan umum, buatlah aplikasi baru di Portal Meta untuk Developer. Setelah membuat aplikasi, Anda mendapatkan ID aplikasi dan rahasia aplikasi untuk aplikasi Anda.

Setiap panggilan yang Anda lakukan ke API Meta Pay memerlukan token akses aplikasi yang berasal dari ID aplikasi dan rahasia aplikasi. Kirim token akses aplikasi dengan menggunakan header Authorization, bukan parameter kueri access_token. API Meta Pay menolak panggilan dengan token pengguna.

Contohnya, gunakan kode berikut:

Authorization: OAuth <APP_ACCESS_TOKEN>

Tanda Tangan

Setiap permintaan HTTP ke API Meta Pay harus menyertakan header permintaan FBPAY_SIGNATURE. Nilai header ini adalah objek JSON Web Signature (JWS) dengan algoritma ES256, serialisasi ringkas, dan payload terpisah (sesuai dengan https://tools.ietf.org/html/rfc7515#appendix-F). Nilai payload adalah isi permintaan HTTP POST. Kunci tanda tangan JWS harus diidentifikasi dengan header x5c, yang harus berisi sertifikat yang terhubung ke trusted root milik mitra. Sertifikat root mitra dibagikan dengan Meta sebagai bagian dari proses penggunaan (disebut sebagai sertifikat tanda tangan API Meta Pay).

Contoh permintaan dengan tanda tangan

curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "FBPAY_SIGNATURE: eyJhbGciOiJFUzI1NiIsIng1YyI6WyJNSUlCaERDQ0FTcWdBd0lCQWdJQkFUQUtCZ2dxaGtqT1BRUURBakFoTVI4d0hRWURWUVFEREJad1lYSjBibVZ5SUhOcFoyNWhkSFZ5WlNCalpYSjBNQjRYRFRJd01EY3hNekl5TWpVek1Gb1hEVEkwTURNeE1USXlNalV6TUZvd0lURWZNQjBHQTFVRUF3d1djR0Z5ZEc1bGNpQnphV2R1WVhSMWNtVWdZMlZ5ZERCWk1CTUdCeXFHU000OUFnRUdDQ3FHU000OUF3RUhBMElBQkFuRngwR1NKMklPZGZpcFdiMGMwZytBVThlbDh6QnRVS0kxdWRzT2kzN2thd1JRSFkzV29YaWRvRThIOHM1cVIySmo2ZkFKWVhOTURXY0NiditWMEJ1alV6QlJNQjBHQTFVZERnUVdCQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QWZCZ05WSFNNRUdEQVdnQlR4NlBGRkhjd2FUZnY5cVdzZUJcL1NjMWFPbVZ6QVBCZ05WSFJNQkFmOEVCVEFEQVFIXC9NQW9HQ0NxR1NNNDlCQU1DQTBnQU1FVUNJUUNBRE9zZ0pZanRXVm9xNUZOSjc3U2JDeWtON1ZldUlKR2pXb3NBVUFNd1ZRSWdUTlVcL2ttc1wvN0cxVUx5Z01DRWVXemNiYTNrMVo4NEE4RmNlMXQzYUNGbGc9Il19..ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" "https://graph.facebook.com/1001200005002/notify_authorizations" \
  -d '{"notification":{"partner_merchant_id":"123e4567-e89b-12d3-a456-426614174000","container_id":"cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x","event_time":1582230020020,"type":"notify_authorizations"},"resource":{"partner_auth_id":"1234567890","auth_amount":{"currency":"USD","value":29508},"status":"SUCCEEDED","created_time":1582230019010,"metadata":[]},"idempotence_token":"ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"}'

Permintaan sebelumnya mengenkode data berikut:

{
  "notification": {
    "partner_merchant_id": "123e4567-e89b-12d3-a456-426614174000",
    "container_id": "cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x",
    "event_time": 1582230020020,
    "type": "notify_authorizations"
  },
  "resource": {
    "partner_auth_id": "1234567890",
    "auth_amount": {
      "currency": "USD",
      "value": 29508
    },
    "status": "SUCCEEDED",
    "created_time": 1582230019010,
    "metadata": []
  },
  "idempotence_token": "ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"
}

Berikut ini adalah tanda tangan dari permintaan sebelumnya, Base64 dan JSON yang didekodekan untuk kejelasan:

base64url(
 json({
   "x5c": [
     "MIIBhDCCASqgAwIBAgIBATAKBggqhkjOPQQDAjAhMR8wHQYDVQQDDBZwYXJ0bmVyIHNpZ25hdHVyZSBjZXJ0MB4XDTIwMDcxMzIyMjUzMFoXDTI0MDMxMTIyMjUzMFowITEfMB0GA1UEAwwWcGFydG5lciBzaWduYXR1cmUgY2VydDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAnFx0GSJ2IOdfipWb0c0g+AU8el8zBtUKI1udsOi37kawRQHY3WoXidoE8H8s5qR2Jj6fAJYXNMDWcCbv+V0BujUzBRMB0GA1UdDgQWBBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAfBgNVHSMEGDAWgBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQCADOsgJYjtWVoq5FNJ77SbCykN7VeuIJGjWosAUAMwVQIgTNU/kms/7G1ULygMCEeWzcba3k1Z84A8Fce1t3aCFlg="
   ],
   "alg": "ES256"
 })
) + // Protected Header
 "." +
 "" + // Payload is detached
 "." +
 "ZnT7ZR3EqsPYMQt3WdgUZYScBiyK9RI77zMaUKr-tkFRBHgBJQVTOORwM2fFh0QQCTLwOp1TiAzt_q9ofvw6JQ" // Signature

Idempotensi

Kolom idempotence_token digunakan untuk mencegah eksekusi duplikat permintaan saat permintaan dicoba ulang setelah kegagalan jaringan atau waktu habis. Token idempotensi adalah nilai unik yang dihasilkan oleh klien dan klien memutuskan cara membuat token ini. Contoh: Anda dapat menggunakan V4 UUID untuk menghasilkan token idempotensi.

Saat permintaan berhasil diselesaikan, atau panggilan ke API memberikan hasil yang valid, data tanggapan disimpan dengan token idempotensi. Ketika permintaan yang berhasil kemudian dicoba ulang dengan token idempotensi yang digunakan sebelumnya, tanggapan yang disimpan sebelumnya diberikan tanpa menjalankan kembali kode apa pun.

Saat permintaan menampilkan kesalahan, tidak ada hasil yang disimpan. Anda dapat mencoba kembali permintaan dan menggunakan token idempotensi yang sama.

Jika Anda membuat 2 permintaan secara bersamaan dengan token idempotensi yang sama, hanya satu yang memberikan data tanggapan.

Token idempotensi dimaksudkan untuk sementara dan hanya digunakan untuk mencoba lagi panggilan API jika terjadi kegagalan. Jika Anda mencoba kembali permintaan setelah beberapa waktu, Anda mungkin menerima tanggapan yang berbeda dari panggilan sebelumnya.

Parameter permintaan akan diabaikan. Jika Anda mengubah konten permintaan dengan cara apa pun, buat token idempotensi baru untuk permintaan tersebut.

Rekonsiliasi Batch

Saat Anda memproses pembayaran, Anda memberi tahu Meta tentang aktivitas transaksi pembayaran dengan menggunakan webhooks Meta Pay. Dengan memanggil Webhooks, aktivitas transaksi pembayaran muncul di halaman Aktivitas Facebook Pay dari akun Facebook pelanggan sesegera mungkin.

Notifikasi yang gagal ditangkap oleh Meta selama rekonsiliasi batch dan kemudian ditampilkan di akun Facebook pelanggan.

Untuk mendukung rekonsiliasi batch, setiap hari unggah file yang berisi notifikasi yang Anda kirimkan ke Meta hari itu. Sertakan notifikasi yang berhasil dan notifikasi yang gagal. Untuk detail tentang mengunggah file ke API Meta, lihat Mengunggah File ke Facebook.

Penanganan Kesalahan

API Meta Pay menggunakan penanganan kesalahan Graph API standar.

Menginisialisasi dan Memperbarui Pelapak

Untuk menginisialisasi atau memperbarui data untuk pelapak yang Anda dukung, buat permintaan POST ke Graph API pelapak /metapay_partner/merchant dan tentukan parameter pedagang.

https://graph.facebook.com/metapay_partner/merchant

Parameter permintaan

Tanggapan

Setelah Anda membuat permintaan POST ke API pelapak, tanggapan 200 OK menandakan bahwa POST telah berhasil diproses. Isi tanggapan menunjukkan status pelapak, baik ENABLED ataupun DISABLED. Pengubah status yang tidak kosong memberikan informasi tambahan.

Tanggapan umum yang berhasil terlihat seperti berikut:

{
    "status":"ENABLED",
    "status_modifiers":[]
}

Tanggapan untuk pelapak yang sedang menjalani pemeriksaan sementara terlihat seperti berikut:

{
    "status":"DISABLED",
    "status_modifiers":["PENDING_SCREENING"]
}

Berikut adalah kemungkinan pengubah status.

Mendapatkan Pelapak

Untuk mengambil daftar pelapak terdaftar, buat permintaan GET ke Graph API pelapak /metapay_partner/merchants.

https://graph.facebook.com/metapay_partner/merchants

Parameter permintaan

Parameter permintaan opsional berikut didukung sebagai parameter URL:

Tanggapan

Hasil dari GET API Pelapak dipaginasi. Lihat halaman tertaut untuk format tanggapan umum. Setiap elemen yang dikembalikan dalam array data akan berada dalam format Parameter permintaan pelapak. Contoh:

curl -H "Authorization: OAuth $OAUTH" -X GET "https://graph.facebook.com/metapay_partner/merchants?partner_merchant_id=MERCHANT_TEST_1"
{
    "data": [
        {
            "partner_merchant_id": "MERCHANT_TEST_1",
            "merchant_status": "DISABLED",
            "display_name": "Test merchant 1",
            "business_uri": "https://facebook.com/",
            "icon_uri": "https://facebook.com/favicon.ico",
            "mcc_list": [7311],
            "support_email": "example@facebook.com",
            "support_phone": "+11234567890",
            "valid_origins": [
                "https://facebook.com/"
            ],
            "legal_structure": "COMPANY_TYPE_NOT_SPECIFIED",
            "status_modifiers":["BLOCKED"],
            "effective_merchant_status":"DISABLED"
        }
    ],
    "paging": {
        "cursors": {
            "before": "aaa...",
            "after": "bbb..."
        },
        "next": "https://graph.facebook.com/metapay_partner/merchants?limit=25&after=..."
    }
}

Webhooks

Anda harus memberi tahu Meta tentang aktivitas transaksi pembayaran dengan mengaktifkan Webhooks Meta setiap kali terjadi otorisasi, penahanan dana pembayaran, sengketa, pembayaran, atau pengembalian dana.

Tanggapan 200 OK menunjukkan bahwa Webhooks telah berhasil diproses. Isi tanggapan yang berhasil akan mengembalikan container_id:

{
    "id":"cGF5bWVudF9jb250YWluZAXI6N2I3ODA1ZATYtZAmRiNS00Yzc4LWFjYjAtZATg3ZAjJhMzg2YTc5XzM2ODkyNjAzMTc4MDEzNzYZD"
}

Jika pemanggilan webhook gagal, coba lagi pemanggilan tersebut setidaknya tiga kali selama tujuh puluh dua jam dengan kemunduran inkremental. Jika pemanggilan masih gagal, notifikasi dapat diambil nanti selama rekonsiliasi batch.

Berikut adalah diagram hubungan entitas untuk sumber informasi yang dimodelkan di Webhooks API Meta. Properti dengan titik hitam menunjukkan atribut wajib.

Notifikasi

Setiap kali Anda memanggil Webhooks, sertakan parameter notifikasi di isi permintaan dan detail untuk jenis notifikasi di kolom sumber informasi, seperti yang dijelaskan di bagian berikutnya. Struktur umum untuk notifikasi adalah sebagai berikut:

{
  idempotence_token: '<your token>',
  notification:
  {
    ...
  },
  resource:
  {
    ...
  }
}

Parameter Notifikasi

Memberitahukan Otorisasi

Buat permintaan POST ke /<CONTAINER_ID>/notify_authorizations untuk memberi tahu Meta tentang aktivitas otorisasi untuk transaksi pembayaran.

https://graph.facebook.com/<CONTAINER_ID>/notify_authorizations

Sumber informasi otorisasi

Memberitahukan Dana Pembayaran Telah Ditahan

Buat permintaan POST ke /<CONTAINER_ID>/notify_captures untuk memberi tahu Meta tentang aktivitas penahanan dana untuk transaksi pembayaran.

https://graph.facebook.com/<CONTAINER_ID>/notify_captures

Sumber informasi tentang penahanan dana pembayaran

Memberitahukan Sengketa

Buat permintaan POST ke /<CONTAINER_ID>/notify_disputes untuk memberi tahu Meta tentang aktivitas sengketa untuk transaksi pembayaran.

https://graph.facebook.com/<CONTAINER_ID>/notify_disputes

Sumber informasi sengketa

Memberitahukan Pembayaran

Buat permintaan POST ke /<CONTAINER_ID>/notify_payments untuk memberi tahu Meta tentang aktivitas pembayaran yang tidak terkait dengan operasi pergerakan uang. Contohnya, Anda mungkin memutuskan untuk tidak memproses pembayaran pengguna jika gagal melewati pemeriksaan risiko.

https://graph.facebook.com/<CONTAINER_ID>/notify_payments

Sumber informasi pembayaran

Memberitahukan Pengembalian Dana

Buat permintaan POST ke /<CONTAINER_ID>/notify_refunds untuk memberi tahu Meta tentang aktivitas pengembalian dana untuk transaksi pembayaran.

https://graph.facebook.com/<CONTAINER_ID>/notify_refunds

Sumber Informasi pengembalian dana

Objek Jumlah Notifikasi

Gunakan objek jumlah untuk mewakili nilai uang dalam mata uang tertentu untuk notifikasi otorisasi, penahanan dana pembayaran, sengketa, dan pengembalian dana.

Objek jumlah

Objek Kesalahan Notifikasi

Jika terjadi kesalahan saat Anda memproses otorisasi, penahanan dana pembayaran, pembayaran, atau pengembalian dana, sertakan objek error di resource untuk memberikan informasi tentang kesalahan.

Objek kesalahan