Hướng dẫn về phương thức thanh toán bằng tiền mặt (API Số tham chiếu AKA)

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 bằng tiền mặt.

Trường hợp sử dụng

Có một số cách sử dụng API Số tham chiếu. Hướng dẫn này sẽ thảo luận về hai trường hợp sử dụng và trình bày 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 cho Số tài khoản ảo.

Tiền mặt

Người dùng có thể mua sản phẩm nào đó 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 một số tham chiếu để mang đến cửa hàng để thanh toán. Ngoài ra, Google sẽ hiển thị hướng dẫn cho người dùng về cách hoàn tất giao dịch mua. Tốt nhất là ngay sau khi người dùng hoàn tất giao dịch mua hàng, đơn vị tích hợp sẽ thông báo cho Google để Google có thể giao 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 báo.

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 ngay 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 ReferenceNumberpaidNotification, nhà tích hợp không thể đảo ngược 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. Google sẽ yêu cầu đơn vị tích hợp cung cấp Số tài khoản ảo, đồng thời trình bày số này và 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 ứng dụng 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 nhận được ReferenceNumberPaidNotification, Google sẽ phân phối sản phẩm và đơn vị tích hợp không thể đảo ngược 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.

Theo dõi hành vi không thay đổi

Không có giá trị có nghĩa là bạn không nên cố gắng xử lý lại bất kỳ yêu cầu nào (chẳng hạn như khoản thanh toán) đã được xử lý thành công. Phản hồi cho quá trình xử lý thành công sẽ được báo cáo thay thế.

Tầm 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 bên phía chúng tôi giống với trạng thái bên phía nhà cung cấp. Hệ thống của bạn không nên nghĩ rằng đây là một giao dịch khác. Do đó, tính đồng nhất là rất quan trọng. Điều này có nghĩa là trình tích hợp không nên xử lý lại những nội dung đã được xử lý thành công. Trong trường hợp như vậy, phản hồi trước đó sẽ được gửi thay thế.

Cách triển khai Tính năng thay thế

Nếu Google gửi một lần thử lại, mã yêu cầu sẽ không đổi và nội dung vẫn như cũ, nhưng dấu thời gian sẽ khác. Trả lời bằng cùng một nội dung phản hồi 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 sẽ nhận được phản hồi tương tự nhưng có 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 trong lần đầu tiên và việc thử lại để 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 đơn vị tích hợp thanh toán (PIAID)

Việc tích hợp với Google có thể yêu cầu bạn phải tích hợp với nhiều công ty con 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. Các chế độ cài đặt này sẽ có các tài khoản người bán khác nhau đại diện cho từng chế độ thiết lập đó.

Để 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 cung cấp Mã tài khoản của đơn vị tích hợp thanh toán (PIAID). Để biết ví dụ về API FOP bằng tiền mặt, hãy xem generateReferenceNumber. Dưới đây là 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 cung cấp Mã tài khoản của đơn vị tích hợp thanh toán (PIAID). Để xem ví dụ về cách sử dụng API thanh toán bằng tiền mặt, hãy xem generateReferenceNumber. Dưới đây là 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 làm nổi bật. Hai giá trị cần thiết ở đây là paymentIntegratorAccountId do đầu mối liên hệ của bạn tại Google và tài khoản người bán của bạn cung cấp.

Đơn vị tích hợp cũng có thể có nhiều tài khoản tuỳ theo từng quốc gia cung cấp dịch vụ. Điều này có thể là do các luật thuế khác nhau và những điểm 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ể sẽ 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ý thông báo thanh toán và tạo số tham chiếu.

Các API sau đây xử lý việc chuyển tiền và thanh toán.

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 gọi GenerateReferenceNumber khi bạn bắt đầu giao dịch mua hàng. Chúng tôi mong bạn sẽ trả lờ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 các 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 tệp 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"
}

Định dạng JSON của 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);

Hủy số tham chiếu

Google có thể chọn huỷ số tham chiếu và ngăn không cho người dùng thanh toán số tham chiếu đó. Một trường hợp sử dụng mẫu là chương trình khuyến mãi đã hết hạn. Sau khi nhận được yêu cầu này, bạn phải đảm bảo rằng chúng tôi không thể thanh toán số tham chiếu đó.

Nếu người dùng đã bắt đầu quy trình thanh toán, ví dụ: 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 tệp 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"
}

Định dạng JSON của phản hồi

{
  "responseHeader": {
    "responseTimestamp": "1561680406459"
  },
  "result": "SUCCESS"
}

referenceNumberPaidNotification

Sau khi khoản thanh toán được chấp nhận và giao dịch hoàn tất, 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 dự kiến 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 tệp 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"
}

Định dạng JSON của phản hồi

{
  "responseHeader": {
    "responseTimestamp": "1561748642600"
  },
  "result": "SUCCESS"
}

Thực hiện quy trình chuyển tiền

Sau khi tích hợp các API cho phương thức FOP cụ thể của mình, bạn có thể chuyển tiền. Phương thức chuyển tiền hoạt động như nhau đối với tất cả các 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 đó. 2 ngày sau 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 tệp 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ục ánh xạ totalDueByIntegrator. Trên dòng này, bạn có thể thấy số tiền ròng mà Nhà tích hợp nợ (tính bằng phần triệu). Ngoài ra, ngày và loại đơn vị tiền tệ sẽ xuất hiện trong thông báo này, với kỳ thanh toán lần lượt là 00:00:00.000 và 23:59:59.999 của(các) ngày giao dịch sớm nhất và gần nhất.

Điều chỉnh (remittanceStatementDetails)

Để đối chiếu, bên tích hợp sẽ gọi remittanceStatementDetails để lấy danh sách các sự kiện có trong phương thứchangtanceStatementNotification.

Google phản hồi yêu cầu remittanceStatementDetails bằng một danh sách sự kiện được phân trang. remittanceStatementDetails phải được gọi 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ể tải 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
}

Đây là một đoạn mã ngắn của phản hồi lớn hơn, mô tả hai sự kiện chụp ảnh (giao dịch).

"captureEvents": [ {
    {
      "eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
      "paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
      "eventCharge": "700000000",
      "eventFee": "-28000000"
    },
    {
      "eventRequestId": "Ggghvh78200PQ3Yrpb",
      "paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
      "eventCharge": "800000000",
      "eventFee": "-32000000"
    }
  }

Xem remittanceStatementDetails để tìm hiểu thêm.

acceptRemittanceStatement và acceptRemittanceStatementWithModifications

Nhà tích hợp nên so sánh các sự kiện này với các sự kiện đã ghi lại. Nếu có giao dịch nào không khớp hoặc thiếu giao dịch, hãy liên hệ với Google để đ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 đã bao gồm thuế, hãy gọi acceptRemittanceStatementWithModifications.

Phương thức acceptRemittanceStatement được sử dụng khi không có thuế đối với các khoản phí.

Nếu muốn bao gồm thuế, hãy gọi acceptRemittanceStatementWithModifications rồi xác định mức thuế. Nếu thuế suất của bạn thay đổi, hãy đảm bảo thông tin này được cập nhậ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"
}