sumup android sdk
Release 5.0.3
พื้นที่เก็บข้อมูลนี้จัดทำเอกสารทีละขั้นตอนสำหรับ Android SDK ดั้งเดิมของ SumUp ซึ่งช่วยให้คุณสามารถรวมเทอร์มินัลบัตรที่เป็นกรรมสิทธิ์ของเราและแพลตฟอร์มการชำระเงินเพื่อรับการชำระเงินด้วยบัตรเครดิตและเดบิต (รวมถึง VISA, MasterCard, American Express และอื่น ๆ ) SDK สื่อสารอย่างโปร่งใสไปยังช่องเสียบการ์ดผ่าน Bluetooth (BLE 4.0) เมื่อเริ่มต้นการชำระเงิน SDK จะแนะนำผู้ใช้ของคุณโดยใช้หน้าจอที่เหมาะสมผ่านแต่ละขั้นตอนของกระบวนการชำระเงิน ส่วนหนึ่งของกระบวนการนี้ SumUp ยังมีหน้าจอการตั้งค่าเครื่องรูดบัตร พร้อมด้วยหน้าจอการตรวจสอบลายเซ็นของผู้ถือบัตรอีกด้วย ผลลัพธ์การชำระเงินจะถูกส่งกลับพร้อมกับข้อมูลที่เกี่ยวข้องเพื่อเก็บไว้เป็นหลักฐาน
ไม่มีการส่งผ่านข้อมูลบัตรที่ละเอียดอ่อนไปยังหรือจัดเก็บไว้ในโทรศัพท์ของร้านค้า ข้อมูลทั้งหมดถูกเข้ารหัสโดยเทอร์มินัลการ์ด ซึ่งได้รับการรับรองอย่างสมบูรณ์ตามมาตรฐานอุตสาหกรรมสูงสุด (PCI, EMV I & II, Visa, MasterCard & Amex)
สำหรับข้อมูลเพิ่มเติมเกี่ยวกับผลิตภัณฑ์ผู้พัฒนา SumUp โปรดดูเอกสารประกอบ SumUp API ของเรา
minSdkVersion 26 หรือใหม่กว่าtargetSDK 31 หรือใหม่กว่าเพิ่มพื้นที่เก็บข้อมูลในการพึ่งพาการไล่ระดับของคุณ:
allprojects {
repositories {
maven { url ' https://maven.sumup.com/releases ' }
}
}เพิ่มการพึ่งพาให้กับโมดูล:
implementation ' com.sumup:merchant-sdk:5.0.3 'เริ่มต้นส่วนประกอบ SumUp ในแอปของคุณ:
public class SampleApplication extends Application {
@ Override
public void onCreate () {
super . onCreate ();
SumUpState . init ( this );
}
}ก่อนที่จะเรียกใช้คุณสมบัติใด ๆ ของ SumUp SDK บัญชีผู้ค้า SumUp ที่ลงทะเบียนจะต้องเข้าสู่ระบบ โปรดไปที่ https://me.sumup.com/developers เพื่อดึงรหัส Affiliate ของคุณโดยป้อนรหัสแอปพลิเคชันของแอปของคุณ (เช่น com.sumup.sdksampleapp)
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );หมายเหตุ: นอกจากนี้ยังสามารถเข้าสู่ระบบบัญชีด้วยโทเค็นได้โดยไม่ต้องให้ผู้ใช้ป้อนข้อมูลรับรองการเข้าสู่ระบบ SumUp ใน SDK โปรดดูส่วนการรับรองความถูกต้องแบบโปร่งใส
เมื่อเข้าสู่ระบบแล้ว คุณสามารถเริ่มใช้ SumUp SDK เพื่อรับการชำระเงินด้วยบัตรได้ หากไม่มีบัญชีเข้าสู่ระบบ ระบบจะส่งคืน SumUpAPI.Response.ResultCode.ERROR_NOT_LOGGED_IN
SumUpPayment payment = SumUpPayment . builder ()
// mandatory parameters
. total ( new BigDecimal ( "1.12" )) // minimum 1.00
. currency ( SumUpPayment . Currency . EUR )
// optional: to be used only if the card reader supports the feature, what can be checked with `SumUpApi.isTipOnCardReaderAvailable()`
. tipOnCardReader ()
// optional: include a tip amount in addition to the total, ignored if `tipOnCardReader()` is present
. tip ( new BigDecimal ( "0.10" ))
// optional: add details
. title ( "Taxi Ride" )
. receiptEmail ( "[email protected]" )
. receiptSMS ( "+3531234567890" )
// optional: Add metadata
. addAdditionalInfo ( "AccountId" , "taxi0334" )
. addAdditionalInfo ( "From" , "Paris" )
. addAdditionalInfo ( "To" , "Berlin" )
// optional: foreign transaction ID, must be unique!
. foreignTransactionId ( UUID . randomUUID (). toString ()) // can not exceed 128 chars
// optional: skip the success screen
. skipSuccessScreen ()
// optional: skip the failed screen
. skipFailedScreen ()
. build ();
SumUpAPI . checkout ( MainActivity . this , payment , 2 ); @ Override
protected void onActivityResult ( int requestCode , int resultCode , Intent data ) {
if ( requestCode == 2 && data != null ) {
// Handle the response here
}
}มีช่องตอบกลับหลายช่องเมื่อมีการเรียกกิจกรรมการติดต่อกลับ:
แฟล็กการตอบสนองมีให้ภายใน Bundle ที่ถูกส่งกลับไปยังกิจกรรมการโทรกลับ:
int resultCode = getIntent (). getExtras (). getInt ( SumUpAPI . Response . RESULT_CODE );เมื่อร้านค้าเข้าสู่ระบบ คุณสามารถเปิดกิจกรรมนี้เพื่อเข้าถึงการตั้งค่าและตัวเลือกทั้งหมดที่เกี่ยวข้องกับเครื่องอ่านบัตรได้
SumUpAPI . openCardReaderPage ( MainActivity . this , 4 ); prepareForCheckout() มอบความเป็นไปได้ในการเชื่อมต่อเครื่องอ่านบัตรก่อนเริ่มการชำระเงิน ซึ่งจะช่วยเร่งเวลาชำระเงินโดยรวมให้เร็วขึ้น
หากต้องการเรียกใช้วิธีนี้ ผู้ใช้จะต้องเข้าสู่ระบบด้วยบัญชี SumUp และเครื่องอ่านการ์ดควรได้รับการตั้งค่าแล้ว ถัดไป ให้เรียก prepareForCheckout() ก่อนเริ่มการชำระเงิน
หมายเหตุ: เครื่องอ่านการ์ด Air และ Solo ยังคงเชื่อมต่อผ่าน BLE หลังจากทำธุรกรรมแต่ละครั้ง ในขณะที่ใช้
prepareForCheckout()เมื่อเครื่องอ่านบัตรถูกตัดการเชื่อมต่อ (เช่น เครื่องอ่านอยู่นอกระยะ แอปโฮสต์สูญเสียโฟกัส หรือเครื่องอ่านปิดอยู่)
เมื่อตั้งค่าออบเจ็กต์ SumUpPayment สามารถรวมพารามิเตอร์ทางเลือกต่อไปนี้ได้:
จำนวนทิปสามารถประมวลผลได้เพิ่มเติมจาก total โดยใช้พารามิเตอร์ tip จำนวนทิปจะแสดงในระหว่างขั้นตอนการชำระเงินและรวมอยู่ในการตอบกลับ โปรดทราบว่าจำนวนทิปไม่สามารถเปลี่ยนแปลงได้ในระหว่าง/หลังการชำระเงิน
ซึ่งช่วยให้ลูกค้าสามารถเพิ่มทิปบนเครื่องอ่านการ์ดได้โดยตรง แทนที่จะต้องแจ้งจำนวนทิปบนอุปกรณ์ Android
สามารถแจ้งจำนวนทิปได้โดยตรงในเครื่องอ่านการ์ดโดยใช้พารามิเตอร์ tipOnCardReader หากเครื่องอ่านบัตรรองรับการให้ทิป ดูตัวอย่างที่นี่สำหรับฟิลด์ tipOnCardReader
หมายเหตุ: เครื่องอ่านการ์ดบางรุ่นไม่รองรับคุณสมบัตินี้ หากต้องการทราบว่าคุณสมบัตินี้รองรับเครื่องอ่านการ์ดที่บันทึกไว้ล่าสุดหรือไม่ คุณควรตรวจสอบ
SumUpApi.isTipOnCardReaderAvailable()เสมอ คุณต้องจัดการกรณีนี้ด้วยตนเองเพื่อหลีกเลี่ยงการไม่ได้รับคำแนะนำ โปรดทราบว่าหากมีการเรียกทั้งtipและtipOnCardReaderจะมีการพิจารณาเฉพาะจำนวนtipOnCardReaderเท่านั้นในระหว่างชำระเงิน หากมี
คุณลักษณะ configureRetryPolicy() ช่วยให้คุณสามารถตั้งค่าพารามิเตอร์การลองใหม่แบบกำหนดเองสำหรับการดึงผลลัพธ์ธุรกรรม โดยใช้ pollingInterval , maxWaitingTime และ disableBackButton
pollingInterval และ maxWaitingTime ในหน่วยมิลลิวินาที โดยมีค่าเริ่มต้นที่ 2000 ms และ 60000 ms ตามลำดับ การตั้งค่า disableBackButton เป็น True จะปิดใช้งานปุ่มย้อนกลับระหว่างการลองใหม่maxWaitingTime ผ่านไปโดยไม่มีผลลัพธ์ SDK จะส่งกลับ SumUpAPI.ResultCode.ERROR_UNKNOWN_TRANSACTION_STATUS การกดปุ่มย้อนกลับ (หากเปิดใช้งาน) ระหว่างการลองใหม่จะทำให้เกิดข้อผิดพลาดนี้ด้วยpollingInterval เกิน maxWaitingTime maxWaitingTime จะถูกปรับให้ตรงกันโดยอัตโนมัติ ค่าลบสำหรับพารามิเตอร์ตัวใดตัวหนึ่งจะมีค่าเริ่มต้นเป็น 0configureRetryPolicy() SDK จะใช้ค่าเริ่มต้นในการส่งคืน SumUpAPI.ResultCode.ERROR_TRANSACTION_FAILED เมื่อใช้การชำระเงิน SumUp ดังภาพด้านล่าง:
SumupPayment . builder ()
...
. foreignTransactionId ( UUID . randomUUID (). toString ())
. configureRetryPolicy ( 2000 , 60000 , true )
. build (); หากมีปัญหาการเชื่อมต่อและไม่สามารถเรียกสถานะธุรกรรมได้ API จะส่งกลับ ERROR_UNKNOWN_TRANSACTION_STATUS ในกรณีเช่นนี้ คุณสามารถสืบค้นสถานะธุรกรรมได้โดยการเรียก API สถานะธุรกรรม SumUp โดยใช้ foreignTransactionId ที่ระบุ
ตัวระบุ foreignTransactionID จะเชื่อมโยงกับธุรกรรม และสามารถใช้เพื่อดึงรายละเอียดที่เกี่ยวข้องกับธุรกรรม ดูเอกสารประกอบ API สำหรับรายละเอียด โปรดตรวจสอบให้แน่ใจว่ารหัสนี้ไม่ซ้ำกันภายในขอบเขตของบัญชีผู้ค้า SumUp และบัญชีย่อย ต้องมีความยาวไม่เกิน 128 ตัวอักษร ForeignTransactionID จะพร้อมใช้งานเมื่อมีการเรียกกิจกรรมการเรียกกลับ: SumUpAPI.Param.FOREIGN_TRANSACTION_ID
หากต้องการข้ามหน้าจอความสำเร็จที่แสดงเมื่อสิ้นสุดธุรกรรมที่สำเร็จ คุณสามารถใช้พารามิเตอร์ skipSuccessScreen ได้ เมื่อใช้พารามิเตอร์นี้ แอปพลิเคชันของคุณมีหน้าที่รับผิดชอบในการแสดงผลธุรกรรมให้กับลูกค้า เมื่อใช้ร่วมกับ Receipts API แอปพลิเคชันของคุณยังสามารถส่งใบเสร็จรับเงินของคุณเองได้ โปรดดูรายละเอียดในเอกสารประกอบ API โปรดทราบว่าหน้าจอความสำเร็จจะยังคงแสดงอยู่เมื่อใช้เครื่องอ่าน SumUp Air Lite
หากต้องการข้ามหน้าจอที่ล้มเหลวซึ่งแสดงในตอนท้ายของธุรกรรมที่ล้มเหลว คุณสามารถใช้พารามิเตอร์ skipFailedScreen ได้ เมื่อใช้พารามิเตอร์นี้ แอปพลิเคชันของคุณมีหน้าที่รับผิดชอบในการแสดงผลธุรกรรมให้กับลูกค้า โปรดทราบว่าหน้าจอที่ล้มเหลวจะยังคงแสดงอยู่เมื่อใช้เครื่องอ่าน SumUp Air Lite
หากต้องการตรวจสอบสิทธิ์บัญชีโดยที่ผู้ใช้ไม่ได้พิมพ์ข้อมูลประจำตัว SumUp ในแต่ละครั้ง คุณสามารถสร้างโทเค็นการเข้าถึงโดยใช้ OAuth2.0 และใช้เพื่อเข้าสู่ระบบ SumUp SDK อย่างโปร่งใส
SumUpLogin sumupLogin = SumUpLogin . builder ( mAffiliateKey ). accessToken ( "MY_ACCESS_TOKEN" ). build ();
SumUpAPI . openLoginActivity ( MainActivity . this , sumupLogin , 1 );สำหรับข้อมูลเกี่ยวกับวิธีการรับโทเค็น โปรดดูเอกสารประกอบ API
หากโทเค็นไม่ถูกต้อง SumUpAPI.Response.ResultCode.ERROR_INVALID_TOKEN จะถูกส่งคืน
หากบัญชีผู้ขายเข้าสู่ระบบอยู่ ก็สามารถดึงข้อมูลสำหรับบัญชีนี้ได้
if (! SumUpAPI . isLoggedIn ()) {
// no merchant account currently logged in
} else {
Merchant currentMerchant = SumUpAPI . getCurrentMerchant ();
} SumUpAPI . logout (); buildTypes {
release {
// All ProGuard rules required by the SumUp SDK are packaged with the library
minifyEnabled true
proguardFiles getDefaultProguardFile( ' proguard-android.txt ' )
}
}SDK รองรับบริการระบุตำแหน่งของ Google เพื่อปรับปรุงความแม่นยำของตำแหน่งและลดการใช้พลังงาน
เพื่อที่จะใช้มัน คุณจะต้องเพิ่มการพึ่งพาในไฟล์ build.gradle
implementation " com.google.android.gms:play-services-location:19.0.1 "หากไม่ได้เพิ่มการพึ่งพา GLS ในโปรเจ็กต์หรือไม่ได้ติดตั้งบริการ Google Play บนอุปกรณ์มือถือ SumUp SDK จะระบุตำแหน่งด้วยบริการระบุตำแหน่งเริ่มต้นที่ Android มอบให้
หมายเหตุ: แนะนำให้ใช้ GLS เวอร์ชัน 19.0.1
ฟังก์ชันต่อไปนี้ได้รับการจัดการโดย SumUp API:
บันทึกการเปลี่ยนแปลง SumUp Android SDK
ใบอนุญาต SumUp Android SDK
