API này tuân theo một bộ tiêu chuẩn API HTTP và hỗ trợ tính không thay đổi để hỗ trợ quá trình tích hợp mạnh mẽ hơn.
URL do Google lưu trữ
Tài liệu cho mỗi phương thức do Google lưu trữ cung cấp một URL cơ sở, bao gồm cả tên phương thức và số phiên bản chính. URL hoàn chỉnh được tạo bằng cách thêm Mã tài khoản của nhà tích hợp thanh toán của phương thức gọi vào cuối URL. Ví dụ: tài liệu về phương thức tiếng vang do Google lưu trữ chỉ định URL:
https://vgw.googleapis.com/secure-serving/gsp/v1/echo
Nếu mã tài khoản của Bên tích hợp thanh toán của phương thức gọi là INTEGRATOR_1, thì phương thức gọi sẽ thêm mã đó vào cuối URL để tạo thành:
https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1
URL do đối tác lưu trữ
Tài liệu cho mỗi phương thức API do đối tác lưu trữ cung cấp một URL cơ sở, trong đó có tên phương thức và số phiên bản chính. Bạn không nên đưa Mã tài khoản của đơn vị tích hợp thanh toán (PIAID) vào các URL mà bạn lưu trữ.
Hộp cát và môi trường thực tế
Google lưu trữ các API Thanh toán tiêu chuẩn trong cả hộp cát (cho mục đích phát triển và thử nghiệm) và sản xuất. Các yêu cầu trong môi trường hộp cát của Google không dẫn đến bất kỳ trách nhiệm tài chính nào trong thực tế. Môi trường hộp cát và môi trường sản xuất hoàn toàn riêng biệt và không dùng chung khoá hoặc thông tin giao dịch.
Google hy vọng hộp cát của bạn được cung cấp một cách nhất quán vì chúng tôi sẽ sử dụng hộp cát để kiểm thử các thay đổi và tính năng mới lần đầu tiên.
Đường dẫn cơ sở trong hộp cát của Google
https://vgw.sandbox.google.com/secure-serving/gsp/
Đường dẫn đến cơ sở sản xuất của Google
https://vgw.googleapis.com/secure-serving/gsp/
Hướng dẫn này sẽ sử dụng các điểm cuối thực tế.
Loại nội dung và phương thức mã hoá
Các gói dữ liệu thư sử dụng phương thức mã hoá PGP phải sử dụng loại nội dungapplication/octet-stream; charset=utf-8. Nội dung yêu cầu PGP phải được gửi bằng phương thức mã hoá base64url, như xác định trong rfc4648 §5.
Các gói dữ liệu thư sử dụng phương thức mã hoá JWE phải sử dụng loại nội dung
application/jose; charset=utf-8. Tuỳ chọn Chuyển đổi tuần tự nhỏ gọn do JWE/JWS hỗ trợ sẽ xử lý việc mã hoá cho nội dung yêu cầu cuối cùng.
Mã trạng thái HTTP
API thanh toán tiêu chuẩn được thiết kế để trả về mã trạng thái HTTP 200 cho tất cả các yêu cầu mà máy chủ có thể xử lý. Số liệu này bao gồm cả yêu cầu thành công và bị từ chối từ góc độ kinh doanh hoặc logic ứng dụng. Đừng xử lý các yêu cầu dẫn đến mã trạng thái HTTP 200 vì các yêu cầu này biểu thị lỗi giữa Google và đối tác. Thay vào đó, phản hồi API phải sử dụng mã trạng thái HTTP thích hợp bên dưới với đối tượng ErrorResponse không bắt buộc.
| Lỗi HTTP và nguyên nhân | |
|---|---|
| 400 |
BAD REQUEST
Ứng dụng chỉ định một đối số không hợp lệ. API này cũng có thể được trả về nếu hoạt động bị từ chối vì hệ thống không ở trạng thái bắt buộc để thực thi hoạt động đó. Hãy sử dụng tuỳ chọn này nếu không thể thử lại yêu cầu cho đến khi trạng thái hệ thống được khắc phục rõ ràng. Ví dụ: Nếu yêu cầu hoàn tiền không thành công vì tham chiếu đến một ảnh chụp không tồn tại, thì việc thử lại sẽ không thành công cho đến khi ảnh chụp có trong hệ thống của các trình tích hợp.
|
| 401 |
UNAUTHORIZED
Yêu cầu không có thông tin xác thực hợp lệ cho thao tác. Ví dụ: chữ ký không hợp lệ hoặc chữ ký không xác định sẽ trả về mã 401. |
| 403 |
FORBIDDEN / PERMISSION DENIED
Phương thức gọi không có quyền thực thi thao tác đã chỉ định. |
| 404 |
NOT FOUND
Không tìm thấy một số pháp nhân được yêu cầu, chẳng hạn như khoản thanh toán hoặc người dùng. |
| 409 |
CONFLICT / ABORTED
Thao tác này đã bị huỷ, thường do một vấn đề đồng thời như lỗi kiểm tra trình tự, huỷ giao dịch, v.v. |
| 412 |
PRECONDITION FAILED
Bạn nên sử dụng mã này trong các trường hợp mà khoá không thay đổi được đang được sử dụng lại với các tham số khác. |
| 429 |
RESOURCE EXHAUSTED / TOO MANY REQUESTS
Một số tài nguyên hệ thống đã hết. |
| 499 |
CANCELLED
Thao tác đã bị huỷ (thường là do người gọi). |
| 500 |
INTERNAL ERROR
Lỗi nội bộ. Điều này có nghĩa là một số bất biến dự kiến do hệ thống cơ bản thực hiện đã bị hỏng. |
| 501 |
UNIMPLEMENTED
Thao tác không được triển khai, hỗ trợ hoặc kích hoạt trong dịch vụ này. |
| 503 |
UNAVAILABLE
Dịch vụ này hiện không dùng được. Đây rất có thể là một tình trạng tạm thời và có thể được khắc phục bằng cách thử lại. |
| 504 |
GATEWAY TIMEOUT / DEADLINE EXCEEDED
Đã hết thời hạn trước khi thao tác có thể hoàn tất. Đối với các thao tác thay đổi trạng thái của hệ thống, lỗi này có thể được trả về ngay cả khi thao tác đó đã hoàn tất thành công. Ví dụ: một phản hồi thành công từ máy chủ có thể bị trì hoãn đủ lâu để hết thời hạn. |
Yêu cầu không thay đổi giá trị
Yêu cầu không xác định là một chiến lược trọng tâm dùng trong các API Thanh toán chuẩn, dùng để đảm bảo rằng các hoạt động tương tác giữa hệ thống giữa Google và các đối tác đều mạnh mẽ và dễ chịu với lỗi. Yêu cầu không thay đổi giá trị là những yêu cầu có thể được gửi nhiều lần nhưng có cùng tác dụng như một yêu cầu đơn lẻ. Chiến lược này tạo điều kiện để đạt được sự nhất quán cuối cùng giữa các hệ thống bằng cách đảm bảo tính an toàn cho các lượt thử lại, cho phép các hệ thống của chúng tôi hợp tác với nhau về trạng thái của tài nguyên.
API của chúng tôi tận dụng tính năng đặc biệt để:
- giảm bớt các vấn đề điều chỉnh bằng cách trình bày sao cho tất cả các hành động đều dễ theo dõi và kiểm tra được.
- ngăn chặn tình huống tương tranh bằng cách đảm bảo rằng nhiều yêu cầu giống nhau từ cùng một ứng dụng không dẫn đến trạng thái cuối cùng khác.
- giảm thiểu trạng thái bằng cách cho phép hiểu một cách riêng biệt các yêu cầu, giúp cải thiện hiệu suất và công suất bằng cách loại bỏ tải máy chủ do việc giữ lại dữ liệu gây ra.
- tránh trường hợp cần thêm các trường để cho biết liệu một yêu cầu có phải là một yêu cầu thử lại hay không
Ví dụ
Ví dụ 1: Mất kết nối trước khi nhận được phản hồi
Tình huống:
- Google gửi yêu cầu tới đơn vị tích hợp.
- Máy chủ tích hợp nhận được yêu cầu này và xử lý thành công.
- Máy chủ của Google bị mất nguồn trước khi nhận được phản hồi ở bước #2.
- Nguồn máy chủ của Google được khôi phục và cùng một yêu cầu được gửi với tất cả các tham số giống nhau (cùng mã yêu cầu và thông tin chi tiết yêu cầu nhưng được cập nhật
requestTimestamp) đến máy chủ của nhà tích hợp.
Kết quả:
Trong trường hợp này, máy chủ tích hợp phải trả lời bằng cùng một câu trả lời đã đưa ra ở bước 2 vì tất cả tham số (ngoại trừ responseTimestamp) đều giống nhau.
Hiệu ứng phụ chỉ xuất hiện một lần ở bước 2. Bước 4 không có tác dụng phụ.
Ví dụ 2: Yêu cầu được gửi đến một máy chủ đang được bảo trì
Tình huống:
- Cơ sở dữ liệu của máy chủ tích hợp đang ngừng hoạt động để bảo trì.
- Google gửi yêu cầu tới đơn vị tích hợp.
- Trình tích hợp trả về chính xác mã trạng thái
UNAVAILABLE. - Máy chủ của Google nhận được phản hồi và lên lịch thử lại.
- Cơ sở dữ liệu của máy chủ tích hợp đã trở lại trực tuyến.
- Google gửi lại yêu cầu từ bước 2 (cùng một mã yêu cầu và thông tin chi tiết yêu cầu nhưng cập nhật
requestTimestamp). Hãy lưu ý rằng mã yêu cầu cho cả hai yêu cầu phải giống nhau. - Máy chủ tích hợp nhận yêu cầu và trả về mã trạng thái OK cùng với phản hồi đầy đủ.
Kết quả:
Trong trường hợp này, máy chủ tích hợp phải xử lý yêu cầu ở bước #7 và không trả về HTTP 503 (UNAVAILABLE). Thay vào đó, máy chủ tích hợp phải xử lý đầy đủ yêu cầu và trả về OK kèm theo thông báo thích hợp. Xin lưu ý rằng mặc dù hệ thống là UNAVAILABLE, nhưng Google vẫn có thể thực hiện các yêu cầu lặp lại tương tự như bước #2. Mỗi yêu cầu sẽ dẫn đến một thông báo tương tự như bước #3.
Cuối cùng, bước 6 và bước 7 sẽ diễn ra.
Ví dụ 3: Thông báo được thử lại không khớp với thông báo ban đầu do lỗi khôi phục
Tình huống:
- Google gửi yêu cầu tới đơn vị tích hợp.
- Máy chủ tích hợp nhận được yêu cầu này và xử lý thành công.
- Máy chủ của Google bị mất nguồn trước khi nhận được phản hồi ở bước #2.
- Nguồn máy chủ của Google được khôi phục và cố gắng gửi cùng một yêu cầu, nhưng rất tiếc là một số tham số lại khác.
Kết quả:
Trong trường hợp này, máy chủ tích hợp phải trả lời bằng một mã lỗi HTTP 412 (PRECONDITION FAILED) cho Google biết rằng đã xảy ra lỗi trong hệ thống này.