Halaman ini diterjemahkan oleh Cloud Translation API.

Panduan FOP Tunai (alias API Nomor Referensi)

Berikut ini beberapa kasus penggunaan penting yang perlu dipertimbangkan, serta panduan dan API yang diperlukan untuk menerapkan metode pembayaran tunai Anda.

Kasus penggunaan

Ada sejumlah penggunaan untuk Reference Number API. Panduan ini akan membahas dua kasus penggunaan dan memandu Anda dalam penerapannya.

Tunai - Pengguna membayar dengan uang tunai di lokasi fisik.
VAN - Pengguna mentransfer uang ke Nomor Rekening Virtual.

Tunai

Pengguna dapat membeli sesuatu dari Google dengan membayarnya secara tunai di lokasi fisik, seperti minimarket. Untuk mengidentifikasi transaksi, pengguna akan membuat nomor referensi yang dapat dibawa ke toko untuk membayar. Selain itu, Google akan menampilkan petunjuk kepada pengguna tentang cara menyelesaikan pembelian. Idealnya, segera setelah pengguna menyelesaikan pembelian, integrator akan memberi tahu Google agar Google dapat mengirimkan produk.

Kontak (POC) Anda di Google akan meminta contoh petunjuk pembayaran umum. Anda akan bekerja sama dengan kontak Google Anda untuk mengoptimalkan dan menyempurnakan pesan.

Pengalaman pengguna yang ingin diberikan oleh Google adalah bahwa pesanan pelanggan akan diantarkan saat ia meninggalkan toko. Google mengharapkan ReferenceNumberPaidNotification untuk diterima di Google dalam waktu tiga menit setelah pelanggan membayar nomor referensi. Setelah ReferenceNumberPaymentNotification dikirim, transaksi tidak dapat dibatalkan oleh integrator.

VAN

Pengguna dapat membayar barang dengan rekening bank mereka. Google akan meminta Nomor Rekening Virtual dari integrator, yang menunjukkan nomor dan petunjuk tersebut kepada pengguna. Selanjutnya, pengguna akan menyalin nomor tersebut dan memasukkannya ke aplikasi perbankan mereka selain jumlah yang akan ditransfer.

Integrator harus memverifikasi bahwa jumlah yang ditransfer cocok dengan jumlah permintaan referenceNumberGeneration, lalu memberi tahu Google bahwa nomor referensi telah dibayar.

Setelah Google menerima ReferenceNumberPaidNotification, Google akan mengirimkan produk dan transaksi tidak dapat dibatalkan oleh integrator.

Mengirim pesan antara server Anda dan server Google

Saat mengirim pesan antara server Anda dan server Google, atau sebaliknya, harap lakukan sesuai dengan pedoman ini.

Permintaan masuk - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

Respons keluar - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Permintaan Google - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Respons Google - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

Berikut adalah library dan contoh PGP di Java yang menunjukkan penanganan permintaan dan respons.

Mengikuti perilaku idempoten

Idempotensi berarti Anda tidak boleh mencoba memproses ulang permintaan apa pun (seperti pembayaran) yang telah berhasil diproses. Respons untuk pemrosesan yang berhasil harus dilaporkan.

Mengapa ini penting

Google dapat mencoba kembali beberapa permintaan untuk memastikan status di pihak kami sama dengan negara bagian di pihak vendor. Sistem Anda tidak boleh menganggap bahwa ini merupakan transaksi lain. Oleh karena itu, idempotency sangat penting. Ini berarti integrator tidak boleh memproses ulang sesuatu yang sudah berhasil diproses. Dalam kasus semacam itu, respons sebelumnya harus dikirim.

Cara menerapkan Idempotensi

Jika Google mengirimkan percobaan ulang, ID permintaan akan sama, dan kontennya akan sama, tetapi stempel waktu akan berbeda. Tanggapi dengan respons yang sama dengan yang Anda kirim sebelumnya. Jika respons pertama Anda adalah 200 (Berhasil), Google akan mengharapkan respons yang sama dengan stempel waktu yang berbeda.

Jika respons Anda sebelumnya adalah error (400 atau 500 dll), Anda harus memproses permintaan tersebut sebagai permintaan baru, memeriksanya lagi. Hal ini berguna jika server Anda tidak aktif untuk pertama kalinya dan mencobanya lagi akan memberikan kesempatan lain untuk berhasil diproses.

Untuk mempelajari lebih lanjut, lihat panduan mendetail ini.

Menggunakan ID Akun Integrator Pembayaran (PIAID)

Integrasi dengan Google mungkin memerlukan integrasi dengan berbagai entitas bisnis Google. Misalnya, Google Play adalah satu entitas, yang lainnya adalah YouTube, dan yang lainnya adalah Google Ads. Proses ini akan melibatkan akun penjual yang berbeda untuk mewakili setiap konfigurasi ini.

Untuk pemetaan dari setiap entitas dalam Google ke setiap akun penjual, Google memberikan ID Akun Integrator Pembayaran (PIAID). Untuk contoh FOP API uang tunai, lihat generateReferenceNumber. Berikut adalah contoh yang menggunakan pemetaan tersebut.

Untuk pemetaan dari setiap entitas dalam Google ke setiap akun penjual, Google memberikan ID Akun Integrator Pembayaran (PIAID). Untuk contoh yang menggunakan FOP API tunai, lihat generateReferenceNumber. Berikut adalah contoh yang menggunakan pemetaan tersebut.


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "transactionDescription": "Google - Music",
  "currencyCode": "USD",
  "amount": "2000000"
}

Perhatikan bagian yang ditandai. Dua nilai yang diperlukan di sini adalah paymentIntegratorAccountId yang diberikan oleh kontak (POC) Anda di Google, dan akun penjual Anda.

Integrator mungkin juga memiliki akun yang berbeda sesuai dengan setiap negara yang dilayani. Hal ini mungkin disebabkan oleh berbagai undang-undang perpajakan dan perbedaan lain antara satu negara dengan negara lain. Dalam hal ini, PIAID lain mungkin dibuat untuk setiap negara.

API untuk diintegrasikan

API berikut menangani pembuatan nomor referensi dan notifikasi pembayaran.

API berikut menangani transfer dana dan penyelesaian transaksi.

RemittanceStatementNotification
RemittanceStatementDetails
AcceptRemittanceStatement/AcceptRemittanceStatement dengan perubahan

Anda harus mengintegrasikan semua API di atas untuk membuat nomor referensi dan menyesuaikan dengan Google.

Buat nomor referensi

Google memanggil GenerateReferenceNumber saat Anda memulai pembelian. Kami mengharapkan Anda merespons dengan nomor referensi yang mengidentifikasi transaksi atau rekening. Latensi yang diharapkan adalah < 3 detik.

Untuk transaksi Tunai, nomor referensi dapat berisi hingga 12 karakter.

URL: POST https://[your basepath]/v1/generateReferenceNumber

Meminta JSON

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
    "requestTimestamp": "1561678470395"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "transactionDescription": "Google Play - Tester",
  "currencyCode": "USD",
  "amount": "10000000"
}

Tanggapan JSON

{
  "responseHeader": {
    "responseTimestamp": "1561678947659"
  },
  "result": "SUCCESS",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

Contoh Java

`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`

GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);

Batalkan nomor referensi

Google dapat memilih untuk membatalkan nomor referensi dan mencegahnya dibayar oleh pengguna. Contoh kasus penggunaan adalah promosi yang sudah tidak berlaku. Setelah Anda merespons dengan keberhasilan permintaan ini, Anda harus memastikan bahwa nomor referensi tidak dapat dibayar.

Jika pengguna telah memulai proses pembayaran, misalnya pencarian nomor referensi dari tempat penjualan, server Anda harus merespons dengan respons HTTP 423 dan ErrorResponse di isi permintaan dengan status USER_ACTION_IN_PROGRESS.

URL: POST https://[your basepath]/v1/cancelReferenceNumber

Meminta JSON

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "51e00f16-36ba-4490-b228-0a670d202206",
    "requestTimestamp": "1561678947926"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

Tanggapan JSON

{
  "responseHeader": {
    "responseTimestamp": "1561680406459"
  },
  "result": "SUCCESS"
}

`referenceNumberPaidNotification`

Setelah pembayaran diterima dan transaksi selesai, layanan Anda harus memberi tahu Google bahwa transaksi selesai dan mengirimkan produk kepada pengguna. Setelah notifikasi ini diterima oleh Google, Google mengharapkan bahwa transaksi tersebut diselesaikan dan tidak dapat direservasi.

URL endpoint referenceNumberPaidNotification:


POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]

Meminta JSON

{
 "requestHeader": {
    "requestTimestamp": "1561748625577",
    "requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    }
  },
  "paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
  "referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
  "paymentLocation": {
    "brandName": "TestMart",
    "locationId": "1234"
  },
   "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "paymentTimestamp": "1561748625577"
}

Tanggapan JSON

{
  "responseHeader": {
    "responseTimestamp": "1561748642600"
  },
  "result": "SUCCESS"
}

Menerapkan transfer dana

Setelah mengintegrasikan API untuk FOP tertentu, Anda siap untuk melakukan transfer dana. Transfer dana berfungsi sama di semua FOP.

`remittanceStatementNotification`

Dua hari setelah transaksi, Google akan mengirimkan remittanceStatementNotification yang berisi ringkasan transaksi yang dicatat Google pada hari itu. Contoh notifikasi terlihat seperti ini, dua hari setelah transaksi:

POST https://www.integratordomain.com/v1/remittanceStatementNotification

Meminta JSON


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-statement-abc",
    "requestTimestamp": "1502632800000"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "remittanceStatementSummary": {
    "statementDate": "1502607600000",
    "billingPeriod": {
      "startDate": "1502434800000",
      "endDate": "1502521199000",
    },
    "dateDue": "1503212400000",
    "currencyCode": "INR",
    "totalDueByIntegrator": "1076000000",
  }
}

Perhatikan pemetaan totalDueByIntegrator. Pada baris ini, Anda dapat melihat jumlah bersih yang harus dibayar Integrator (dalam mikro). Selain itu, tanggal dan jenis mata uang muncul dalam pesan ini, dengan periode penagihan yang masing-masing menunjukkan 00:00:00.000 dan 23:59:59.999 tanggal transaksi paling awal dan terakhir.

Rekonsiliasi (`remittanceStatementDetails`)

Untuk rekonsiliasi, integrator akan memanggil remittanceStatementDetails untuk mendapatkan daftar peristiwa yang disertakan dalam remittanceStatementNotification.

Google merespons permintaan remittanceStatementDetails dengan daftar peristiwa yang diberi nomor halaman. remittanceStatementDetails harus dipanggil beberapa kali jika jumlah total transaksi lebih besar dari 1.000. Permintaan tidak perlu dibuat secara berurutan, dan dapat diparalelkan.

URL Permintaan

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails

Contoh isi permintaan

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "statement_detail_request_139932019",
    "requestTimestamp": "1502551332087"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc",
  "numberOfEvents": 4
}

Berikut adalah cuplikan singkat dari respons yang lebih besar, yang menjelaskan dua peristiwa pengambilan (transaksi).

"captureEvents": [ {
    {
      "eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
      "paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
      "eventCharge": "700000000",
      "eventFee": "-28000000"
    },
    {
      "eventRequestId": "Ggghvh78200PQ3Yrpb",
      "paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
      "eventCharge": "800000000",
      "eventFee": "-32000000"
    }
  }

Lihat remittanceStatementDetails untuk mempelajari lebih lanjut.

`acceptRemittanceStatement` dan `acceptRemittanceStatementWithModifications`

Integrator harus membandingkan peristiwa ini dengan peristiwa yang telah mereka catat. Jika ada transaksi yang tidak cocok atau transaksi tidak ada, hubungi Google untuk penyelidikan lebih lanjut. Jika semua transaksi cocok, dan biaya proses tidak termasuk pajak, panggil acceptRemittanceStatement. Jika pajak sudah termasuk, panggil acceptRemittanceStatementWithModifications.

Metode acceptRemittanceStatement digunakan saat tidak ada pajak atas biaya.

Jika pajak akan disertakan, panggil acceptRemittanceStatementWithModifications dan tentukan tarif pajak. Jika tarif pajak Anda berubah, pastikan tarif tersebut diperbarui. Setelah acceptRemittanceStatement berhasil, lakukan transfer bank ke Akun Google.

URL Permintaan untuk `acceptRemittanceStatement`

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement

Contoh isi permintaan

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
}

Contoh respons

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementResultCode": "SUCCESS"
}

URL Permintaan untuk `acceptRemittanceStatementWithModifications`

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications

Contoh isi permintaan

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
  "feeToVatModification": {
    "vatToFeeRatioInMicros": "150000"
  }
}

Contoh respons

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}

Panduan FOP Tunai (alias API Nomor Referensi) Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Kasus penggunaan

Tunai

VAN

Mengirim pesan antara server Anda dan server Google

Mengikuti perilaku idempoten

Mengapa ini penting

Cara menerapkan Idempotensi

Menggunakan ID Akun Integrator Pembayaran (PIAID)

API untuk diintegrasikan

Buat nomor referensi

Meminta JSON

Tanggapan JSON

Contoh Java

Batalkan nomor referensi

Meminta JSON

Tanggapan JSON

referenceNumberPaidNotification

Meminta JSON

Tanggapan JSON

Menerapkan transfer dana

remittanceStatementNotification

Meminta JSON

Rekonsiliasi (remittanceStatementDetails)

URL Permintaan

Contoh isi permintaan

acceptRemittanceStatement dan acceptRemittanceStatementWithModifications

URL Permintaan untuk acceptRemittanceStatement

Contoh isi permintaan

Contoh respons

URL Permintaan untuk acceptRemittanceStatementWithModifications

Contoh isi permintaan

Contoh respons

Panduan FOP Tunai (alias API Nomor Referensi)

`referenceNumberPaidNotification`

`remittanceStatementNotification`

Rekonsiliasi (`remittanceStatementDetails`)

`acceptRemittanceStatement` dan `acceptRemittanceStatementWithModifications`

URL Permintaan untuk `acceptRemittanceStatement`

URL Permintaan untuk `acceptRemittanceStatementWithModifications`