Halaman ini diterjemahkan oleh Cloud Translation API.

Panduan FOP Tunai (alias API Nomor Referensi)

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

Kasus penggunaan

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

Tunai - Pengguna membayar secara tunai di lokasi fisik.
NRM - Pengguna mentransfer uang ke Nomor Rekening Virtual.

Tunai

Pengguna dapat membeli sesuatu dari Google dengan membayarnya secara tunai di lokasi fisik, seperti minimarket. Guna mengidentifikasi transaksi, pengguna akan membuat nomor referensi yang akan 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 Anda di Google akan meminta contoh petunjuk pembayaran yang biasa Anda lakukan. Anda akan bekerja sama dengan kontak Google Anda untuk mengoptimalkan dan meningkatkan kualitas fitur pesan tersebut.

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

NRM

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

Integrator perlu memverifikasi bahwa jumlah yang ditransfer sesuai dengan jumlah permintaan referenceNumberGeneration, lalu memberi tahu Google bahwa nomor referensi telah dibayarkan.

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 itu penting

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

Cara menerapkan Idempotensi

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

Jika respons sebelumnya adalah error (400 atau 500 dll), Anda harus memproses permintaan tersebut sebagai permintaan baru, dan memeriksanya lagi. Hal ini akan membantu jika server Anda sedang tidak aktif pertama kali dan mencoba lagi memberikan peluang lain agar permintaan 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, entitas lainnya adalah YouTube, dan entitas lainnya adalah Google Ads. Hal 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 Cash FOP API, 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 penggunaan Cash FOP API, 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 Anda di Google dan akun penjual Anda.

Integrator mungkin juga memiliki akun yang berbeda sesuai dengan setiap negara yang dilayani. Hal ini mungkin karena adanya berbagai undang-undang perpajakan dan perbedaan lainnya dari satu negara ke negara lain. Dalam hal ini, PIAID lain mungkin akan dibuat untuk setiap negara.

API untuk diintegrasikan

API berikut menangani pembuatan nomor referensi dan notifikasi pembayaran.

API berikut menangani transfer dana dan pembayaran.

RemittanceStatementNotification
RemittanceStatementDetails
AcceptRemittanceStatement/AcceptRemittanceStatement dengan perubahan

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

Buat nomor referensi

Google akan memanggil GenerateReferenceNumber saat Anda melakukan pembelian. Kami harap Anda menanggapi dengan nomor referensi yang mengidentifikasi transaksi atau akun. 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 telah berakhir masa berlakunya. Setelah Anda berhasil merespons permintaan ini, pastikan 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 dalam 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 telah selesai, layanan Anda perlu memberi tahu Google bahwa transaksi telah selesai dan mengirimkan produk kepada pengguna. Setelah pemberitahuan ini diterima oleh Google, Google memperkirakan bahwa transaksi telah 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 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 tersebut. 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 terutang Integrator (dalam micros). Selain itu, tanggal dan jenis mata uang akan muncul dalam pesan ini, dengan periode penagihan yang menunjukkan masing-masing 00:00:00.000 dan 23:59:59.999 dari hari 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 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 ini cuplikan singkat dari respons yang lebih besar, yang menjelaskan dua peristiwa penangkapan (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 kejadian ini dengan kejadian yang dicatat. Jika ada transaksi yang tidak cocok atau transaksi hilang, hubungi Google untuk penyelidikan lebih lanjut. Jika semua transaksi cocok, dan biaya prosesnya belum termasuk pajak, hubungi acceptRemittanceStatement. Jika sudah termasuk pajak, hubungi acceptRemittanceStatementWithModifications.

Metode acceptRemittanceStatement digunakan saat tidak ada pajak atas biaya.

Jika pajak disertakan, panggil acceptRemittanceStatementWithModifications dan tentukan tarif pajak. Jika tarif pajak Anda berubah, pastikan Anda telah memperbaruinya. Setelah acceptRemittanceStatement berhasil, mulai 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)

Kasus penggunaan

Tunai

NRM

Mengirim pesan antara server Anda dan server Google

Mengikuti perilaku idempoten

Mengapa itu 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

`referenceNumberPaidNotification`

`remittanceStatementNotification`

Rekonsiliasi (`remittanceStatementDetails`)

`acceptRemittanceStatement` dan `acceptRemittanceStatementWithModifications`

URL Permintaan untuk `acceptRemittanceStatement`

URL Permintaan untuk `acceptRemittanceStatementWithModifications`