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: การเชื่อมต่อขาดหายก่อนได้รับคำตอบ
สถานการณ์:
- Google จะส่งคำขอไปยังผู้ผสานการทำงาน
- เซิร์ฟเวอร์ผู้ผสานการทำงานได้รับคำขอนี้และประมวลผลได้สำเร็จ
- เซิร์ฟเวอร์ของ Google สูญเสียพลังงานไฟฟ้าก่อนที่จะได้รับการตอบกลับในขั้นตอนที่ 2
- ระบบจะกู้คืนพลังงานเซิร์ฟเวอร์ของ Google และส่งคำขอเดียวกันที่มีพารามิเตอร์เดียวกันทั้งหมด (รหัสคำขอและรายละเอียดคำขอเดียวกัน แต่อัปเดต
requestTimestamp
) ไปยังเซิร์ฟเวอร์ของผู้ผสานการทำงาน
ผลลัพธ์:
ในกรณีนี้ เซิร์ฟเวอร์ผู้ผสานการทำงานระบบต้องตอบกลับด้วยคำตอบเดียวกันในขั้นตอนที่ 2 เนื่องจากพารามิเตอร์ทั้งหมด ยกเว้น responseTimestamp
เหมือนกัน
เกิดผลข้างเคียงเพียงครั้งเดียวในขั้นตอนที่ 2 ขั้นตอนที่ 4 จะไม่เกิดผลข้างเคียง
ตัวอย่างที่ 2: ส่งคำขอไปยังเซิร์ฟเวอร์ที่กำลังมีการบำรุงรักษา
สถานการณ์:
- ฐานข้อมูลของเซิร์ฟเวอร์ผู้รวมอยู่ระหว่างการบำรุงรักษา
- Google จะส่งคำขอไปยังผู้ผสานการทำงาน
- ตัวรวมแสดงรหัสสถานะ
UNAVAILABLE
อย่างถูกต้อง - เซิร์ฟเวอร์ของ Google จะได้รับการตอบกลับและกำหนดเวลาการลองอีกครั้ง
- ฐานข้อมูลของเซิร์ฟเวอร์ Integrator จะกลับมาออนไลน์อีกครั้ง
- Google ส่งคำขออีกครั้งจากขั้นตอนที่ 2 (รหัสคำขอและรายละเอียดคำขอเดียวกัน แต่อัปเดต
requestTimestamp
) โปรดทราบว่ารหัสคำขอของทั้ง 2 คำขอต้องเหมือนกัน - เซิร์ฟเวอร์ผู้รวมได้รับคำขอและส่งคืนรหัสสถานะ OK พร้อมการตอบกลับแบบเต็ม
ผลลัพธ์:
ในกรณีนี้ เซิร์ฟเวอร์ผู้ผสานการทำงานต้องประมวลผลคำขอในขั้นตอนที่ 7 และไม่แสดงผล HTTP 503
(UNAVAILABLE
) แต่เซิร์ฟเวอร์ผู้ผสานการทำงานควรประมวลผลคำขออย่างเต็มรูปแบบและแสดงคำขอ "ตกลง" พร้อมข้อความที่เหมาะสม โปรดทราบว่าในขณะที่ระบบคือ UNAVAILABLE
แต่ Google อาจส่งคำขอซ้ำที่คล้ายกับขั้นตอนที่ 2 คำขอแต่ละรายการควรแสดงข้อความคล้ายกับขั้นตอนที่ 3
สุดท้ายแล้วขั้นตอนที่ 6 และขั้นตอนที่ 7 จะเกิดขึ้น
ตัวอย่างที่ 3: ข้อความที่ลองใหม่ไม่ตรงกับข้อความเริ่มต้นเนื่องจากเกิดข้อผิดพลาดในการกู้คืน
สถานการณ์:
- Google จะส่งคำขอไปยังผู้ผสานการทำงาน
- เซิร์ฟเวอร์ผู้ผสานการทำงานได้รับคำขอนี้และประมวลผลได้สำเร็จ
- เซิร์ฟเวอร์ของ Google สูญเสียพลังงานไฟฟ้าก่อนที่จะได้รับการตอบกลับในขั้นตอนที่ 2
- กำลังเรียกคืนการทำงานของเซิร์ฟเวอร์ของ Google และพยายามส่งคำขอเดียวกัน แต่ทั้งนี้พารามิเตอร์บางตัวแตกต่างกัน
ผลลัพธ์:
ในกรณีนี้ เซิร์ฟเวอร์ผู้ผสานการทำงานควรตอบกลับด้วยรหัสข้อผิดพลาด HTTP 412
(PRECONDITION FAILED
) ซึ่งแสดงให้ Google ทราบว่ามีข้อผิดพลาดในระบบนี้