Standar protokol

API tersebut mengikuti serangkaian standar HTTP API dan mendukung idempotency untuk memfasilitasi model integrasi.

URL yang dihosting Google

Dokumentasi untuk setiap metode yang dihosting Google menyediakan URL dasar, yang berisi nama metode dan nomor versi utama. URL lengkap dibuat dengan menambahkan ID Akun Integrator Pembayaran penelepon ke berakhir. Misalnya, dokumentasi untuk metode echo yang dihosting Google menentukan URL:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

Jika ID Akun Integrator Pembayaran penelepon adalah INTEGRATOR_1, penelepon akan menambahkan di akhir URL untuk membentuk:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

Catatan: Halaman dokumentasi endpoint untuk metode tertentu yang Anda terapkan akan memiliki URL yang paling akurat untuk kasus Anda.

URL yang dihosting partner

Dokumentasi untuk setiap metode API yang dihosting partner menyediakan URL dasar, yang berisi nama metode dan nomor versi utama. Anda tidak boleh menyertakan ID Akun Integrator Pembayaran (PIAID) di URL yang Anda host.

Sandbox dan lingkungan produksi

Google menghosting API Pembayaran Standar di kedua sandbox (untuk pengembangan dan pengujian) dan produksi. Permintaan di lingkungan sandbox Google tidak menghasilkan kewajiban keuangan dunia nyata. Kotak pasir dan lingkungan produksi benar-benar terpisah dan tidak berbagi kunci atau informasi transaksi.

Google mengharapkan bahwa sandbox Anda tersedia secara konsisten karena kami akan menggunakan {i>sandbox<i} untuk menguji perubahan dan fitur baru terlebih dahulu.

Jalur dasar sandbox Google

https://vgw.sandbox.google.com/secure-serving/gsp/

Catatan: Jika integrasi Anda sudah diluncurkan dan memanggil metode https://billpaynotification.sandbox.googleapis.com host, Anda dapat terus melakukannya. Integrasi baru harus memanggil 'vgw.sandbox.google.com' host.

Jalur dasar Produksi Google

https://vgw.googleapis.com/secure-serving/gsp/

Catatan: Jika integrasi Anda sudah diluncurkan dan memanggil metode https://billpaynotification.googleapis.com host, Anda dapat terus melakukannya. Integrasi baru akan memanggil 'vgw.googleapis.com' host.

Panduan ini akan menggunakan endpoint produksi.

Jenis konten dan encoding

Payload pesan yang menggunakan enkripsi PGP harus menggunakan jenis konten application/octet-stream; charset=utf-8. Badan permintaan PGP harus dikirim menggunakan pengkodean base64url, sebagaimana didefinisikan dalam rfc4648 §5. Payload pesan yang menggunakan enkripsi JWE harus menggunakan jenis konten application/jose; charset=utf-8. Opsi Serialisasi Ringkas yang didukung oleh JWE/JWS menangani encoding untuk isi permintaan akhir.

Kode status HTTP

Standard Payments API dirancang untuk menampilkan kode status HTTP 200 untuk semua permintaan yang dapat diproses oleh server. Hal ini mencakup permintaan yang berhasil dan ditolak dari perspektif bisnis atau logika aplikasi. Permintaan yang tidak dapat diproses seharusnya tidak menghasilkan Kode status HTTP 200 karena status tersebut mewakili error antara Google dan partner Anda. Sebagai gantinya, respons API harus menggunakan status HTTP yang sesuai kode di bawah ini dengan objek ErrorResponse opsional.

Error HTTP dan Alasannya
400	BAD REQUEST Klien menentukan argumen yang tidak valid. Ini juga dapat dikembalikan jika operasi ditolak karena sistem tidak dalam status yang dibutuhkan untuk menjalankan operasi. Gunakan metode ini jika percobaan ulang permintaan tidak berhasil hingga status sistem telah diperbaiki secara eksplisit. Misalnya, jika permintaan pengembalian dana gagal karena itu merujuk ke tangkapan yang tidak ada, percobaan ulang tidak akan berhasil sampai penangkapan itu ada dalam sistem integrator. Catatan: bahwa BAD_REQUEST (400) tidak boleh digunakan untuk situasi saat error aplikasi yang sesuai tersedia. Sebagai contoh, mata uang yang salah akan menghasilkan ACCOUNT_DOES_NOT_SUPPORT_CURRENCY dengan kode 200 jika respons standar memiliki kolom atau enum tersebut.
401	UNAUTHORIZED Permintaan tidak memiliki kredensial otentikasi yang valid untuk operasi. Misalnya, tanda tangan yang tidak valid atau tanda tangan tidak dikenal menampilkan 401.
403	FORBIDDEN / PERMISSION DENIED Pemanggil tidak memiliki izin untuk menjalankan operasi yang ditentukan.
404	NOT FOUND Beberapa entitas yang diminta seperti pembayaran atau pengguna tidak ditemukan.
409	CONFLICT / ABORTED Operasi dibatalkan, biasanya karena masalah konkurensi seperti kegagalan pemeriksaan sequencer, pembatalan transaksi, dll.
412	PRECONDITION FAILED Kode ini harus digunakan dalam situasi saat kunci idempotency digunakan kembali dengan parameter yang berbeda.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Beberapa resource sistem telah habis.
499	CANCELLED Operasi dibatalkan (biasanya oleh pemanggil).
500	INTERNAL ERROR Error internal. Ini berarti beberapa invarian diharapkan oleh sistem dasar rusak.
501	UNIMPLEMENTED Operasi tidak diterapkan, didukung, atau diaktifkan dalam layanan ini.
503	UNAVAILABLE Saat ini layanan tidak tersedia. Kemungkinan besar ini adalah kondisi Anda dan dapat diperbaiki dengan mencoba lagi.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED Batas waktu berakhir sebelum operasi selesai. Untuk operasi yang mengubah keadaan sistem, {i>error<i} ini dapat muncul bahkan jika berhasil diselesaikan. Misalnya, respons yang berhasil dari server bisa tertunda cukup lama untuk tenggat waktu berakhir.

Meminta idempotensi

idempotency permintaan adalah strategi terpusat yang digunakan dalam Standard Payments API yang digunakan untuk memastikan bahwa interaksi sistem antara Google dan partner andal dan fault-tolerant. Permintaan idempoten adalah permintaan yang dapat berpotensi dikirim beberapa kali tetapi memiliki efek yang sama dengan satu permintaan. Strategi ini memfasilitasi konsistensi tertunda di antara sistem dengan membuat percobaan ulang yang aman, sehingga sistem kita menyatu menjadi kesepakatan pada status resource.

API kami memanfaatkan idempotency untuk:

• mengurangi masalah rekonsiliasi dengan membuat semua tindakan mudah dilacak dan dapat diaudit.
• mencegah kondisi race dengan memastikan bahwa beberapa permintaan identik dari klien yang sama tidak menghasilkan status akhir yang berbeda.
• meminimalkan status dengan mengizinkan permintaan dipahami secara terpisah, memungkinkan untuk peningkatan performa dan throughput dengan menghapus beban server yang disebabkan oleh retensi data.
• agar tidak diperlukan kolom tambahan untuk menunjukkan apakah permintaan merupakan percobaan ulang

Catatan: Hasil error tidak boleh di-cache atau ditampilkan secara idempoten. Dan, percobaan ulang otomatis untuk error harus menggunakan strategi backoff eksponensial.

Contoh

Contoh 1: Konektivitas hilang sebelum respons diterima

Skenario:

1. Google mengirimkan permintaan kepada integrator.
2. Server integrator menerima permintaan ini dan berhasil memprosesnya.
3. Server Google kehilangan daya sebelum menerima respons pada langkah #2.
4. Daya server Google dipulihkan dan permintaan yang sama dikirim dengan semua parameter yang sama (ID permintaan dan detail permintaan yang sama, tetapi diperbarui requestTimestamp) ke server integrator.

Hasil:

Dalam hal ini server integrator harus membalas dengan balasan yang sama seperti yang diberikan di langkah #2 karena semua parameter, kecuali responseTimestamp, sama. Efek samping hanya terjadi sekali, yaitu di langkah 2. Langkah 4 tidak memiliki efek samping.

Contoh 2: Permintaan dikirim ke server yang sedang menjalani pemeliharaan

Skenario:

1. Database server integrator sedang dalam pemeliharaan.
2. Google mengirimkan permintaan kepada integrator.
3. Integrator menampilkan kode status UNAVAILABLE dengan benar.
4. Server Google akan menerima respons dan menjadwalkan percobaan ulang.
5. Database server integrator kembali online.
6. Google mengirim ulang permintaan dari langkah #2 (ID permintaan dan detail permintaan yang sama tetapi memperbarui requestTimestamp). Perhatikan bahwa ID permintaan untuk kedua permintaan seharusnya sama.
7. Server integrator menerima permintaan dan mengembalikan kode status OK dengan respons lengkap.

Hasil:

Dalam hal ini, server integrator harus memproses permintaan di langkah #7 dan tidak tampilkan HTTP 503 (UNAVAILABLE). Sebaliknya, server integrator harus sepenuhnya memproses permintaan dan memunculkan OK dengan pesan yang sesuai. Perhatikan bahwa meskipun sistem UNAVAILABLE Google dapat membuat permintaan berulang yang mirip dengan langkah #2. Setiap permintaan akan menghasilkan pesan yang mirip dengan langkah #3. Terakhir, langkah #6 dan langkah #7 akan terjadi.

Contoh 3: Pesan yang dicoba lagi tidak cocok dengan pesan awal karena error pemulihan

Skenario:

1. Google mengirimkan permintaan kepada integrator.
2. Server integrator menerima permintaan ini dan berhasil memprosesnya.
3. Server Google kehilangan daya sebelum menerima respons di langkah #2.
4. Daya server Google dipulihkan dan mencoba mengirim permintaan yang sama tetapi sayangnya beberapa parameternya berbeda.

Hasil:

Dalam hal ini server integrator harus membalas dengan 412 HTTP (PRECONDITION FAILED) kode kesalahan yang menunjukkan kepada Google bahwa ada error dalam sistem ini.