คู่มือสำหรับ FOP เงินสด (หรือที่เรียกว่า API หมายเลขอ้างอิง)

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

กรณีการใช้งาน

API หมายเลขอ้างอิงมีประโยชน์หลายอย่าง คู่มือนี้จะพูดถึงกรณีการใช้งาน 2 กรณีและแนะนำการใช้งาน

  • เงินสด - ผู้ใช้ชำระเป็นเงินสดที่หน้าร้านจริง
  • VAN - ผู้ใช้โอนเงินไปยังหมายเลขบัญชีเสมือน (VAN)

เงินสด

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

ผู้ติดต่อที่ Google จะขอตัวอย่างวิธีการชำระเงินทั่วไปของคุณ คุณจะทำงานร่วมกับผู้ติดต่อของ Google เพื่อเพิ่มประสิทธิภาพและปรับแต่งข้อความ

ประสบการณ์ของผู้ใช้ที่ Google ต้องการคือระบบนำส่งคำสั่งซื้อของลูกค้าขณะที่พวกเขากำลังออกจากร้านค้า Google คาดว่า Google จะได้รับ ReferenceNumberPaidNotification ภายใน 3 นาทีนับตั้งแต่ลูกค้าชำระเงินตามหมายเลขอ้างอิงดังกล่าว เมื่อส่ง ReferenceNumberPaidNotification แล้ว ผู้ผสานรวมจะย้อนกลับธุรกรรมนั้นไม่ได้

VAN

ผู้ใช้สามารถชำระค่าสินค้าด้วยบัญชีธนาคารได้ Google จะขอหมายเลขบัญชีเสมือน (VAN) จากผู้ผสานรวมระบบจะแสดงหมายเลขและวิธีการแก่ผู้ใช้ จากนั้น ผู้ใช้จะคัดลอกหมายเลขและป้อนหมายเลขดังกล่าวลงในใบสมัครธนาคารนอกเหนือจากจำนวนเงินที่จะโอน

ผู้ผสานการทำงานต้องยืนยันว่าจำนวนเงินที่โอนตรงกับจำนวนเงินที่ขอ ReferenceNumberGeneration จากนั้นแจ้งให้ Google ทราบว่ามีการชำระเงินหมายเลขอ้างอิงแล้ว

เมื่อ Google ได้รับ ReferenceNumberPaidNotification ของ Google จะนำส่งผลิตภัณฑ์ และผู้ผสานรวมจะย้อนกลับธุรกรรมดังกล่าวไม่ได้

การส่งข้อความระหว่างเซิร์ฟเวอร์ของคุณและเซิร์ฟเวอร์ของ Google

เมื่อคุณส่งข้อความระหว่างเซิร์ฟเวอร์ของคุณและเซิร์ฟเวอร์ของ Google หรือในทางกลับกัน โปรดดำเนินการตามหลักเกณฑ์เหล่านี้

คำขอที่เข้ามา - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

การตอบกลับขาออก - Base64UrlEncode(EncryptWithGooglePublicKey(request))

คำขอของ Google - Base64UrlEncode(EncryptWithGooglePublicKey(request))

การตอบกลับของ Google - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

โปรดดูไลบรารีและตัวอย่าง PGP ใน Java ที่แสดงคำขอและการตอบกลับ

ทำตามลักษณะการทำงานแบบนิจพล

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

ความสำคัญ

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

วิธีใช้งาน Idempotency

หาก Google ส่งลองอีกครั้ง รหัสคำขอจะเหมือนกันและเนื้อหาจะเหมือนกัน แต่การประทับเวลาจะต่างออกไป ตอบกลับด้วยคำตอบเดียวกันกับที่คุณส่งก่อนหน้านี้ หากคำตอบแรกคือ 200 (สำเร็จ) Google คาดว่าคำตอบเดียวกันนี้จะมีการประทับเวลาที่ต่างกัน

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

ดูข้อมูลเพิ่มเติมได้ในคู่มือโดยละเอียดนี้

ใช้รหัสบัญชีผู้ผสานรวมการชำระเงิน (PIAID)

การผสานรวมกับ Google อาจต้องการการผสานรวมกับองค์กรธุรกิจต่างๆ ของ Google ตัวอย่างเช่น Google Play เป็นหนึ่งในนิติบุคคล อีกรายหนึ่งคือ YouTube และอีกรายหนึ่งคือ Google Ads ซึ่งจะเกี่ยวข้องกับบัญชีผู้ขายต่างๆ เพื่อเป็นตัวแทนของการกำหนดค่าเหล่านี้แต่ละรายการ

Google ได้ระบุรหัสบัญชีผู้ผสานรวมการชำระเงิน (PIAID) ไว้สำหรับการแมปจากเอนทิตีแต่ละรายการภายใน Google กับบัญชีผู้ขายแต่ละบัญชี ดูตัวอย่างสำหรับ API รูปแบบการชำระเงินสด โปรดดู generateReferenceNumber นี่คือตัวอย่างที่ใช้การแมปนี้

Google ได้ระบุรหัสบัญชีผู้ผสานรวมการชำระเงิน (PIAID) ไว้สำหรับการแมปจากเอนทิตีแต่ละรายการภายใน Google กับบัญชีผู้ขายแต่ละบัญชี สำหรับตัวอย่างที่ใช้ API การชำระเงินสด โปรดดู generateReferenceNumber นี่คือตัวอย่างที่ใช้การแมปนี้


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "transactionDescription": "Google - Music",
  "currencyCode": "USD",
  "amount": "2000000"
}

สังเกตส่วนที่ไฮไลต์ ค่า 2 ค่าที่จำเป็นต้องระบุคือ paymentIntegratorAccountId ที่ได้รับจากผู้ติดต่อที่ Google และบัญชีผู้ขายของคุณ

ผู้รวมบริการอาจมีบัญชีที่แตกต่างกันในแต่ละประเทศที่ให้บริการ ซึ่งอาจเป็นเพราะกฎหมายภาษีที่หลากหลายและความแตกต่างอื่นๆ ในแต่ละประเทศ ในกรณีนี้ อาจมีการสร้าง PIAID อีกรายการสำหรับแต่ละประเทศ

API ที่จะผสานรวม

API ต่อไปนี้จะจัดการการสร้างหมายเลขอ้างอิงและการแจ้งเตือนเกี่ยวกับการชำระเงิน

API ต่อไปนี้จัดการการส่งเงินและการปิดยอด

คุณจะต้องผสานรวม API ข้างต้นทั้งหมดเพื่อสร้างหมายเลขอ้างอิงและตกลงกับ Google

สร้างหมายเลขอ้างอิง

Google จะเรียกใช้ GenerateReferenceNumber เมื่อคุณเริ่มการซื้อ เราหวังว่าคุณจะตอบกลับพร้อมหมายเลขอ้างอิงที่ระบุธุรกรรมหรือบัญชี เวลาในการตอบสนองที่คาดไว้คือ < 3 วินาที

สำหรับธุรกรรมเงินสด หมายเลขอ้างอิงอาจมีความยาวได้สูงสุด 12 อักขระ

URL: POST https://[your basepath]/v1/generateReferenceNumber

ขอ 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 ของการตอบกลับ

{
  "responseHeader": {
    "responseTimestamp": "1561678947659"
  },
  "result": "SUCCESS",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

Java ตัวอย่าง

`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`

GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);

ยกเลิกหมายเลขอ้างอิง

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

หากผู้ใช้เริ่มกระบวนการชำระเงินแล้ว เช่น การค้นหาหมายเลขอ้างอิงจากจุดขาย เซิร์ฟเวอร์ของคุณควรตอบกลับด้วยการตอบกลับ HTTP 423 และ ErrorResponse ในเนื้อหาคำขอโดยมีสถานะ USER_ACTION_IN_PROGRESS

URL: POST https://[your basepath]/v1/cancelReferenceNumber

ขอ 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 ของการตอบกลับ

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

referenceNumberPaidNotification

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

URL ปลายทางของ referenceNumberPaidNotification


POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]

ขอ 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 ของการตอบกลับ

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

ดำเนินการส่งเงิน

เมื่อคุณผสานรวม API สำหรับรูปแบบการชำระเงินหนึ่งๆ แล้ว คุณก็พร้อมที่จะส่งเงินได้ การส่งเงินจะทำงานเหมือนกันในทุก FOP

remittanceStatementNotification

2 วันหลังจากทำธุรกรรม Google จะส่ง remittanceStatementNotification ซึ่งมีข้อมูลสรุปธุรกรรมที่ Google บันทึกไว้ในวันนั้น ตัวอย่างการแจ้งเตือน 2 วันหลังจากทำธุรกรรมจะมีลักษณะดังนี้

POST https://www.integratordomain.com/v1/remittanceStatementNotification

ขอ 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",
  }
}

สังเกตการแมป totalDueByIntegrator ในบรรทัดนี้ คุณจะเห็นจำนวนเงินสุทธิที่ผู้ผสานรวมค้างชำระอยู่ (เป็นไมโคร) นอกจากนี้ วันที่และประเภทสกุลเงินจะปรากฏในข้อความนี้ด้วย โดยระยะเวลาการเรียกเก็บเงินจะแสดงเป็น 00:00:00.000 และ 23:59:59.999 ของวันทำธุรกรรมวันแรกสุดและวันสุดท้ายตามลำดับ

การปรับยอด (remittanceStatementDetails)

สำหรับการไกล่เกลี่ย ผู้ผสานรวมจะเรียก remittanceStatementDetails เพื่อรับรายการเหตุการณ์ที่รวมอยู่ใน remittanceStatementNotification

Google ตอบกลับคําขอ remittanceStatementDetails ด้วยรายการเหตุการณ์แบบแบ่งหน้า ควรเรียก remittanceStatementDetails หลายครั้งหากจำนวนธุรกรรมทั้งหมดมากกว่า 1,000 โดยไม่จำเป็นต้องส่งคำขอตามลำดับและสามารถส่งพร้อมกันได้

URL คำขอ

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails

ตัวอย่างเนื้อหาคำขอ

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "statement_detail_request_139932019",
    "requestTimestamp": "1502551332087"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc",
  "numberOfEvents": 4
}

ต่อไปนี้เป็นตัวอย่างสั้นๆ ของการตอบสนองที่ใหญ่กว่าซึ่งอธิบายถึงเหตุการณ์การบันทึก 2 รายการ (ธุรกรรม)

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

ดูข้อมูลเพิ่มเติมที่ remittanceStatementDetails

acceptRemittanceStatement และ acceptRemittanceStatementWithModifications

ผู้ผสานรวมควรเปรียบเทียบเหตุการณ์เหล่านี้กับเหตุการณ์ที่ได้บันทึกไว้ หากธุรกรรมไม่ตรงกันหรือไม่มีธุรกรรมใดๆ โปรดติดต่อ Google เพื่อตรวจสอบเพิ่มเติม หากธุรกรรมทั้งหมดตรงกัน และค่าธรรมเนียมการดำเนินการไม่รวมภาษี โปรดโทรหา acceptRemittanceStatement หากรวมภาษีแล้ว โปรดโทรหาหมายเลข acceptRemittanceStatementWithModifications

ระบบจะใช้เมธอด acceptRemittanceStatement เมื่อไม่มีภาษีสำหรับค่าธรรมเนียม

หากต้องการรวมภาษี ให้เรียกใช้ acceptRemittanceStatementWithModifications และกำหนดอัตราภาษี หากอัตราภาษีมีการเปลี่ยนแปลง โปรดตรวจสอบว่าได้อัปเดตแล้ว หลังจาก acceptRemittanceStatement สำเร็จแล้ว ให้เริ่มการโอนเงินผ่านธนาคารไปยังบัญชี Google

URL คำขอสำหรับ acceptRemittanceStatement

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement

เนื้อหาคำขอตัวอย่าง

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
}

ตัวอย่างการตอบกลับ

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementResultCode": "SUCCESS"
}

URL คำขอสำหรับ acceptRemittanceStatementWithModifications

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications

ตัวอย่างเนื้อหาคำขอ

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
  "feeToVatModification": {
    "vatToFeeRatioInMicros": "150000"
  }
}

ตัวอย่างการตอบกลับ

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}