Dưới đây là một số trường hợp sử dụng quan trọng cần xem xét, cũng như các nguyên tắc và API cần thiết để triển khai phương thức thanh toán tiền mặt của bạn.
Trường hợp sử dụng
Có một số cách sử dụng API Số tham chiếu. Tài liệu hướng dẫn này sẽ thảo luận về hai trường hợp sử dụng và hướng dẫn bạn cách triển khai các trường hợp đó.
- Tiền mặt – Người dùng thanh toán bằng tiền mặt tại một địa điểm thực tế.
- VAN – Người dùng chuyển tiền đến Số tài khoản ảo.
Tiền Mặt
Người dùng có thể mua thứ gì đó từ Google bằng cách thanh toán bằng tiền mặt tại một địa điểm thực tế, chẳng hạn như cửa hàng tiện lợi. Để xác định giao dịch, người dùng sẽ tạo số tham chiếu để mang đến cửa hàng để thanh toán. Ngoài ra, Google sẽ cho người dùng xem hướng dẫn cách hoàn tất giao dịch mua. Tốt nhất là ngay khi người dùng hoàn tất giao dịch mua, đối tác tích hợp sẽ thông báo cho Google để Google có thể phân phối sản phẩm.
Đầu mối liên hệ của bạn tại Google sẽ yêu cầu bạn cung cấp mẫu các hướng dẫn thanh toán thông thường. Bạn sẽ làm việc với người liên hệ của Google để tối ưu hoá và tinh chỉnh thông điệp.
Trải nghiệm người dùng mà Google muốn cung cấp là đơn đặt hàng của khách hàng được giao khi họ rời khỏi cửa hàng. Google dự kiến sẽ nhận được ReferenceNumberPaidNotification tại Google trong vòng 3 phút kể từ khi khách hàng thanh toán số tham chiếu. Sau khi gửi ReferenceNumberBillingNotification, đơn vị tích hợp không thể huỷ giao dịch.
Số tài khoản ảo (VAN)
Người dùng có thể thanh toán cho hàng hoá bằng tài khoản ngân hàng của họ. Google sẽ yêu cầu đối tác tích hợp một Số tài khoản ảo, trình bày số đó và thông tin hướng dẫn cho người dùng. Sau đó, người dùng sẽ sao chép số và nhập số này vào đơn đăng ký ngân hàng cùng với số tiền cần chuyển.
Đơn vị tích hợp cần xác minh rằng số tiền được chuyển khớp với số tiền trong yêu cầu referenceNumberGeneration, sau đó thông báo cho Google rằng số tham chiếu đó đã được thanh toán.
Sau khi Google nhận được ReferenceNumberPaidNotification, Google sẽ phân phối sản phẩm và đơn vị tích hợp không thể huỷ giao dịch.
Gửi tin nhắn giữa máy chủ của bạn và máy chủ của Google
Khi gửi thư giữa máy chủ của bạn và máy chủ của Google hoặc ngược lại, vui lòng thực hiện theo các nguyên tắc này.
Yêu cầu gửi đến – DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Câu trả lời đi – Base64UrlEncode(EncryptWithGooglePublicKey(request))
Yêu cầu của Google – Base64UrlEncode(EncryptWithGooglePublicKey(request))
Phản hồi của Google – DecryptWithVendorPrivateKey(Base64UrlDecode(request))
Sau đây là thư viện và mẫu PGP trong Java, cho thấy cách xử lý các yêu cầu và phản hồi.
Làm theo hành vi bất biến
Không thay đổi có nghĩa là bạn không nên tìm cách xử lý lại bất kỳ yêu cầu nào (chẳng hạn như thanh toán) đã được xử lý thành công. Thay vào đó, phản hồi cho quá trình xử lý thành công sẽ được báo cáo.
Tại sao điều này quan trọng
Google có thể thử lại một số yêu cầu để đảm bảo rằng trạng thái ở phía chúng tôi cũng giống với trạng thái ở phía nhà cung cấp. Hệ thống của bạn không nên cho rằng đây là một giao dịch khác. Do đó, tính năng giá trị đều rất quan trọng. Điều này có nghĩa là đối tác tích hợp không nên xử lý lại nội dung đã được xử lý thành công. Trong trường hợp như vậy, bạn nên gửi câu trả lời trước đó.
Cách triển khai tính năng bình thường
Nếu Google gửi lại yêu cầu thử lại, mã yêu cầu sẽ vẫn như cũ và nội dung sẽ giống nhau, nhưng dấu thời gian sẽ khác. Hãy trả lời bằng chính câu trả lời mà bạn đã gửi trước đó. Nếu phản hồi đầu tiên của bạn là 200 (Thành công), thì Google dự kiến cũng nhận được phản hồi đó với dấu thời gian khác.
Nếu phản hồi trước đó của bạn là lỗi (400 hoặc 500, v.v.), bạn nên xử lý yêu cầu đó dưới dạng yêu cầu mới, kiểm tra lại. Điều này rất hữu ích nếu máy chủ của bạn không hoạt động lần đầu tiên và việc thử lại sẽ giúp yêu cầu có thêm một cơ hội để được xử lý thành công.
Để tìm hiểu thêm, hãy xem hướng dẫn chi tiết này.
Sử dụng mã tài khoản của nhà tích hợp thanh toán (PIAID)
Khi tích hợp với Google, bạn có thể phải tích hợp với nhiều pháp nhân kinh doanh của Google. Ví dụ: Google Play là một pháp nhân, một pháp nhân khác là YouTube và một pháp nhân khác là Google Ads. Những cấu hình này sẽ liên quan đến các tài khoản người bán khác nhau để đại diện cho từng cấu hình trong số này.
Để liên kết từng pháp nhân trong Google với từng tài khoản người bán, Google sẽ cung cấp Mã tài khoản của Nhà tích hợp thanh toán (PIAID). Để xem ví dụ về API phương thức thanh toán tiền mặt, hãy tham khảo phần generateReferenceNumber. Dưới đây là một mẫu sử dụng mối liên kết này.
Để liên kết từng pháp nhân trong Google với từng tài khoản người bán, Google sẽ cung cấp Mã tài khoản của Nhà tích hợp thanh toán (PIAID). Để xem ví dụ về cách sử dụng API phương thức thanh toán tiền mặt, hãy truy cập vào generateReferenceNumber. Dưới đây là một mẫu sử dụng mối liên kết này.
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"requestTimestamp": "1502220196077"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"transactionDescription": "Google - Music",
"currencyCode": "USD",
"amount": "2000000"
}
Hãy chú ý phần được đánh dấu. Hai giá trị cần thiết ở đây là paymentIntegratorAccountId do đầu mối liên hệ của bạn tại Google cung cấp và tài khoản người bán của bạn.
Nhà tích hợp cũng có thể có các tài khoản khác nhau tuỳ theo quốc gia được cung cấp dịch vụ. Điều này có thể là do luật thuế khác nhau và những khác biệt khác giữa các quốc gia. Trong trường hợp này, hệ thống có thể tạo một PIAID khác cho từng quốc gia.
API để tích hợp
Các API sau đây xử lý việc tạo số tham chiếu và thông báo thanh toán.
Các API sau đây xử lý hoạt động chuyển tiền và thanh toán.
- RemittanceStatementNotification
- RemittanceStatementDetails
- AcceptRemittanceStatement/AcceptRemittanceStatement có nội dung sửa đổi
Bạn sẽ cần tích hợp tất cả các API ở trên để tạo số tham chiếu và thanh toán với Google.
Tạo số tham chiếu
Google sẽ gọi GenerateReferenceNumber khi bạn bắt đầu giao dịch mua. Chúng tôi mong bạn sẽ phản hồi kèm theo số tham chiếu xác định giao dịch hoặc tài khoản đó. Độ trễ dự kiến là < 3 giây.
Đối với Giao dịch bằng tiền mặt, số tham chiếu có thể dài tối đa 12 ký tự.
URL: POST https://[your basepath]/v1/generateReferenceNumber
Yêu cầu JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"requestTimestamp": "1561678470395"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"transactionDescription": "Google Play - Tester",
"currencyCode": "USD",
"amount": "10000000"
}
JSON phản hồi
{
"responseHeader": {
"responseTimestamp": "1561678947659"
},
"result": "SUCCESS",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
Java mẫu
`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`
GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);
Huỷ số tham chiếu
Google có thể chọn hủy số tham chiếu và không cho người dùng thanh toán số đó. Một ví dụ về trường hợp sử dụng là chương trình khuyến mãi đã hết hạn. Sau khi phản hồi yêu cầu này thành công, bạn phải đảm bảo rằng số tham chiếu đó không được thanh toán.
Nếu người dùng đã bắt đầu quy trình thanh toán, chẳng hạn như tra cứu số tham chiếu từ điểm bán hàng, máy chủ của bạn phải phản hồi bằng phản hồi HTTP 423 và ErrorResponse trong nội dung yêu cầu với trạng thái USER_ACTION_IN_PROGRESS.
URL: POST https://[your basepath]/v1/cancelReferenceNumber
Yêu cầu JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "51e00f16-36ba-4490-b228-0a670d202206",
"requestTimestamp": "1561678947926"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}
JSON phản hồi
{
"responseHeader": {
"responseTimestamp": "1561680406459"
},
"result": "SUCCESS"
}
referenceNumberPaidNotification
Sau khi chấp nhận khoản thanh toán và hoàn tất giao dịch, dịch vụ của bạn cần thông báo cho Google rằng giao dịch đã hoàn tất và giao sản phẩm đến người dùng. Sau khi Google nhận được thông báo này, Google kỳ vọng rằng giao dịch đã hoàn tất và không thể đặt trước.
URL điểm cuối referenceNumberPaidNotification:
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]
Yêu cầu JSON
{
"requestHeader": {
"requestTimestamp": "1561748625577",
"requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
}
},
"paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
"referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
"paymentLocation": {
"brandName": "TestMart",
"locationId": "1234"
},
"paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
"paymentTimestamp": "1561748625577"
}
JSON phản hồi
{
"responseHeader": {
"responseTimestamp": "1561748642600"
},
"result": "SUCCESS"
}
Triển khai tính năng chuyển tiền
Khi bạn đã tích hợp API cho FOP cụ thể của mình, bạn đã sẵn sàng để chuyển tiền. Phương thức chuyển tiền hoạt động như nhau đối với mọi phương thức thanh toán.
remittanceStatementNotification
Hai ngày sau khi giao dịch, Google sẽ gửi một remittanceStatementNotification chứa bản tóm tắt các giao dịch mà Google đã ghi lại vào ngày đó. Sau hai ngày kể từ khi giao dịch diễn ra, thông báo mẫu sẽ có dạng như sau:
POST https://www.integratordomain.com/v1/remittanceStatementNotification
Yêu cầu JSON
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-statement-abc",
"requestTimestamp": "1502632800000"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"remittanceStatementSummary": {
"statementDate": "1502607600000",
"billingPeriod": {
"startDate": "1502434800000",
"endDate": "1502521199000",
},
"dateDue": "1503212400000",
"currencyCode": "INR",
"totalDueByIntegrator": "1076000000",
}
}
Hãy lưu ý mối liên kết totalDueByIntegrator. Trên dòng này, bạn có thể thấy số tiền ròng mà Trình tích hợp còn nợ (tính bằng micro). Ngoài ra, ngày và loại đơn vị tiền tệ xuất hiện trong thông báo này, với kỳ thanh toán tương ứng với 00:00:00.000 và 23:59:59.999 của(các) ngày giao dịch sớm nhất và muộn nhất.
Điều chỉnh (remittanceStatementDetails)
Để đối chiếu, trình tích hợp sẽ gọi remittanceStatementDetails để lấy danh sách các sự kiện có trong remittanceStatementNotification.
Google phản hồi yêu cầu remittanceStatementDetails bằng một danh sách sự kiện được phân trang. Bạn nên gọi remittanceStatementDetails nhiều lần nếu tổng số giao dịch lớn hơn 1000. Các yêu cầu không cần phải được thực hiện tuần tự và có thể được thực hiện song song.
URL yêu cầu
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails
Nội dung yêu cầu mẫu
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "statement_detail_request_139932019",
"requestTimestamp": "1502551332087"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc",
"numberOfEvents": 4
}
Dưới đây là một đoạn trích ngắn của một phản hồi lớn hơn, mô tả hai sự kiện bắt giữ (giao dịch).
"captureEvents": [ {
{
"eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
"paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
"eventCharge": "700000000",
"eventFee": "-28000000"
},
{
"eventRequestId": "Ggghvh78200PQ3Yrpb",
"paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
"eventCharge": "800000000",
"eventFee": "-32000000"
}
}
Hãy xem remittanceStatementDetails để tìm hiểu thêm.
acceptRemittanceStatement và acceptRemittanceStatementWithModifications
Nhà tích hợp nên so sánh những sự kiện này với sự kiện mà họ đã ghi lại. Nếu có giao dịch nào không khớp hoặc bị thiếu, hãy liên hệ với Google để chúng tôi điều tra thêm. Nếu tất cả giao dịch đều trùng khớp và phí xử lý không bao gồm thuế, hãy gọi acceptRemittanceStatement. Nếu giá đã bao gồm thuế, hãy gọi acceptRemittanceStatementWithModifications.
Phương thức acceptRemittanceStatement được dùng khi không có thuế đối với các khoản phí.
Nếu bạn muốn bao gồm thuế, hãy gọi acceptRemittanceStatementWithModifications để xác định thuế suất. Nếu thuế suất của bạn thay đổi, hãy đảm bảo bạn đã cập nhật thuế suất. Sau khi acceptRemittanceStatement thành công, hãy bắt đầu chuyển khoản ngân hàng vào tài khoản Google.
URL yêu cầu cho acceptRemittanceStatement
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement
Nội dung yêu cầu mẫu
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
}
Phản hồi mẫu
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementResultCode": "SUCCESS"
}
URL yêu cầu cho acceptRemittanceStatementWithModifications
POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications
Nội dung yêu cầu mẫu
{
"requestHeader": {
"protocolVersion": {
"major": 1,
"minor": 0,
"revision": 0
},
"requestId": "0123434-abc",
"requestTimestamp": "1502545413098"
},
"paymentIntegratorAccountId": "InvisiCashUSA_USD",
"statementId": "0123434-statement-abc"
"feeToVatModification": {
"vatToFeeRatioInMicros": "150000"
}
}
Phản hồi mẫu
{
"responseHeader": {
"responseTimestamp": "1519996752221"
}
"acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}