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

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

Use Case

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

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

เงินสด

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

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

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

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

วิธีใช้การแสดงตัวตน

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

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

หากต้องการเรียนรู้เพิ่มเติม โปรดดูคู่มือโดยละเอียดนี้

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

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

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

สำหรับการแมปจากเอนทิตีแต่ละรายการภายใน Google กับบัญชีผู้ขายแต่ละบัญชี Google จะระบุรหัสบัญชีของผู้รวมการชำระเงิน (PIAID) ดูตัวอย่างการใช้ 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"
}