คำแนะนำการผสานรวมแบ็กเอนด์สำหรับการสร้างรายได้นอก Google Play Billing

ตอนนี้ API สำหรับนักพัฒนาซอฟต์แวร์ Google Play มี เพื่อรายงานธุรกรรมจากการเรียกเก็บเงินระบบอื่นหรือ ระบบข้อเสนอภายนอก คู่มือนี้อธิบายวิธีรายงานทางเลือก การเรียกเก็บเงินหรือธุรกรรมของข้อเสนอภายนอก

มีองค์ประกอบ 2-3 อย่างที่อาจจำเป็นต้องใช้ในการจัดการในแอป จากแบ็กเอนด์ของคุณ คุณต้องตั้งค่าแบ็กเอนด์ก่อนจึงจะสร้างได้ ดังที่ระบุไว้ในกำหนดค่า Google Play Developer API สำหรับ ฟังก์ชันการทำงานแบ็กเอนด์ทั้งหมดของนักพัฒนาแอปที่ไม่ได้เจาะจงสำหรับการเรียกเก็บเงินระบบอื่น หรือ API ของข้อเสนอภายนอก วิธีการจาก เป็นไปตามเอกสารประกอบของระบบการเรียกเก็บเงินของ Google Play

รายงานธุรกรรมภายนอกใหม่ไปยัง Google Play

ผสานรวมกับ Externaltransactions APIs เพื่อรายงานธุรกรรมที่เกิดขึ้นนอกระบบการเรียกเก็บเงินของ Google Play ประเทศที่รองรับ รวมถึงธุรกรรม $0 ที่เกิดจากช่วงทดลองใช้ฟรี การซื้อ ธุรกรรมในการเรียกเก็บเงินระบบอื่นหรือระบบข้อเสนอภายนอก ควรเริ่มต้นและรายงานประเทศผู้ใช้ที่มีสิทธิ์ตามที่ได้รับอนุญาตเท่านั้น ภายใต้การเรียกเก็บเงินระบบอื่นหรือ ข้อเสนอภายนอก ไม่เช่นนั้นการเรียก API ถูกปฏิเสธ นโยบายนี้จะมีผลกับธุรกรรมทั้งหมด รวมถึงการซื้อใหม่ การต่ออายุ การเติมเงิน การอัปเกรด การดาวน์เกรด และอื่นๆ

การรายงานธุรกรรมภายนอก

คุณควรโทรหา Externaltransactions API เพื่อรายงานธุรกรรมภายนอก หลังจากการชำระเงินได้รับการอนุมัติผ่านการเรียกเก็บเงินระบบอื่น หรือ ระบบข้อเสนอภายนอก นโยบายนี้จะมีผลกับธุรกรรมทั้งหมด รวมถึงธุรกรรมครั้งแรก การเรียกเก็บเงิน การต่ออายุ การคืนเงิน และอื่นๆ ธุรกรรมทั้งหมดต้องเป็น ได้รับรายงานภายใน 24 ชั่วโมงนับจากมีการทำธุรกรรม

ระบบจะรายงานธุรกรรมภายนอกแต่ละรายการด้วยรหัสธุรกรรมภายนอก สำหรับ การซื้อแบบตามรอบ (เช่น การสมัครใช้บริการแบบต่ออายุใหม่อัตโนมัติ) คุณจะต้องส่ง รหัสธุรกรรมภายนอกที่เชื่อมโยงกับธุรกรรมแรกในธุรกรรมที่เกิดซ้ำ purchase เป็นพารามิเตอร์สำหรับธุรกรรมที่ตามมา รวมถึงการคืนเงิน ช่วงเวลานี้ จะบันทึกชุดธุรกรรมสำหรับการซื้อนั้น คุณส่งภายนอกรายการใหม่ รหัสธุรกรรมสำหรับการซื้อเมื่อผลิตภัณฑ์มีการเปลี่ยนแปลง (เช่น การอัปเกรด หรือ การดาวน์เกรด) หรือหากธุรกรรมตามรอบถูกยกเลิกหรือหมดอายุไปแล้ว มีการซื้อผลิตภัณฑ์อีกครั้งในภายหลัง คุณต้องไม่รวมข้อมูลที่ระบุตัวตนได้ ข้อมูลที่เป็นกรรมสิทธิ์หรือข้อมูลลับโดยเป็นส่วนหนึ่งของ รหัสธุรกรรม

รายงานการซื้อใหม่

ทุกครั้งที่การซื้อใหม่เสร็จสมบูรณ์ในการเรียกเก็บเงินระบบอื่น หรือระบบข้อเสนอภายนอก การเรียก Externaltransactions API ต้องระบุ สำหรับการซื้อใหม่เหล่านี้ คุณจะต้องระบุแอตทริบิวต์อีเมลที่ไม่ซ้ำ externalTransactionId ที่เชื่อมโยงกับการซื้อในแบ็กเอนด์ของคุณเป็นการค้นหา พารามิเตอร์ externalTransactionId นี้ไม่สามารถใช้ซ้ำภายในแอปเดียวกัน รหัสแพ็กเกจ

externalTransactionToken ที่แอปได้รับผ่าน UserChoiceBillingListener AlternativeBillingOnlyReportingDetailsListener หรือ ExternalOfferReportingDetailsListener Callback ก็ต้องมีเป็นส่วนหนึ่งของ เนื้อหาคำขอสำหรับการซื้อแบบครั้งเดียวและธุรกรรมครั้งแรกใน การซื้อตามรอบ (เช่น การสมัครใช้บริการ) ไม่ว่าในกรณีใด สิ่งนี้เรียกว่า ธุรกรรมเริ่มต้น หลังจากทำธุรกรรมครั้งแรก คุณไม่จําเป็นต้องใช้ externalTransactionToken อีกต่อไป และคุณรายงานรายการต่อๆ ไป ธุรกรรม (เช่น การต่ออายุการสมัครสมาชิก) โดยการระบุ externalTransactionId โปรดดูหัวข้อรายงานธุรกรรมการซื้อครั้งต่อๆ ไป สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับวิธีรายงานธุรกรรมที่ตามมา

ตัวอย่าง

  1. นักพัฒนาแอปจะกำหนดค่าและเปิดใช้การเรียกเก็บเงินระบบอื่นในแอปของตน
  2. ผู้ใช้ 1 อยู่ในเกาหลีใต้ซึ่งเป็นประเทศที่รองรับ และกำลังพยายามซื้อ product1 ในราคา 12634.10KRW/เดือน พร้อมข้อเสนอช่วงทดลองใช้ฟรี 1 เดือน
  3. แอปจะเปิดขั้นตอนการซื้อด้วย ProductDetails สำหรับ product1 และข้อเสนอที่ผู้ใช้เลือก
  4. ผู้ใช้ 1 เลือกระบบการเรียกเก็บเงินระบบอื่นของนักพัฒนาแอป
  5. UserChoiceBillingListener จะได้รับค่า my_token เป็น externalTransactionToken
  6. จากนั้นนักพัฒนาแอปจะส่งข้อมูลที่เกี่ยวข้องไปยังแบ็กเอนด์ (มูลค่า externalTransactionToken รายการและผลิตภัณฑ์ที่กำลังซื้อ) จากนั้น เปิดขั้นตอนการซื้อสำหรับ product1 ในระบบการเรียกเก็บเงินระบบอื่น ธุรกรรมนี้ได้รับการกำหนดรหัสธุรกรรมที่ไม่ซ้ำกันในฝั่งนักพัฒนาซอฟต์แวร์ ที่ใช้ในการรายงานไปยัง Google Play: 123-456-789 รหัสธุรกรรม แม้ว่าผู้ใช้จะได้รับช่วงทดลองใช้ฟรีก็ตาม
  7. หลังจากธุรกรรมสำหรับการซื้อเกิดขึ้นในการเรียกเก็บเงินระบบอื่น นักพัฒนาซอฟต์แวร์จะรายงานธุรกรรมดังกล่าวให้ Google Play ทราบด้วย คำขอต่อไปนี้ ในตอนแรกมีการรายงานเป็นธุรกรรมที่ไม่มีดอลลาร์ เนื่องจากผู้ใช้จะได้รับการใช้งานฟรี 1 เดือน
POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

หากทำธุรกรรมกับผู้ใช้ที่อาศัยอยู่ในอินเดีย ซึ่งภาษีจะแตกต่างกันไปขึ้นอยู่กับ เขตบริหาร (เช่น รัฐหรือจังหวัด) แล้วอย่าลืมใส่ ใต้ userTaxAddress โปรดดูรายการสตริงที่กำหนดไว้ล่วงหน้าใน คู่มืออ้างอิง API สำหรับเขตบริหารที่เกี่ยวข้อง

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=123-456-789

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "INR"
 },
"transactionTime" : "2023-11-01T12:45:00Z",
 "recurringTransaction" : {
   "externalTransactionToken": "my_token",
   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   # Tax varies in India based on state, so include that information in
   # administrativeArea
   "regionCode": "IN"
   "administrativeArea": "KERALA"
 }
}

รายงานธุรกรรมสำหรับการซื้อภายหลัง

ในบางกรณี อาจมีการชำระเงินของผู้ใช้มากกว่า 1 รายการที่เชื่อมโยงกับบัญชีเดียวกัน การซื้อภายนอก (เช่น การต่ออายุการสมัครใช้บริการหรือการเติมเงินแพ็กเกจแบบชำระเงินล่วงหน้า) คุณสามารถรายงานธุรกรรมที่ตามมาเหล่านี้โดยใช้ API เดียวกันใน Externaltransactions ตามที่อธิบายไว้ในรายงานการซื้อใหม่ แต่ไม่จำเป็นต้องใช้ externalTransactionToken สำหรับการทำธุรกรรมครั้งต่อๆ ไป แต่ ระบบจะส่ง externalTransactionId ใหม่ที่ไม่ซ้ำกันเป็นพารามิเตอร์การค้นหาสำหรับแต่ละรายการ ธุรกรรมการต่ออายุหรือเติมเงินที่มีรหัสธุรกรรมเริ่มต้น ในช่อง initialExternalTransactionId

ต่อไปนี้คือตัวอย่างก่อนหน้านี้

  1. การต่ออายุครั้งแรกของผู้ใช้ 1 จะเกิดขึ้นในระบบการเรียกเก็บเงินระบบอื่น ตัวย่อ รหัสธุรกรรมเดิมคือ 123-456-789
  2. นักพัฒนาแอปรายงานการเกิดซ้ำของธุรกรรมในพารามิเตอร์การค้นหาของ URL เป็นรหัสธุรกรรมภายนอกสำหรับธุรกรรมใหม่นี้ ขณะที่อ้างถึง รหัสธุรกรรมภายนอกของธุรกรรมเริ่มต้นใน initialExternalTransactionId

ตัวอย่างคำขอ

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
"originalPreTaxAmount" : {
   "priceMicros": "12634000000",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "1263000000",
   "currency": "KRW"
 },
"transactionTime" : "2022-02-22T12:45:00Z",
 "recurringTransaction" : {
   "initialExternalTransactionId": "123-456-789",

   "externalSubscription" {
     "subscriptionType": "RECURRING"
   }
 },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

รายงานการอัปเกรดหรือดาวน์เกรด

วิธีรายงานการอัปเกรดหรือดาวน์เกรดเมื่อผู้ใช้เป็นเจ้าของการสมัครใช้บริการใน ระบบการเรียกเก็บเงินระบบอื่นที่คุณใช้ปลายทางและฟังก์ชันเดียวกันใน Externaltransactions API ซึ่งส่ง externalTransactionToken ที่ ที่ให้ไว้กับแอปสำหรับธุรกรรมการอัปเกรดหรือดาวน์เกรด วิธีนี้ได้ผล ซึ่งคล้ายกับการรายงานการซื้อใหม่

ย้ายข้อมูลจากการรายงานธุรกรรมการเรียกเก็บเงินระบบอื่นด้วยตนเอง

วิธีย้ายข้อมูลการสมัครใช้บริการที่ใช้งานอยู่ซึ่งเริ่มต้นขณะที่คุณเสนอทางเลือก การเรียกเก็บเงินโดยไม่มีการรายงานอัตโนมัติ ให้สร้างธุรกรรมแบบไม่เสียค่าใช้จ่ายใหม่โดยใช้ ในฟิลด์ migratedTransactionProgram แทนการระบุ initialExternalTransactionIdหรือexternalTransactionToken ตั้งค่า transactionTime จนถึงเวลาที่ผู้ใช้ลงชื่อสมัครใช้งานแต่ละรายการที่ใช้งานอยู่ครั้งแรก การสมัครใช้บริการ หลังจากนั้น ให้รายงานธุรกรรมที่ตามมาแต่ละรายการสำหรับ ตามปกติผ่าน API ซึ่งทำให้สามารถ ใช้ initialExternalTransactionId ด้านบนเพื่อสร้างธุรกรรมการต่ออายุ เมื่อย้ายข้อมูลการสมัครใช้บริการแล้ว คุณจะไม่ต้องรายงานด้วยตนเองอีกต่อไป ธุรกรรมของการสมัครใช้บริการในครั้งต่อๆ ไป โดยมีเงื่อนไขว่า รายงานด้วยวิธีการอัตโนมัติที่อธิบายในหน้านี้

ขณะย้ายข้อมูลการสมัครใช้บริการ โปรดคำนึงถึงโควต้าโควต้าที่กำหนดไว้เพื่อ เพื่อให้มั่นใจว่าการย้ายข้อมูลจะไม่ทำให้โควต้าหยุดทำงาน หากมีความจำเป็นในการสมัครใช้บริการหลายรายการ ให้ย้ายข้อมูล กระจายแคมเปญออกไปหลายๆ วัน หรือขอเพิ่ม ในโควต้า ที่ใช้เวลาเพียง 2 นาที

สามารถใช้ฟิลด์ migratedTransactionProgram เมื่อย้ายข้อมูลจาก การรายงานด้วยตนเอง เราจะเลิกใช้เมื่อการรายงานด้วยตนเองไม่ได้ให้บริการอีกต่อไป ที่รองรับ

ตัวอย่างคำขอ

# Note that the externalTransactionId specified here will used to report subsequent
# transactions.

POST /androidpublisher/v3/applications/com.myapp.android/externalTransactions?externalTransactionId=abc-def-ghi

Body
 {
 # Be sure to set the price to 0 for this transaction since it does not reflect
 # an actual subscription renewal.
 "originalPreTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },
 "originalTaxAmount" : {
   "priceMicros": "0",
   "currency": "KRW"
 },

 # The transaction time should be set to when the user signed up for this
 # subscription.
 "transactionTime" : "2022-02-22T12:45:00Z",
  "recurringTransaction" : {
    "migratedTransactionProgram": "USER_CHOICE_BILLING",

    "externalSubscription" {
      "subscriptionType": "RECURRING"
    }
  },
 "userTaxAddress" : {
   "regionCode": "KR"
 }
}

รายงานโปรแกรมพาร์ทเนอร์ของ Play

นักพัฒนาแอปที่เข้าร่วมโปรแกรมพาร์ทเนอร์ เช่น Play Media Experience Program จะต้องระบุ transaction_program_code เมื่อรายงานธุรกรรมภายนอก หากคุณ นักพัฒนาซอฟต์แวร์ที่มีสิทธิ์ โปรดติดต่อผู้จัดการฝ่ายพัฒนาธุรกิจของคุณ ข้อมูลเกี่ยวกับวิธีตั้งค่าช่องนี้

รายงานการคืนเงินสำหรับการซื้อไปยัง Google Play

ผสานรวมกับ Externaltransactions API เพื่อรายงานธุรกรรมที่คืนเงินไปยัง ผู้ใช้ที่อยู่นอกระบบการเรียกเก็บเงินของ Google Play เพื่อให้ Play สามารถระบุได้ถูกต้อง ธุรกรรมได้รับการคืนเงินแล้ว คุณควรระบุ externalTransactionIdสำหรับธุรกรรมที่รายงานก่อนหน้านี้เป็นส่วนหนึ่งของ พารามิเตอร์ของ URL

เมื่อรายงานการคืนเงินสำหรับการซื้อการสมัครใช้บริการ โปรดดู externalTransactionId ของการสมัครใช้บริการที่เกิดซ้ำที่ กำลังดำเนินการคืนเงิน

ตัวอย่าง: สมมติว่าการสมัครใช้บริการมีธุรกรรมต่อไปนี้

  • ธุรกรรมเริ่มต้นที่ใช้รหัสธุรกรรมภายนอก ABC.1234-5678-9012-34567
  • ธุรกรรมที่เกิดซ้ำรายการแรกที่มีรหัสธุรกรรมภายนอก ABC.1234-5678-9012-34567..0
  • ธุรกรรมที่เกิดซ้ำรายการที่ 2 ซึ่งมีรหัสธุรกรรมภายนอก ABC.1234-5678-9012-34567..1

หากต้องการรายงานการคืนเงินของธุรกรรมทั้งหมดสำหรับการสมัครใช้บริการ คุณต้องทำดังนี้ คำขอเงินคืนแยกกัน 3 รายการ ได้แก่ คำขอแรกสำหรับธุรกรรมครั้งแรกและอีก 2 รายการสำหรับ ธุรกรรมที่เกิดตามมา

วิธีนี้ยอมรับทั้งการคืนเงินเต็มจำนวน (โดยจำนวนเงินเป็นจำนวนเงินเท่ากับที่ผู้ใช้ชำระในรายการภายนอก ธุรกรรม) และการคืนเงินบางส่วน (โดยที่จำนวนเงินน้อยกว่าที่ผู้ใช้ชำระในเอกสารภายนอก ธุรกรรม) สำหรับการคืนเงินบางส่วน คุณต้องระบุจำนวนเงินก่อนหักภาษีที่ ได้รับเงินคืนแล้ว

โควต้า API

Externaltransactions API จะเป็นไปตามโควต้า API รายวัน สำหรับการเรียกทั้งหมด เช่นเดียวกับปลายทางอื่นๆ ใน Google Play Developer API

นอกจากนี้ Externaltransactions API ยังมีคำค้นหา 1,200 รายการต่อนาที (QPM) สำหรับการโทรไปยัง Externaltransactions.createexternaltransaction หรือ Externaltransactions.refundexternaltransaction โทรหา Externaltransactions.getexternaltransaction ไม่นับรวมใน 1,200 QPM นี้ ขีดจำกัด