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

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 ตัวเลือกการจัดเรียงอนุกรมแบบกะทัดรัด 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. ฐานข้อมูลของเซิร์ฟเวอร์ผู้ผสานกลับมาออนไลน์อีกครั้ง
  6. Google จะส่งคำขอจากขั้นตอนที่ 2 อีกครั้ง (รหัสคำขอและรายละเอียดคำขอเดียวกัน แต่มีการอัปเดต requestTimestamp) โปรดทราบว่ารหัสคำขอของทั้ง 2 คำขอ ควรจะเหมือนกัน
  7. เซิร์ฟเวอร์ผู้ผสานรวมจะได้รับคำขอและส่งคืนรหัสสถานะ OK พร้อมกับ พร้อมคำตอบแบบเต็ม

ผลลัพธ์:

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

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

สถานการณ์:

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

ผลลัพธ์:

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