โปรโตคอลมาตรฐาน

API นี้ปฏิบัติตามชุดมาตรฐาน HTTP API และรองรับ idempotency เพื่ออำนวยความสะดวกในการผสานรวมที่มีประสิทธิภาพยิ่งขึ้น

URL ที่ Google โฮสต์

เอกสารประกอบสำหรับแต่ละเมธอดที่โฮสต์โดย Google จะมี URL ฐาน ซึ่งมีชื่อเมธอดและหมายเลขเวอร์ชันหลัก ระบบจะสร้าง URL ที่สมบูรณ์ด้วยการใส่รหัสบัญชีผู้รวมการชำระเงินของผู้โทรต่อท้าย ตัวอย่างเช่น เอกสารประกอบสำหรับวิธีการสะท้อนกลับที่โฮสต์โดย Google จะระบุ URL ดังนี้

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

หากรหัสบัญชีของผู้รวมการชำระเงินคือ INTEGRATOR_1 ผู้โทรจะต้องเพิ่มรหัสต่อท้าย URL เพื่อสร้างแบบฟอร์ม ดังนี้

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

URL ที่พาร์ทเนอร์โฮสต์

เอกสารประกอบสำหรับเมธอด API ที่โฮสต์ของพาร์ทเนอร์แต่ละรายการจะมี URL ฐาน ซึ่งประกอบด้วยชื่อเมธอดและหมายเลขเวอร์ชันหลัก คุณไม่ควรใส่รหัสบัญชีผู้รวมการชำระเงิน (PIAID) ใน URL ที่โฮสต์

แซนด์บ็อกซ์และสภาพแวดล้อมการใช้งานจริง

Google โฮสต์ Standard Payments API ทั้งในแซนด์บ็อกซ์ (เพื่อการพัฒนาและทดสอบ) และเวอร์ชันที่ใช้งานจริง คำขอในสภาพแวดล้อมแซนด์บ็อกซ์ของ Google จะไม่ส่งผลให้เกิดความรับผิดทางการเงินใดๆ ในชีวิตจริง สภาพแวดล้อมแซนด์บ็อกซ์และเวอร์ชันที่ใช้งานจริงจะแยกกันอย่างสิ้นเชิง และไม่มีการแชร์คีย์หรือข้อมูลธุรกรรม

Google คาดว่าแซนด์บ็อกซ์ของคุณจะพร้อมใช้งานได้อย่างต่อเนื่อง เนื่องจากเราจะใช้แซนด์บ็อกซ์เพื่อทดสอบการเปลี่ยนแปลงและฟีเจอร์ใหม่ๆ ก่อน

เส้นทางฐานแซนด์บ็อกซ์ของ Google

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

เส้นทางฐานการผลิตของ Google

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

คู่มือนี้จะใช้ปลายทางที่ใช้งานจริง

ประเภทเนื้อหาและการเข้ารหัส

เพย์โหลดข้อความที่ใช้การเข้ารหัส PGP ต้องใช้ประเภทเนื้อหา application/octet-stream; charset=utf-8 ต้องส่งคำขอ PGP โดยใช้การเข้ารหัส base64url ตามที่ระบุไว้ใน rfc4648 §5 เพย์โหลดข้อความที่ใช้การเข้ารหัส JWE ต้องใช้เนื้อหาประเภท application/jose; charset=utf-8 ตัวเลือก Compact Serialization ที่ JWE/JWS รองรับจะจัดการการเข้ารหัสสำหรับเนื้อหาคำขอสุดท้าย

รหัสสถานะ HTTP

API การชำระเงินมาตรฐานออกแบบมาเพื่อแสดงรหัสสถานะ HTTP 200 สำหรับคำขอทั้งหมดที่เซิร์ฟเวอร์ประมวลผลได้ ซึ่งรวมทั้งคำขอที่สำเร็จและถูกปฏิเสธจากมุมมองของธุรกิจหรือแอปพลิเคชัน คำขอที่ประมวลผลไม่ได้ไม่ควรส่งผลให้มีรหัสสถานะ HTTP 200 เนื่องจากคำขอเหล่านั้นแสดงถึงข้อผิดพลาดระหว่าง Google และพาร์ทเนอร์ การตอบกลับของ API ควรใช้รหัสสถานะ HTTP ที่เหมาะสมด้านล่างกับออบเจ็กต์ ErrorResponse ที่ไม่บังคับแทน

ข้อผิดพลาดและเหตุผลของ HTTP
400 BAD REQUEST

ไคลเอ็นต์ระบุอาร์กิวเมนต์ไม่ถูกต้อง

ซึ่งอาจแสดงผลหากการดำเนินการถูกปฏิเสธเนื่องจากระบบไม่อยู่ในสถานะที่จำเป็นสำหรับการดำเนินการ

ใช้ตัวเลือกนี้หากการส่งคำขอซ้ำไม่สำเร็จจนกว่าจะมีการแก้ไขสถานะของระบบอย่างชัดเจน ตัวอย่างเช่น หากคำขอเงินคืนไม่สำเร็จเนื่องจากอ้างอิงการจับภาพที่ไม่มีอยู่ การลองอีกครั้งจะไม่สำเร็จจนกว่าจะมีข้อมูลบันทึกอยู่ในระบบผู้ผสานการทำงานระบบ

401 UNAUTHORIZED

คำขอไม่มีข้อมูลเข้าสู่ระบบการตรวจสอบสิทธิ์ที่ถูกต้องสำหรับการดำเนินการ เช่น ลายเซ็นที่ไม่ถูกต้องหรือลายเซ็นที่ไม่รู้จักควรแสดงผล 401

403 FORBIDDEN / PERMISSION DENIED

ผู้โทรไม่มีสิทธิ์ดำเนินการที่ระบุ

404 NOT FOUND

ไม่พบเอนทิตีที่ขอบางรายการ เช่น การชำระเงินหรือผู้ใช้

409 CONFLICT / ABORTED

ระบบล้มเลิกการดำเนินการ ซึ่งมักเกิดจากปัญหาการเกิดขึ้นพร้อมกัน เช่น การตรวจสอบตัวจัดลำดับไม่สำเร็จ ล้มเลิกธุรกรรม ฯลฯ

412 PRECONDITION FAILED

ควรใช้โค้ดนี้ในกรณีที่มีการใช้คีย์ประจำตัวซ้ำด้วยพารามิเตอร์ที่ต่างกัน

429 RESOURCE EXHAUSTED / TOO MANY REQUESTS

ทรัพยากรของระบบบางรายการหมดแล้ว

499 CANCELLED

การดำเนินการถูกยกเลิก (โดยปกติแล้วจะเป็นผู้โทร)

500 INTERNAL ERROR

ข้อผิดพลาดภายใน ซึ่งหมายความว่าค่าผันแปรบางรายการที่ระบบที่สำคัญพื้นฐานทำงานขัดข้อง

501 UNIMPLEMENTED

บริการนี้ไม่มีการใช้งาน สนับสนุน หรือเปิดใช้การดำเนินการนี้

503 UNAVAILABLE

ไม่พร้อมให้บริการนี้ในขณะนี้ ปัญหานี้อาจเกิดขึ้นชั่วคราวและอาจแก้ไขได้ด้วยการลองอีกครั้ง

504 GATEWAY TIMEOUT / DEADLINE EXCEEDED

กำหนดเวลาหมดอายุก่อนที่การดำเนินการจะเสร็จสิ้น สำหรับการดำเนินการที่เปลี่ยนสถานะของระบบ ระบบอาจแสดงผลข้อผิดพลาดนี้แม้ว่าการดำเนินการจะเสร็จสมบูรณ์แล้วก็ตาม เช่น การตอบสนองที่สําเร็จจากเซิร์ฟเวอร์อาจล่าช้านานพอที่กําหนดกําลังจะหมดอายุ

คำขอข้อมูลประจำตัว

การมีคำขอชั่วคราวเป็นกลยุทธ์หลักที่ใช้ใน API การชำระเงินมาตรฐานซึ่งใช้เพื่อให้แน่ใจว่าการโต้ตอบของระบบระหว่าง Google กับพาร์ทเนอร์นั้นมีประสิทธิภาพและทนทานต่อความผิดพลาด คำขอแบบเป็นนิจพลคือคำขอที่ส่งได้หลายครั้ง แต่จะมีผลเช่นเดียวกับคำขอเดียว กลยุทธ์นี้ช่วยให้ระบบมีความสอดคล้องกันในที่สุด โดยทำให้การลองใหม่มีความปลอดภัย ทำให้ระบบของเราสามารถประสานงานกันเกี่ยวกับสถานะของทรัพยากรได้

API ของเราใช้ประโยชน์จากความมีเอกลักษณ์เพื่อดำเนินการต่อไปนี้

  • ช่วยลดปัญหาการปรับยอดโดยการทำให้การดำเนินการทั้งหมดตรวจสอบย้อนกลับและตรวจสอบได้ง่าย
  • จะป้องกันเงื่อนไขการแข่งขันโดยตรวจสอบให้แน่ใจว่าคำขอที่เหมือนกันหลายรายการจากลูกค้าเดียวกันไม่ได้ส่งผลให้มีสถานะสุดท้ายแตกต่างกัน
  • ลดสถานะโดยอนุญาตให้เข้าใจคำขอแยกต่างหาก ซึ่งจะเพิ่มประสิทธิภาพและอัตราการส่งข้อมูลโดยนำภาระงานของเซิร์ฟเวอร์ที่เกิดจากการเก็บรักษาข้อมูลออก
  • ไม่จำเป็นต้องใช้ช่องเพิ่มเติมเพื่อระบุว่าเป็นคำขอลองอีกครั้งหรือไม่

ตัวอย่าง

ตัวอย่างที่ 1: การเชื่อมต่อขาดหายก่อนได้รับคำตอบ

สถานการณ์:

  1. Google จะส่งคำขอไปยังผู้ผสานการทำงาน
  2. เซิร์ฟเวอร์ผู้ผสานการทำงานได้รับคำขอนี้และประมวลผลได้สำเร็จ
  3. เซิร์ฟเวอร์ของ Google สูญเสียพลังงานไฟฟ้าก่อนที่จะได้รับการตอบกลับในขั้นตอนที่ 2
  4. ระบบจะกู้คืนพลังงานเซิร์ฟเวอร์ของ Google และส่งคำขอเดียวกันที่มีพารามิเตอร์เดียวกันทั้งหมด (รหัสคำขอและรายละเอียดคำขอเดียวกัน แต่อัปเดต requestTimestamp) ไปยังเซิร์ฟเวอร์ของผู้ผสานการทำงาน

ผลลัพธ์:

ในกรณีนี้ เซิร์ฟเวอร์ผู้ผสานการทำงานระบบต้องตอบกลับด้วยคำตอบเดียวกันในขั้นตอนที่ 2 เนื่องจากพารามิเตอร์ทั้งหมด ยกเว้น responseTimestamp เหมือนกัน เกิดผลข้างเคียงเพียงครั้งเดียวในขั้นตอนที่ 2 ขั้นตอนที่ 4 จะไม่เกิดผลข้างเคียง

ตัวอย่างที่ 2: ส่งคำขอไปยังเซิร์ฟเวอร์ที่กำลังมีการบำรุงรักษา

สถานการณ์:

  1. ฐานข้อมูลของเซิร์ฟเวอร์ผู้รวมอยู่ระหว่างการบำรุงรักษา
  2. Google จะส่งคำขอไปยังผู้ผสานการทำงาน
  3. ตัวรวมแสดงรหัสสถานะ UNAVAILABLE อย่างถูกต้อง
  4. เซิร์ฟเวอร์ของ Google จะได้รับการตอบกลับและกำหนดเวลาการลองอีกครั้ง
  5. ฐานข้อมูลของเซิร์ฟเวอร์ Integrator จะกลับมาออนไลน์อีกครั้ง
  6. Google ส่งคำขออีกครั้งจากขั้นตอนที่ 2 (รหัสคำขอและรายละเอียดคำขอเดียวกัน แต่อัปเดต requestTimestamp) โปรดทราบว่ารหัสคำขอของทั้ง 2 คำขอต้องเหมือนกัน
  7. เซิร์ฟเวอร์ผู้รวมได้รับคำขอและส่งคืนรหัสสถานะ OK พร้อมการตอบกลับแบบเต็ม

ผลลัพธ์:

ในกรณีนี้ เซิร์ฟเวอร์ผู้ผสานการทำงานต้องประมวลผลคำขอในขั้นตอนที่ 7 และไม่แสดงผล HTTP 503 (UNAVAILABLE) แต่เซิร์ฟเวอร์ผู้ผสานการทำงานควรประมวลผลคำขออย่างเต็มรูปแบบและแสดงคำขอ "ตกลง" พร้อมข้อความที่เหมาะสม โปรดทราบว่าในขณะที่ระบบคือ UNAVAILABLE แต่ Google อาจส่งคำขอซ้ำที่คล้ายกับขั้นตอนที่ 2 คำขอแต่ละรายการควรแสดงข้อความคล้ายกับขั้นตอนที่ 3 สุดท้ายแล้วขั้นตอนที่ 6 และขั้นตอนที่ 7 จะเกิดขึ้น

ตัวอย่างที่ 3: ข้อความที่ลองใหม่ไม่ตรงกับข้อความเริ่มต้นเนื่องจากเกิดข้อผิดพลาดในการกู้คืน

สถานการณ์:

  1. Google จะส่งคำขอไปยังผู้ผสานการทำงาน
  2. เซิร์ฟเวอร์ผู้ผสานการทำงานได้รับคำขอนี้และประมวลผลได้สำเร็จ
  3. เซิร์ฟเวอร์ของ Google สูญเสียพลังงานไฟฟ้าก่อนที่จะได้รับการตอบกลับในขั้นตอนที่ 2
  4. กำลังเรียกคืนการทำงานของเซิร์ฟเวอร์ของ Google และพยายามส่งคำขอเดียวกัน แต่ทั้งนี้พารามิเตอร์บางตัวแตกต่างกัน

ผลลัพธ์:

ในกรณีนี้ เซิร์ฟเวอร์ผู้ผสานการทำงานควรตอบกลับด้วยรหัสข้อผิดพลาด HTTP 412 (PRECONDITION FAILED) ซึ่งแสดงให้ Google ทราบว่ามีข้อผิดพลาดในระบบนี้