SoftPOS deeplink dokumentáció

A SoftPOS alkalmazás csomagnevei#

A kérést mindig a környezetnek megfelelő csomagnak kell címezni:

Android 11-től a hívó alkalmazásnak deklarálnia kell, hogy látja ezeket a csomagokat. E nélkül a hívás hibaüzenet nélkül nem indul el:

<queries>
    <package android:name="com.paynance.sideapp.release" />
    <package android:name="com.paynance.sideapp.test" />
</queries>

Deeplink küldése a SoftPOS alkalmazásnak#

A SoftPOS alkalmazást a következő módon lehet meghívni deeplink kéréssel:

val intent = Intent(Intent.ACTION_VIEW, Uri.parse(
    "paynance://sideapp/gateway" +
        "?ownerAppPackage=eu.paynance.softpos.tester" +
        "&ownerAppDeepLinkCallback=softpos-tester://gateway" +
        "&sessionId=92e6e172-b3b2-4a94-bf77-0c868f4e32ba" +
        "&sourceCode=ST3295L22322755KXC7LNFQ5S" +
        "&terminalId=52CDD12E-3DDF-4C73-A037-673124E9D03A" +
        "&cashRegisterId=CashRegisterId" +
        "&amount=12000" +
        "&currencyCode=348" +
        "&merchantReference=some-reference" +
        "&customerTrns=some-reference" +
        "&tipAmount=2000" +
        "&action=sale"
))

intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
intent.addFlags(Intent.FLAG_ACTIVITY_EXCLUDE_FROM_RECENTS)

A deeplink kérés válaszának fogadása#

A válasz egy ACTION_SEND típusú, text/json MIME-típusú intentben érkezik, amelyet a SoftPOS alkalmazás közvetlenül a kérésben megadott ownerAppPackage csomagnak címez. A teljes válasz JSON-ként az Intent.EXTRA_TEXT extrában található.

A fogadó alkalmazásnak ezt az intent-filtert kell deklarálnia az AndroidManifest.xml fájlban:

<activity
    android:name="com.example.URLResponseActivity"
    android:label="Payment Result"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.SEND"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:mimeType="text/json"/>
    </intent-filter>
</activity>

A válasz kiolvasása:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    handleResult(intent)
}

// Ha az Activity singleTop vagy singleTask módban fut
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    handleResult(intent)
}

private fun handleResult(intent: Intent) {
    val payload = intent.getStringExtra(Intent.EXTRA_TEXT) ?: return
    val message = JSONObject(payload).getJSONObject("message")

    val eventId = message.getInt("eventId")
    if (eventId == 0) {
        // sikeres tranzakció
    } else {
        // hiba - a részleteket a message mező tartalmazza
    }
}

A válasz felépítése#

Minden válasz egy burokba van csomagolva. A tranzakció adatai a message objektumon belül találhatók, nem a JSON gyökerében:

{
    "ownerAppPackage": "com.example.app",
    "ownerAppDeepLinkCallback": "app://callback",
    "message": {
        ...
    }
}

A burok ownerAppPackage és ownerAppDeepLinkCallback kulcsai csak akkor szerepelnek a válaszban, ha a kérés is tartalmazta őket – üres értékkel nem kerülnek bele.

Általános szabályok

• A hiányzó értékek helyén a "---" szöveg szerepel, nem null, és a kulcs sem marad ki.
• A currencyCode a válaszban mindig numerikus ISO 4217 kód (348 vagy978), akkor is, ha a kérésben betűkóddal érkezett.
• Az értékek típusosak: a success logikai érték, az eventId,currencyCode, amount és tipAmount szám.
• A tranzakció kimenetelét az eventId mező hordozza – erre érdemes ágazni.

Az eventId mező lehetséges értékei

• 0 – Sikeres tranzakció
• 1000 – A felhasználó megszakította a tranzakciót
• 1007 – A kártya elutasította a tranzakciót
• 1016 – Megszakadt tranzakció
• 1099 – Általános tranzakciós hiba
• 1100 – SZÉP-kártyás fizetés nem elérhető ezen a terminálon

Hibakeresés#