Mã tài khoản
Mã tài khoản được gửi lại từ máy chủ của nhà tích hợp trong quy trình liên kết. Mã này được dùng để giúp Google xác định tài khoản cơ sở theo hai cách. Trước tiên, để xác định nhiều công cụ sử dụng cùng một tài khoản người dùng cơ bản để đánh giá rủi ro và hành vi gian lận. Thứ hai, tên này được nhân viên hỗ trợ dịch vụ khách hàng của Google sử dụng để xác định tài khoản này. Giá trị này phải nhận dạng duy nhất tài khoản người dùng trong các yêu cầu liên kết. Giá trị này phải không thể thay đổi được trên tài khoản cụ thể và người dùng phải nhận dạng được giá trị này.
Ví dụ: nếu nhà tích hợp sử dụng địa chỉ email cho danh tính, thì đó có thể là địa chỉ email. Tuy nhiên, nếu trình tích hợp sử dụng một địa chỉ email để đăng nhập nhưng có thể thay đổi địa chỉ đó, thì địa chỉ email này là lựa chọn không phù hợp cho mã tài khoản. Bất kể được chọn là gì, giá trị của yếu tố này phải giống nhau trong nhiều lượt liên kết có cùng một danh tính người dùng tích hợp thanh toán.
Gói ứng dụng Android (APK)
Định dạng tệp gói mà hệ điều hành Android sử dụng để phân phối và cài đặt ứng dụng dành cho thiết bị di động.
Tạo phiên bản API
Thông số kỹ thuật này hỗ trợ tạo phiên bản. Các phiên bản được hỗ trợ được định cấu hình trên máy chủ của Google. Khi chuyển từ phiên bản N sang M (trong đó M là phiên bản lớn lớn hơn N), trình tích hợp phải hỗ trợ cả N và M cho đến khi Google xác minh rằng tất cả lưu lượng truy cập đã được di chuyển sang M. Các phiên bản được xác định theo cách khác nhau dựa trên ngữ cảnh. API Android và API WebRedirect sẽ chuyển phiên bản API dưới dạng tham số vào yêu cầu. Các lệnh gọi từ máy chủ đến máy chủ sẽ truyền phiên bản này dưới dạng một phần của đường dẫn URL.
Các phiên bản không được cố định theo quy trình. Vì vậy, trong quá trình di chuyển từ N sang M, nhà tích hợp có thể thấy ảnh chụp với phiên bản M và tiền hoàn lại bằng phiên bản N cho cùng một giao dịch. Trong quá trình liên kết, đơn vị tích hợp có thể nhận được yêu cầu xác thực của phiên bản M với yêu cầu liên kết của phiên bản N.
Mã liên kết
associationID xác định mối liên kết giữa tài khoản của khách hàng và công cụ của Google. associationId rất giống với GPT. Trên thực tế, thẻ này có cùng thời gian tồn tại với GPT và có số lượng giá trị riêng biệt 1:1 đối với GPT. associationId khác với GPT về độ nhạy. GPT là một mã thông báo nhạy cảm
được dùng để thanh toán. associationId là giá trị nhận dạng công khai đại diện cho cùng một mối quan hệ, nhưng không mang tính nhạy cảm.
associationId được chuyển đến đơn vị tích hợp thanh toán trong associateAccount. Trong quá trình xác thực lại, giá trị này sẽ được chuyển đến trình tích hợp. Điều này cho phép trình tích hợp nắm được ngữ cảnh về những tài khoản cần được xác thực. Nếu bạn truyền mã liên kết vào, thì chính tài khoản đã được xác định trong quá trình liên kết ban đầu phải được điền trước và xác thực.
Trình tích hợp thanh toán dự kiến sẽ lưu trữ tất cả mã liên kết và liên kết các mã đó với một tài khoản tích hợp cụ thể trong suốt thời gian hợp đồng giữa đơn vị tích hợp và Google.
Id yêu cầu xác thực
Các phương thức refreshToken, associateAccount và chụp ảnh (không bắt buộc) sẽ tham chiếu đến một quy trình xác thực. Thông tin tham chiếu này có dạng requestId của phương thức xác thực cụ thể mà Google đang tham chiếu đến. Trường này được đơn vị tích hợp thanh toán sử dụng để xác minh rằng phương thức thực sự đã được tiến hành thông qua quy trình xác thực thành công.
Các phương thức chụp có thể được điền sẵn requestId xác thực. Điều này xảy ra trong hai trường hợp. Nếu Google xác thực người dùng ngay trước khi chụp, thì Google sẽ điền vào trường requestId xác thực. Ngoài ra, Google thường xác thực người dùng tại thời điểm thiết lập khi lịch thanh toán tự động được thiết lập. Google ghi requestId xác thực theo lịch biểu đó và gửi requestId cùng với mọi lần chụp được liên kết với lịch biểu cụ thể đó.
Các nhà tích hợp thanh toán dự kiến sẽ lưu trữ tất cả requestIds xác thực trong 30 ngày. Nếu nhà tích hợp thanh toán muốn kiểm tra requestIds xác thực có thể có trong yêu cầu thu thập, bao gồm cả những yêu cầu có trong lịch thanh toán, thì đơn vị tích hợp phải lưu trữ tất cả requestId xác thực trong suốt thời gian hoạt động của hợp đồng giữa nhà tích hợp và Google.
Công ty
Công ty là một khái niệm được định nghĩa trong cấu hình và hợp đồng của Google. Một công ty xác định mối quan hệ giữa đơn vị tích hợp và Google. Khoá PGP và (không bắt buộc) CA gốc SSL được liên kết với công ty. Quan trọng nhất là một công ty được liên kết với một hoặc nhiều mã tài khoản của bên tích hợp thanh toán. GPT tạo trong một công ty chủ yếu hoạt động với tất cả mã tài khoản của đơn vị tích hợp thanh toán trong công ty. Có áp dụng một số ngoại lệ. Ví dụ: nếu GPT được liên kết với một tài khoản có đơn vị tiền tệ bằng một đơn vị tiền tệ (và không hỗ trợ phí FX) và đang cố gắng thực hiện giao dịch mua trên mã tài khoản của đơn vị tích hợp thanh toán bằng một đơn vị tiền tệ khác.
Phương thức thanh toán (FOP)
Tất cả giao dịch bao gồm một hoặc nhiều phương thức thanh toán (FOP), chẳng hạn như thẻ tín dụng hoặc Chuyển khoản điện tử, được người dùng sử dụng để thanh toán cho Google đối với các sản phẩm hoặc dịch vụ hoặc để Google thanh toán cho người dùng trong trường hợp người dùng AdSense và nhà phát triển Google Play. Các phương thức thanh toán còn thường được gọi là Phương thức thanh toán, Phương thức thanh toán và Phương thức thanh toán.
Mã thông báo thanh toán của Google (GPT)
GPT là một giá trị được mã hoá base64 ngẫu nhiên, an toàn cho web do máy chủ Google tạo ra tại thời điểm liên kết và được chuyển tới máy chủ tích hợp. GPT là một giá trị nhận dạng riêng tư thể hiện mối liên kết giữa tài khoản của người dùng với trình tích hợp và công cụ của Google. GPT là một mã thông báo thay thế thông tin xác thực người dùng hoặc mã tài khoản. Mã thông báo này được sử dụng trong quy trình mua để xác định tài khoản cần ghi có hoặc ghi nợ và là thông tin bí mật đối với cả hai bên. GPT tuyệt đối không được gửi ở dạng văn bản rõ ràng và phải được mã hoá để đảm bảo quyền riêng tư.
GPT khác với associationId vì associationId không được bảo vệ và được chuyển tự do qua các phương tiện công khai (URL, kết nối không an toàn). Chỉ Google và đơn vị tích hợp mới biết đến GPT.
Đơn vị tích hợp thanh toán dự kiến sẽ lưu trữ tất cả GPTS và liên kết các GPT đó với một tài khoản tích hợp cụ thể trong suốt thời gian của hợp đồng giữa đơn vị tích hợp và Google.
Tính không xác định
Một thao tác không thay đổi giá trị có thể được áp dụng nhiều lần mà không thay đổi kết quả hoặc có tác dụng phụ mới ngoài lần áp dụng ban đầu của thao tác đó. Thông thường, tính năng không thể thay đổi sẽ sử dụng "khoá" để xác định cùng một yêu cầu. Mọi yêu cầu được xác định giữa hai máy chủ đều sử dụng một khoá không thay đổi (idempotency key) được xác định trong tiêu đề của yêu cầu. Tiêu đề yêu cầu có một mã yêu cầu được dùng làm khoá không thay đổi giá trị nhận dạng. Mã yêu cầu là duy nhất trên toàn hệ thống. Các yêu cầu không thay đổi giá trị (Idempotent) phải giống hệt với nội dung JSON với một ngoại lệ. requestTimestamp sẽ khác nhau đối với mỗi yêu cầu. Đây là điểm khác biệt quan trọng. requestTimestamp là thời gian mà máy chủ gửi yêu cầu này. Và là duy nhất cho mỗi lần thử. Điều này giúp giảm khả năng xảy ra các cuộc tấn công phát lại.
Tương tự, một phản hồi không thay đổi phải giống hệt như nội dung JSON, ngoại trừ responseTimestamp sẽ khác nhau đối với mỗi phản hồi.
Tất cả các phương thức từ máy chủ đến máy chủ ngoại trừ phương thức Echo phải giống nhau. Các yêu cầu xác thực đối với giao diện người dùng của trình tích hợp (cho dù là Android hay Web) không thay đổi.
Để biết ví dụ về hành vi không thay đổi, hãy xem tài liệu tham khảo.
Giá trị nhận dạng (mã nhận dạng)
Giá trị nhận dạng thể hiện một giao dịch hoặc hoạt động giao tiếp giữa nhà tích hợp thanh toán và Google.
Công cụ
Công cụ này đại diện cho một phương thức thanh toán đã lưu trữ được liên kết với một khách hàng của Google. Ví dụ về các công cụ bao gồm:
- Số thẻ tín dụng trong hồ sơ
- Tài khoản ngân hàng và số định tuyến
Người dùng có thể có nhiều công cụ được liên kết với danh tính Google của họ.
Cực nhỏ
Giá trị tiền tệ trong API này được biểu thị bằng định dạng "micrô", một tiêu chuẩn tại Google. Micros là một định dạng dựa trên số nguyên, chính xác cố định. Để biểu thị giá trị tiền tệ bằng phần triệu, hãy nhân giá trị tiền tệ tiêu chuẩn với 1.000.000.
Ví dụ:
- 1,23 USD = 1230000 micro USD
- 0,01 USD = 10.000 micro USD
Bên tích hợp thanh toán
Đơn vị tích hợp bên ngoài xử lý các khoản thanh toán cho giao dịch của người dùng.
ID tài khoản của đơn vị tích hợp thanh toán
Giá trị nhận dạng này thể hiện các quy tắc ràng buộc liên quan đến hợp đồng giữa Google và đơn vị tích hợp. Mã tài khoản trình tích hợp do Google tạo và được chỉ định cho trình tích hợp trong thời gian thiết lập. Thông thường, sự kiện này được gọi là "MID". Tất cả các yêu cầu và phản hồi phải bao gồm mã nhận dạng này. Giá trị nhận dạng này không rõ ràng và không bao giờ được phân tích cú pháp. Định dạng của giá trị nhận dạng này có thể không nhất quán trên tất cả các giấy tờ tuỳ thân được cấp.
Giá trị nhận dạng này không bao giờ thay đổi trong suốt thời gian của một giao dịch. Trong trường hợp chụp và hoàn tiền, cùng một giá trị nhận dạng sẽ được sử dụng.
Các quy tắc ràng buộc của Mã tài khoản nhà tích hợp được xác định theo chính hợp đồng. Nhìn chung, những hạn chế xoay quanh việc lập hóa đơn. Ví dụ: một nhà tích hợp hỗ trợ CAD và MXN được lập hoá đơn bằng USD nhưng yêu cầu lập hoá đơn giao dịch EUR bằng EUR. Trong trường hợp này, hai mã tài khoản khác nhau của nhà tích hợp thanh toán sẽ được sử dụng, một mã để lập hoá đơn bằng USD và một mã để lập hoá đơn EUR.
Giá trị nhận dạng có thể bị loại bỏ và thay vào đó là giá trị nhận dạng mới. Trong trường hợp
một giá trị nhận dạng không được dùng nữa, Google sẽ ngừng bắt đầu quá trình thu thập
giá trị nhận dạng đó. Tuy nhiên, trình tích hợp phải chấp nhận hoàn tiền cho các giao dịch được thực hiện dựa trên giá trị nhận dạng đó trong một năm kể từ lần bắt đầu thu thập gần đây nhất (thực hiện thu thập được xác định là requestTimestamp có trong requestHeader).
PII (Thông tin nhận dạng cá nhân)
Thông tin nhận dạng cá nhân (PII) là thông tin nhận dạng cá nhân một cá nhân và mọi dữ liệu khác mà Google có thể liên kết một cách hợp lý với thông tin đó, chẳng hạn như tên, địa chỉ email, địa chỉ gửi thư hoặc số điện thoại của người dùng, ở một cách riêng lẻ hoặc kết hợp
ID yêu cầu
requestId xác định mọi hoạt động liên lạc giữa Google và bên tích hợp thanh toán.
SPII (thông tin nhạy cảm có thể nhận dạng cá nhân)
Thông tin nhận dạng cá nhân (SPII) nhạy cảm là một tập hợp con thông tin nhận dạng cá nhân (PII) gây rủi ro cao cho người dùng nếu thông tin đó bị xâm phạm hoặc sử dụng sai mục đích. SPII thường có các yêu cầu hạn chế về việc xử lý và lưu trữ do các pháp nhân, cơ quan quản lý hoặc pháp nhân tuân thủ đặt ra.
Mã thông báo
Mã thông báo bổ sung một lớp bảo mật khi Google và đơn vị tích hợp trao đổi thông tin xác thực nhạy cảm như PII (Thông tin nhận dạng cá nhân) hoặc SPII (SPII).
Địa chỉ người dùng
Tại thời điểm tạo công cụ, Google sẽ kiểm tra xem người dùng có phải là khách hàng Google Payments hay không. Điều này độc lập với việc là khách hàng của Google. Để trở thành khách hàng của Google Payments, chúng tôi cần có địa chỉ thanh toán của người dùng. Một số cơ quan quản lý yêu cầu chúng tôi biết địa chỉ đầy đủ của người dùng, trong khi các cơ quan khác yêu cầu một tập hợp con địa chỉ đó.
Nếu bên tích hợp thanh toán có địa chỉ trong hồ sơ của người dùng này, thì Google muốn lấy địa chỉ đó trong quy trình liên kết để điền trước vào biểu mẫu địa chỉ cho người dùng đó. Người dùng có thể thay đổi địa chỉ được điền sẵn trong trường. Việc điền sẵn địa chỉ người dùng giúp giảm bớt phiền hà trong việc thêm một công cụ và tăng tỷ lệ chuyển đổi của những người dùng thêm các công cụ này.
Nếu địa chỉ được chia sẻ, Google cũng sẽ sử dụng địa chỉ đó dưới dạng phép tính vào mô hình rủi ro của họ. Điều này giúp công cụ xác định rủi ro của Google hiểu được địa chỉ mà người dùng nói rằng họ được tính phí trong khi so sánh địa chỉ đó với vị trí IP của người dùng.
Chia sẻ địa chỉ chỉ đơn thuần là tối ưu hoá. Không có vấn đề gì khi một số nhà tích hợp sẽ không có địa chỉ thanh toán cho người dùng hoặc không thể chia sẻ địa chỉ này.
Mã hoá Base64 an toàn trên web
Tiêu chuẩn mã hoá được chỉ định trong RFC 4648 mục 5, Mã hoá cơ sở 64 bằng URL và Bảng chữ cái an toàn tên tệp, đôi khi còn được gọi là mã hoá "Base64 an toàn trên web" hoặc "base64url". (Phương thức này giống với phương thức mã hoá base64 bằng URL và bảng chữ cái an toàn cho tên tệp từ mục 4 của RFC 3548.) Tất cả các giá trị đã mã hoá và đã ký phải được mã hoá bằng tiêu chuẩn này.