API tuân theo một bộ tiêu chuẩn API HTTP và hỗ trợ không đồng đều để hỗ trợ tích hợp.
URL do Google lưu trữ
Tài liệu về mỗi phương thức do Google lưu trữ đều cung cấp một URL cơ sở. bao gồm tên phương thức và số phiên bản chính. Đã tạo URL hoàn chỉnh bằng cách thêm ID tài khoản nhà tích hợp thanh toán của người gọi vào kết thúc. Ví dụ: tài liệu về phương thức lặp lại do Google lưu trữ chỉ định URL:
https://vgw.googleapis.com/secure-serving/gsp/v1/echo
Nếu Mã tài khoản Trình tích hợp thanh toán của người gọi là INTEGRATOR_1, họ 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 về mỗi phương thức API do đối tác lưu trữ cung cấp một URL cơ sở.
bao gồm tên phương thức và số phiên bản chính. Bạn không nên đưa vào
Mã tài khoản của đơn vị tích hợp thanh toán (PIAID)
trong các URL bạn lưu trữ.
Môi trường hộp cát và môi trường thực tế
Google lưu trữ API Thanh toán tiêu chuẩn trong cả hộp cát (để phát triển và cho mục đích thử nghiệm) và sản xuất. Yêu cầu trong môi trường hộp cát của Google không phát sinh trách nhiệm tài chính nào trong thực tế. 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 luôn có sẵn vì chúng tôi sẽ sử dụng hộp cát để thử nghiệm các thay đổi và tính năng mới lần đầu tiên.
Đường dẫn cơ sở hộp cát của Google
https://vgw.sandbox.google.com/secure-serving/gsp/
Đường dẫ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 tải trọng 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ư được xác định trong
rfc4648 §5.
Các tải trọng tin nhắn 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ự thu gọn
mà 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ả yêu cầu mà máy chủ có thể xử lý. Bao gồm cả
yêu cầu đã thành công và bị từ chối xét từ khía cạnh kinh doanh hoặc
logic ứng dụng. Những yêu cầu không xử lý được không được dẫn đến
Mã trạng thái HTTP 200 vì chúng biểu thị lỗi giữa Google và
trở thành đối tác. Thay vào đó, phản hồi của API phải sử dụng trạng thái HTTP thích hợp
các mã bên dưới với đối tượng ErrorResponse không bắt buộc.
| Lỗi và lý do HTTP | |
|---|---|
| 400 |
BAD REQUEST
Ứng dụng khách chỉ định một đối số không hợp lệ. Mã lỗi này cũng có thể được trả về nếu thao tác bị từ chối do hệ thống không ở trạng thái cần thiết để thực thi thao tác. Sử dụng phương thức này nếu bạn không thể gửi lại yêu cầu cho đến khi hệ thống đạt trạng thái đã được khắc phục một cách rõ ràng. Ví dụ: nếu yêu cầu hoàn tiền không thành công do tệp tham chiếu đến một ảnh chụp không tồn tại, thử lại sẽ không thành công cho đến khi việc thu thập dữ liệu tồn tại trong hệ thống tích hợp.
|
| 401 |
UNAUTHORIZED
Yêu cầu không có thông tin xác thực hợp lệ cho hoạt động. Ví dụ: chữ ký không hợp lệ hoặc chữ ký không xác định phải trả về 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 như thanh toán hoặc người dùng. |
| 409 |
CONFLICT / ABORTED
Thao tác này đã bị huỷ, thường là do sự cố xảy ra đồ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 trường hợp khoá không xác định đang được sử dụng được sử dụng lại với các tham số khác nhau. |
| 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 phương thức gọi). |
| 500 |
INTERNAL ERROR
Lỗi nội bộ. Tức là có một số giá trị bất biến mà hệ thống cơ bản dự kiến đã bị hỏng. |
| 501 |
UNIMPLEMENTED
Thao tác chưa được triển khai, được hỗ trợ hoặc được bật trong dịch vụ này. |
| 503 |
UNAVAILABLE
Dịch vụ này hiện không dùng được. Rất có thể đây là một lỗi tạm thời tình trạng và có thể 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 toán tử thay đổi trạng thái của hệ thống, lỗi này có thể được trả về ngay cả khi đã hoàn tất thành công. Ví dụ: một phản hồi thành công từ một máy chủ có thể bị trì hoãn đủ lâu trước thời hạn hết hạn. |
Yêu cầu giá trị không đổi
Yêu cầu giá trị không thay đổi là chiến lược trọng tâm được sử dụng trong phương thức Thanh toán thông thường Các API được dùng để đảm bảo rằng các hoạt động tương tác trên hệ thống giữa Google và đối tác mạnh mẽ và chống lỗi. Yêu cầu không thay đổi giá trị là các yêu cầu có thể có thể được gửi nhiều lần nhưng vẫn có tác dụng giống như một yêu cầu duy nhất. Chiến lược này tạo điều kiện cho tính nhất quán cuối cùng giữa các hệ thống bằng cách tạo và thử lại một cách an toàn, giúp hệ thống của chúng tôi thống nhất 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 giá trị nhận dạng để:
- giảm thiểu các vấn đề điều chỉnh bằng cách giúp bạn dễ dàng truy vết mọi hành động và có thể kiểm tra.
- ngăn chặn điều kiện tranh đấu bằng cách đảm bảo rằng nhiều yêu cầu giống hệt 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 rõ các yêu cầu một cách riêng biệt, cho phép giúp cải thiện hiệu suất và thông lượng bằng cách loại bỏ tải máy chủ gây ra do giữ lại dữ liệu.
- tránh nhu cầu các trường bổ sung để 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 sẽ gửi yêu cầu đến đơ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 mất nguồn trước khi nhận được phản hồi ở bước số 2.
- Nguồn điện máy chủ của Google đã được khôi phục và cùng một yêu cầu sẽ được gửi đi
với tất cả các thông số giống nhau (cùng mã yêu cầu và thông tin chi tiết về yêu cầu nhưng được cập nhật
requestTimestamp) đến máy chủ của đối tác 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 nội dung trả lời được cung cấp tại
bước 2 vì tất cả tham số đều giống nhau, ngoại trừ responseTimestamp.
Tác dụng phụ chỉ xảy ra 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 sẽ gửi yêu cầu đến đơ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 đã hoạt động trở lại.
- Google gửi lại yêu cầu ở bước 2 (cùng một mã yêu cầu và thông tin chi tiết về yêu cầu
nhưng đã cập nhật vào
requestTimestamp). 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 sẽ hoàn toàn
hãy xử lý yêu cầu và trả về OK bằng tin nhắn thích hợp. Xin lưu ý rằng mặc dù
hệ thống là UNAVAILABLE Google có thể đưa ra các yêu cầu lặp lại tương tự như
bước 2. Mỗi yêu cầu sẽ nhận được 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ẽ xảy ra.
Ví dụ 3: Thông báo đã 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 sẽ gửi yêu cầu đến đơ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 mất nguồn trước khi nhận được phản hồi ở bước số 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, 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 sẽ trả lời bằng HTTP 412
(PRECONDITION FAILED) cho Google biết rằng có
lỗi trong hệ thống này.