Nền tảng Trung tâm hành động hỗ trợ nhiều cấu hình để nhận thanh toán. Hướng dẫn bật tính năng thanh toán trình bày các khía cạnh tích hợp phổ biến cho tất cả các tính năng tích hợp thanh toán, bao gồm:
- Định cấu hình nguồn cấp dữ liệu để đưa thông tin
tokenization_parametervào - Cập nhật máy chủ đặt phòng để chấp nhận các đối tượng
payment_method_token - Thông tin tổng quan về thông tin được trao đổi giữa người dùng, Trung tâm hành động, đối tác / người bán và đơn vị xử lý thanh toán.
Trong hướng dẫn này, chúng tôi sẽ trình bày chi tiết hơn về cách định cấu hình nguồn cấp dữ liệu để chỉ định loại cấu hình thanh toán nào áp dụng cho người bán và dịch vụ của bạn.
- Không thanh toán / Thanh toán khi đến nơi
- Thanh toán trước toàn bộ
- Phí không đến / Phí huỷ
- Khoản tiền gửi
Tất cả các trường hợp sử dụng cho việc thanh toán đều là phần mở rộng của trường hợp sử dụng không thanh toán/thanh toán khi đến nơi (không yêu cầu cấu hình thanh toán). Vì vậy, hướng dẫn này sẽ bắt đầu bằng cách mô tả cấu hình đó và coi các cấu hình khác là phần mở rộng.
Mỗi phần cũng sẽ đề cập đến các trường cần theo dõi trong máy chủ đặt phòng để chấp nhận cấu hình thanh toán cụ thể.
Không thanh toán / Thanh toán khi đến nơi
Đối với những dịch vụ không yêu cầu thanh toán tại thời điểm đặt trước, bạn không cần phải định cấu hình phương thức thanh toán ở cấp người bán hoặc cấp dịch vụ. Tuy nhiên, bạn vẫn phải cung cấp giá.
Đây là cấu hình cơ sở cho một dịch vụ, chứa tên, nội dung mô tả và giá. Đây sẽ là một thông báo Dịch vụ duy nhất trong một ServiceFeed:
{ "merchant_id": "merchant-1", "service_id": "service-1-a", "name": "Men's haircut", "description": "One of our stylists will cut your hair", "price": { "price_micros": 15000000, "currency_code": "USD" } }
Bạn không cần phải định cấu hình thêm ngoài cách triển khai tiêu chuẩn trong máy chủ đặt phòng để hỗ trợ thanh toán khi đến.
Trả Tiền Trước
Cấu hình này được dùng để chỉ định rằng khách phải thanh toán toàn bộ số tiền cho dịch vụ tại thời điểm đặt phòng.
Khoản thanh toán trước được chỉ định ở cấp dịch vụ thông qua trường prepayment_type của Service. Để yêu cầu thanh toán cho một dịch vụ, bạn nên đặt giá trị này thành REQUIRED như trong ví dụ bên dưới. Xin lưu ý rằng giá được chỉ định theo cách tương tự như ví dụ về phương thức thanh toán khi đến nơi. Tại đây, vì chúng ta đang đặt loại thanh toán trước là bắt buộc, nên thẻ tín dụng sẽ được thu thập và giá này có thể được tính phí tại thời điểm thanh toán.
{ "merchant_id": "merchant-1", "service_id": "service-2-b", "name": "Spa Treatment", "description": "A full spa treatment", "price": { "price_micros": "200000000", "currency_code": "USD" } "prepayment_type": "REQUIRED" }
Máy chủ đặt phòng
Khi chấp nhận khoản thanh toán trước, mã thông báo thanh toán sẽ được chuyển đến máy chủ đặt phòng trong lệnh gọi đến CreateBooking thông qua trường payment_processing_parameters.unparsed_payment_method_token.
Bạn phải tính phí chính xác số tiền được chỉ định thông qua trường giá trong nguồn cấp dữ liệu và bạn phải sử dụng đơn vị tiền tệ được chỉ định trong nguồn cấp dữ liệu. Các khoản phí này phải tuân theo quy trình được mô tả trong Hướng dẫn bật tính năng thanh toán.
Khi trả về một CreateBookingResponse, bạn phải đặt trường booking.payment_information để phản ánh chính xác rằng khoản thanh toán trước đã được cung cấp và xử lý.
Thông số kỹ thuật PaymentInformation chứa tài liệu đầy đủ về tất cả các tuỳ chọn thông tin thanh toán. Dưới đây là ví dụ tối thiểu về cách xử lý khoản thanh toán trước. Điều quan trọng là giá được trả về trong trường giá phải khớp chính xác với giá được chỉ định trong yêu cầu. Ngoài ra, nếu bạn chỉ định một mức thuế trong nguồn cấp dữ liệu/yêu cầu, thì mức thuế đó cũng phải được đưa vào chính xác.
Ngoài ra, bạn phải cung cấp mã giao dịch. Mã giao dịch này tối thiểu phải là duy nhất trong số các giao dịch với người bán đó. Một đề xuất phù hợp cho mã giao dịch là mã giao dịch do công ty xử lý thanh toán cung cấp cho bạn.
{ "prepayment_status": "PREPAYMENT_PROVIDED", "payment_processed_by": "PROCESSED_BY_PARTNER", "payment_transaction_id": "[this-transaction-id]", "price": { "price_micros": "200000000", "currency_code": "USD" } }
Phí không đến
Người dùng có thể bị tính phí vắng mặt nếu họ không đến lượt đặt chỗ hoặc nếu họ huỷ sau thời hạn huỷ. Nếu bạn không chỉ định khoảng thời gian huỷ, thì khoảng thời gian này sẽ mặc định là thời gian bắt đầu của khung giờ.
Để chỉ định phí không đến, trong nguồn cấp dữ liệu dịch vụ, bạn nên thêm trường no_show_fee như trong ví dụ bên dưới:
{ "merchant_id": "merchant-1", "service_id": "service-2-b", "name": "Spa Treatment", "description": "A full spa treatment", "price": { "price_micros": 200000000, "currency_code": "USD" } "scheduling_rules": { "min_advance_online_canceling": 14400, } "no_show_fee": { "fee": { "price_micros": 25000000, "currency_code": "USD" } "fee_type": "FIXED_RATE_DEFAULT" } }
Trong ví dụ trên, đối tác hoặc người bán được uỷ quyền tính phí cố định là 25 đô la Mỹ như đã chỉ định trong trường no_show_fee.fee.price_micros nếu người giữ cuộc hẹn không tham dự cuộc hẹn. Phí này cũng có thể được tính nếu người dùng huỷ trong vòng 4 giờ (14400 giây) trước cuộc hẹn, như được chỉ định trong trường scheduling_rules.min_advance_online_canceling.
Để xem cách xác định phí không đến nhận phòng ở cấp khả năng cung cấp, hãy xem phần này.
Máy chủ đặt phòng
Khi xử lý một yêu cầu có tính phí không đến, mã thông báo thanh toán sẽ được chuyển đến máy chủ đặt phòng của bạn trong lệnh gọi đến CreateBooking thông qua trường payment_processing_parameters.unparsed_payment_method_token.
Mã thông báo này được truyền theo cách tương tự như trong trường hợp thanh toán trước. Tuy nhiên, vì mã thông báo chỉ được uỷ quyền trong một khoảng thời gian ngắn, nên bạn phải gọi API liên quan của trình xử lý thanh toán để nâng cấp mã thông báo này thành một phiên bản mà bạn có thể duy trì để sử dụng sau này. Điều này được mô tả trong phần Hướng dẫn bật tính năng Thanh toán về Quy trình mã thông báo Phí không đến.
Khi trả về một CreateBookingResponse, bạn phải đặt trường booking.payment_information để phản hồi chính xác trạng thái của phí vắng mặt như trong ví dụ bên dưới.
{ "prepayment_status": "PREPAYMENT_PROVIDED", "payment_processed_by": "PROCESSED_BY_PARTNER", "payment_transaction_id": "[this-transaction-id]", "price": { "price_micros": "200000000", "currency_code": "USD" } "no_show_fee": { "fee": { "price_micros": 25000000, "currency_code": "USD" } "fee_type": "FIXED_RATE_DEFAULT" } }
Xin lưu ý rằng no_show_fee được đặt để phản ánh giá và cấu trúc của khoản phí có thể được tính. Ngoài ra, lưu ý rằng, tương tự như ví dụ về thanh toán trước, bạn phải có transaction_id trong thông báo này.
Ngoài ra, xin lưu ý rằng booking_id được đặt trong CreateBookingResponse là trường bắt buộc đối với thông tin cập nhật theo thời gian thực mà bạn phải gửi khi tính phí vắng mặt. Dự kiến mã nhận dạng này sẽ được lưu trữ cùng với thông tin về lượt đặt phòng.
Thông tin cập nhật theo thời gian thực
Nếu người dùng không đến nhận phòng theo lịch đặt phòng hoặc huỷ sau khoảng thời gian huỷ (ví dụ: bằng cách liên hệ trực tiếp với bạn), bạn có thể tuỳ ý tính phí vắng mặt theo quy định bằng thông tin thanh toán mà bạn đã lưu trữ tại thời điểm đặt phòng. Khi tính phí không đến nhận phòng, bạn phải gửi Thông tin cập nhật theo thời gian thực để chỉ định rằng bạn đã tính phí không đến nhận phòng.
Đối với các lượt đặt phòng do CreateBooking tạo, bạn phải gửi thông tin cập nhật đến notification.partners.bookings.patch. Trong nội dung của yêu cầu này phải là thông tin đặt phòng đã cập nhật, với trạng thái được đặt thành NO_SHOW_PENALIZED. Trạng thái này cho Google biết rằng bạn đã thực hiện một khoản thanh toán.
Ví dụ: bạn có thể gửi yêu cầu đến:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/12345678/bookings/123123123?updateMask=status
Với nội dung yêu cầu:
{ "name": "partners/12345678/bookings/123123123" "merchantId": "merchant-1" "serviceId": "service-2-b" "status": "NO_SHOW_PENALIZED" }
Khoản tiền gửi
Khoản đặt cọc được dùng để thu phí ban đầu theo yêu cầu khi đặt phòng. Khoản đặt cọc có thể được tính phí tại thời điểm đặt phòng hoặc sau đó. Bạn có thể cần xác định các điều khoản mà khoản đặt cọc có thể được hoàn lại cũng như thời điểm có thể huỷ đặt phòng trên mạng.
Để chỉ định khoản tiền gửi, trong nguồn cấp dữ liệu dịch vụ, bạn nên thêm trường deposit như trong ví dụ bên dưới:
{ "merchant_id": "merchant-1", "service_id": "service-2-b", "name": "Spa Treatment", "description": "A full spa treatment", "price": { "price_micros": 200000000, "currency_code": "USD" } "scheduling_rules": { "min_advance_online_canceling": 86400, } "deposit": { "deposit": { "price_micros": 25000000, "currency_code": USD, "min_advance_cancellation_sec": 14400, } "deposit_type": "FIXED_RATE_DEFAULT" } }
Trong ví dụ này, min_advance_online_canceling xác định khoảng thời gian huỷ và deposit.min_advance_cancellation_sec xác định thời điểm có thể hoàn tiền đặt cọc. Xin lưu ý rằng trong ví dụ trên, khoản đặt cọc có thể chỉ định thời gian huỷ riêng biệt với các điều khoản hoàn tiền. Trong trường hợp này, người dùng có thể huỷ dịch vụ trên mạng trước tối đa 24 giờ (86400 giây). Điều này đảm bảo rằng người bán được thông báo trực tiếp về mọi trường hợp huỷ trễ. Tuy nhiên, người dùng vẫn có thể được hoàn tiền cho khoản đặt cọc của họ trước khi đặt phòng tối đa 4 giờ (14.400 giây) (bằng cách liên hệ với bạn hoặc người bán để huỷ). Thông tin này sẽ xuất hiện trong các điều khoản thanh toán và trong email xác nhận.
Để xem cách xác định khoản tiền đặt trước ở cấp độ tình trạng còn hàng, hãy xem phần này.
Máy chủ đặt phòng
Khi xử lý một yêu cầu có khoản đặt cọc, mã thông báo thanh toán sẽ được chuyển đến máy chủ đặt phòng của bạn trong lệnh gọi đến CreateBooking thông qua trường payment_processing_parameters.unparsed_payment_method_token.
Mã thông báo này được truyền theo cách tương tự như trong trường hợp thanh toán trước. Nếu tính khoản đặt cọc hoặc giữ tiền tại thời điểm đặt phòng, bạn có thể thực hiện việc này trong yêu cầu này.
Nếu dự định tính phí tiền đặt cọc sau này, vì mã thông báo chỉ được uỷ quyền trong một khoảng thời gian ngắn, bạn phải gọi API liên quan của trình xử lý thanh toán để nâng cấp mã thông báo này thành một phiên bản mà bạn có thể duy trì để sử dụng sau này. Điều này được mô tả trong phần hướng dẫn về cách Bật tính năng thanh toán về quy trình mã thông báo tiền gửi.
Khi trả về một CreateBookingResponse, trường booking.payment_information phải phản hồi đúng trạng thái của khoản tiền gửi, như trong ví dụ bên dưới.
{ "prepayment_status": "PREPAYMENT_PROVIDED", "payment_processed_by": "PROCESSED_BY_PARTNER", "payment_transaction_id": "[this-transaction-id]", "price": { "price_micros": "200000000", "currency_code": "USD" } "deposit": { "deposit": { "price_micros": 25000000, "currency_code": USD, "min_advance_cancellation_sec": 28800, } "deposit_type": "FIXED_RATE_DEFAULT" } }
Xin lưu ý rằng khoản tiền đặt cọc được thiết lập để phản ánh giá và cấu trúc của khoản tiền đặt cọc sẽ được tính phí hoặc giữ lại. Ngoài ra, lưu ý rằng, tương tự như ví dụ về thanh toán trước, bạn phải có transaction_id trong thông báo này.
Thông tin cập nhật theo thời gian thực
Nếu người dùng huỷ đặt phòng trước thời hạn huỷ đặt cọc, bạn phải hoàn lại mọi khoản tiền đặt cọc mà bạn đã tính vào thẻ của người dùng. Khi hoàn tiền đặt cọc, bạn phải gửi thông tin cập nhật theo thời gian thực để chỉ định rằng tiền đặt cọc đã được hoàn lại.
Đối với các lượt đặt phòng do CreateBooking tạo, bạn phải gửi thông tin cập nhật đến notification.partners.bookings.patch. Trong nội dung của yêu cầu này phải là lượt đặt phòng đã cập nhật, với trạng thái được đặt thành CANCELED và trường paymentInformation.prepaymentStatus được đặt thành PREPAYMENT_REFUNDED. Thao tác này sẽ thông báo cho Google rằng khoản tiền đặt cọc đã được hoàn lại.
Ví dụ: bạn có thể gửi yêu cầu đến:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/12345678/bookings/123123123?updateMask=status
Với nội dung yêu cầu:
{ "name": "partners/12345678/bookings/123123123" "merchantId": "merchant-1" "serviceId": "service-2-b" "status": "CANCELED" "paymentInformation": { "prepaymentStatus": "PREPAYMENT_REFUNDED" } }
Yêu cầu thẻ tín dụng
Một dịch vụ có thể yêu cầu thẻ tín dụng để xác minh thêm danh tính của người dùng. Tuy nhiên, bạn không nên sử dụng loại khoản phí này cho các khoản thanh toán trước, tiền đặt cọc hoặc phí không đến nhận phòng. Nếu cần thiết, bạn phải định cấu hình rõ ràng các trường hợp sử dụng đó bằng cách làm theo các bước ở trên. Ngoài ra, xin lưu ý rằng việc yêu cầu thẻ tín dụng thường sẽ dẫn đến việc giảm đáng kể số lượt đặt phòng cho dịch vụ này.
Để yêu cầu cung cấp thẻ tín dụng trong quá trình thanh toán, bạn phải đặt trường require_credit_card thành REQUIRE_CREDIT_CARD_ALWAYS.
{ "merchant_id": "merchant-1", "service_id": "service-1-a", "name": "Men's haircut", "description": "One of our stylists will cut your hair", "price": { "price_micros": 15000000, "currency_code": "USD" }, "require_credit_card": "REQUIRE_CREDIT_CARD_ALWAYS" }
Máy chủ đặt phòng
Khi xử lý một yêu cầu có yêu cầu về thẻ tín dụng, mã thông báo thanh toán sẽ được chuyển đến máy chủ đặt phòng của bạn trong lệnh gọi đến CreateBooking thông qua trường payment_processing_parameters.unparsed_payment_method_token.
Mã thông báo này được truyền theo cách tương tự như trong trường hợp thanh toán trước. Tuy nhiên, vì mã thông báo chỉ được uỷ quyền trong một khoảng thời gian ngắn, nên bạn phải gọi API liên quan của trình xử lý thanh toán để nâng cấp mã thông báo này thành một phiên bản mà bạn có thể duy trì để sử dụng sau này.
Bạn không cần thêm thông tin nào khác trong phản hồi của máy chủ Đặt phòng ngoài trường hợp sử dụng thanh toán khi đến nơi.
Ghi đè giá ở cấp tình trạng còn phòng
Trong tất cả các ví dụ trên, giá / cấu trúc phí được chỉ định ở cấp Dịch vụ. Trong hầu hết các trường hợp, bạn nên sử dụng mức giá theo cấp dịch vụ này. Tuy nhiên, trong một số trường hợp, bạn nên thay đổi cấu trúc thanh toán cho một số khung giờ trống nhất định. Ví dụ: bạn có thể xử lý các trường hợp sau bằng cách ghi đè giá / phí ở cấp tình trạng còn hàng:
- Giá giảm vào thứ Ba và tăng vào thứ Bảy.
- Không áp dụng phí không đến đối với tình trạng phòng từ 17:00 đến 19:00.
Bảng dưới đây liệt kê, đối với mỗi phương thức thanh toán / phí, trường cần sử dụng trong nguồn cấp dữ liệu về tình trạng phòng để ghi đè định nghĩa về cấp dịch vụ.
| Hình thức thanh toán | Định nghĩa về phí / giá | Có thể ghi đè không? |
|---|---|---|
| Thanh toán khi đến | Service.price
|
Giá có thể ghi đè thông qua việc tham chiếu Availability.payment_option_id đến Merchant.payment_option
|
| Trả Tiền Trước | Service.price
|
Bạn có thể ghi đè giá thông qua việc tham chiếu Availability.payment_option_id đến Merchant.payment_option
|
| Không tính phí nếu không đến | Service.no_show_fee
|
Availability.no_show_fee
|
| Khoản tiền gửi | Service.deposit
|
Availability.deposit
|
| Yêu cầu thẻ tín dụng | Service.require_credit_card
|
Availability.require_credit_card
|
Xin lưu ý rằng để ghi đè giá ở cấp độ tình trạng còn hàng, trước tiên, bạn phải xác định một phương thức thanh toán ở cấp người bán. Ngoài ra, để biết hướng dẫn về cách thêm khoảng thời gian huỷ ở cấp độ tình trạng phòng, vui lòng xem hướng dẫn Cách thêm khoảng thời gian huỷ.