Android पेमेंट ऐप्लिकेशन से शिपिंग और संपर्क जानकारी देना

Web Payments API के ज़रिए शिपिंग पता और पैसे चुकाने वाले की संपर्क जानकारी देने के लिए, Android पेमेंट ऐप्लिकेशन को अपडेट करने का तरीका.

Sahel Sharify
Sahel Sharify
GitHub

वेब फ़ॉर्म के ज़रिए शिपिंग पता और संपर्क जानकारी डालने पर काफ़ी मुश्किल काम हो सकता है. इससे गड़बड़ियां हो सकती हैं और कन्वर्ज़न कम हो सकता है दर.

इसलिए, Payment Request API, शिपिंग का अनुरोध करने के लिए एक सुविधा के साथ काम करती है पता और संपर्क जानकारी. इससे कई फ़ायदे मिलते हैं:

ब्राउज़र, शिपिंग पते और संपर्क जानकारी को इकट्ठा करने की प्रोसेस को आगे बढ़ा सकते हैं पेमेंट ऐप्लिकेशन का इस्तेमाल करें. यह सुविधा डेलिगेशन कहा जाता है.

जब भी मुमकिन हो, Chrome, खरीदार की शिपिंग का कलेक्शन अपने-आप उपलब्ध कराता है पते और संपर्क जानकारी को Android पेमेंट ऐप्लिकेशन पर भेजना होगा. कॉन्टेंट बनाने चेकआउट के दौरान होने वाली परेशानी कम कर दी जाती है.

कारोबारी या कंपनी की वेबसाइट पर, शिपिंग के विकल्पों और कुल कीमत को डाइनैमिक तरीके से अपडेट किया जा सकता है शिपिंग पते और शिपिंग के लिए ग्राहक की पसंद के आधार पर का विकल्प शामिल है.

कार्रवाई में शिपिंग विकल्प और शिपिंग पते में बदलाव. देखें कि इससे शिपिंग के विकल्पों और कुल कीमत पर डाइनैमिक तौर पर कैसे असर पड़ता है.

पहले से मौजूद Android पेमेंट ऐप्लिकेशन में, काम का ऐक्सेस देने की सुविधा जोड़ने के लिए, ये चरण लागू करें:

  1. इस्तेमाल किए जा सकने वाले ऐक्सेस का एलान करना.
  2. ज़रूरी पेमेंट के लिए, PAY इंटेंट के अतिरिक्त को पार्स करें के विकल्प.
  3. पेमेंट करते समय ज़रूरी जानकारी देना जवाब.
  4. [ज़रूरी नहीं] डाइनैमिक फ़्लो के साथ काम करता है:
    1. उपयोगकर्ता के चुने गए पेमेंट के तरीके में हुए बदलावों के बारे में कारोबारी को सूचना दें, शिपिंग पता या शिपिंग का विकल्प भी होता है.
    2. कारोबारी से अपडेट किए गए पेमेंट के तरीके की जानकारी पाना (उदाहरण के लिए, शिपिंग के चुने गए विकल्प के हिसाब से बदली गई कुल रकम लागत).

उन लोगों के बारे में बताएं जिनका इस्तेमाल किया जा सकता है

ब्राउज़र को उन अतिरिक्त जानकारी की सूची पता होनी चाहिए जो आपके पेमेंट के तरीके में शामिल हैं ऐप्लिकेशन उपलब्ध करा सकता है, ताकि वह उस जानकारी का संग्रह आपके है. अपने ऐप्लिकेशन के ऐक्सेस लेवल का एलान <meta-data> के तौर पर करें AndroidManifest.xml.

<activity
  android:name=".PaymentActivity"
  …
  <meta-data
    android:name="org.chromium.payment_supported_delegations"
    android:resource="@array/supported_delegations" />
</activity>

<resource>, स्ट्रिंग की ऐसी सूची होनी चाहिए जिसे इन मान्य वैल्यू में से चुना गया हो:

[ "payerName", "payerEmail", "payerPhone", "shippingAddress" ]

नीचे दिए गए उदाहरण में सिर्फ़ शिपिंग पता और पैसे चुकाने वाले का ईमेल पता दिया जा सकता है इससे पहले ही अपने कारोबार के हिसाब से name@yourcompany.com जैसा कोई ईमेल पता बनाएं.

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <string-array name="supported_delegations">
    <item>payerEmail</item>
    <item>shippingAddress</item>
  </string-array>
</resources>

पेमेंट के ज़रूरी विकल्पों के लिए, PAY इंटेंट के अतिरिक्त को पार्स करें

कारोबारी या कंपनी, इसका इस्तेमाल करके अतिरिक्त ज़रूरी जानकारी दे सकती है paymentOptions शब्दकोश. Chrome उन ज़रूरी विकल्पों की सूची उपलब्ध कराएगा जिन्हें आपका ऐप्लिकेशन उपलब्ध करा सकता है इन पैरामीटर को PAY गतिविधि में इंटेंट के तौर पर पास करके उपलब्ध कराएं अतिरिक्त चीज़ें.

paymentOptions

paymentOptions, व्यापारी/कंपनी/कारोबारी के बताए गए पेमेंट के विकल्पों का सबसेट है, जिसके लिए आपके ऐप्लिकेशन ने दूसरे लोगों को अपने ईमेल खाते का ऐक्सेस देने का एलान किया है.

val paymentOptions: Bundle? = extras.getBundle("paymentOptions")
val requestPayerName: Boolean? = paymentOptions?.getBoolean("requestPayerName")
val requestPayerPhone: Boolean? = paymentOptions?.getBoolean("requestPayerPhone")
val requestPayerEmail: Boolean? = paymentOptions?.getBoolean("requestPayerEmail")
val requestShipping: Boolean? = paymentOptions?.getBoolean("requestShipping")
val shippingType: String? = paymentOptions?.getString("shippingType")

इसमें ये पैरामीटर शामिल हो सकते हैं:

  • requestPayerName - बूलियन से पता चलता है कि पैसे चुकाने वाले का नाम है या नहीं आवश्यक है.
  • requestPayerPhone - बूलियन से पता चलता है कि पैसे चुकाने वाले का फ़ोन नंबर है या नहीं आवश्यक है.
  • requestPayerEmail - बूलियन से पता चलता है कि पैसे चुकाने वाले का ईमेल पता है या नहीं आवश्यक है.
  • requestShipping - बूलियन से पता चलता है कि शिपिंग की जानकारी दी गई है या नहीं आवश्यक है.
  • shippingType - शिपिंग का टाइप दिखाने वाली स्ट्रिंग. शिपिंग का टाइप: "shipping", "delivery" या "pickup". आपका ऐप्लिकेशन इस संकेत का इस्तेमाल इसके लिए कर सकता है: यूज़र इंटरफ़ेस (यूआई) की इमेज, जिसमें लोगों से शिपिंग के विकल्प या पता डालने के बारे में पूछा जाता है.

shippingOptions

shippingOptions, व्यापारी/कंपनी/कारोबारी की ओर से तय की गई शिपिंग का पार्स किया जा सकने वाला कलेक्शन है के विकल्प. यह पैरामीटर सिर्फ़ तब दिखेगा, जब paymentOptions.requestShipping == true.

val shippingOptions: List<ShippingOption>? =
    extras.getParcelableArray("shippingOptions")?.mapNotNull {
        p -> from(p as Bundle)
    }

शिपिंग का हर विकल्प एक Bundle है. इसमें ये कुंजियां भी शामिल हैं.

  • id - शिपिंग के विकल्प का आइडेंटिफ़ायर.
  • label - उपयोगकर्ता को दिखाया गया शिपिंग के विकल्प का लेबल.
  • amount - शिपिंग के लिए खरीदार से लिए जाने वाले शुल्क के बंडल में currency और value कुंजियां शामिल हैं स्ट्रिंग वैल्यू.
  • selected - शिपिंग के विकल्प को चुना जाना चाहिए या नहीं पेमेंट ऐप्लिकेशन में शिपिंग के विकल्प दिख रहे हैं.

selected के अलावा, सभी कुंजियों में स्ट्रिंग वैल्यू होती हैं. selected में बूलियन है वैल्यू.

val id: String = bundle.getString("id")
val label: String = bundle.getString("label")
val amount: Bundle = bundle.getBundle("amount")
val selected: Boolean = bundle.getBoolean("selected", false)

पेमेंट के जवाब में ज़रूरी जानकारी देना

आपके ऐप्लिकेशन को जवाब में ज़रूरी अतिरिक्त जानकारी शामिल करनी चाहिए PAY गतिविधि.

ऐसा करने के लिए, नीचे दिए गए पैरामीटर को इंटेंट एक्स्ट्रा के तौर पर बताना ज़रूरी है:

  • payerName - पैसे चुकाने वाले का पूरा नाम. यह स्ट्रिंग ऐसी होनी चाहिए जो खाली न हो paymentOptions.requestPayerName सही है.
  • payerPhone - पैसे चुकाने वाले का फ़ोन नंबर. यह स्ट्रिंग ऐसी होनी चाहिए जो खाली न हो paymentOptions.requestPayerPhone सही है.
  • payerEmail - पैसे चुकाने वाले का ईमेल पता. यह स्ट्रिंग खाली नहीं होनी चाहिए जब paymentOptions.requestPayerEmail सही हो.
  • shippingAddress - उपयोगकर्ता की ओर से दिया गया शिपिंग पता. इसे paymentOptions.requestShipping सही होने पर गैर-खाली बंडल. बंडल के अलग-अलग हिस्सों को फ़िज़िकल पता.
    • city
    • countryCode
    • dependentLocality
    • organization
    • phone
    • postalCode
    • recipient
    • region
    • sortingCode
    • addressLine अभी तक किसी भी व्यक्ति ने चेक इन नहीं किया है addressLine के अलावा, सभी कुंजियों में स्ट्रिंग वैल्यू होती हैं. addressLine स्ट्रिंग का कलेक्शन है.
  • shippingOptionId - उपयोगकर्ता के चुने गए शिपिंग विकल्प का आइडेंटिफ़ायर. यह paymentOptions.requestShipping के सही होने पर, स्ट्रिंग खाली नहीं होनी चाहिए.

पेमेंट के जवाब की पुष्टि करें

अगर अनुरोध किए गए पेमेंट की वजह से मिला पेमेंट रिस्पॉन्स ऐप्लिकेशन को RESULT_OK पर सेट किया गया है. इसके बाद, Chrome अन्य ज़रूरी चीज़ों की जांच करेगा जानकारी को भी शामिल करें. अगर पुष्टि नहीं हो पाती है, तो Chrome ऐसे मैसेज दिखाएगा जिसे अस्वीकार कर दिया गया है request.show() से प्रॉमिस, डेवलपर को दी जाने वाली इनमें से किसी एक गड़बड़ी के साथ संदेश:

'Payment app returned invalid response. Missing field "payerEmail".'
'Payment app returned invalid response. Missing field "payerName".'
'Payment app returned invalid response. Missing field "payerPhone".'
'Payment app returned invalid shipping address in response.'
'... is not a valid CLDR country code, should be 2 upper case letters [A-Z]'
'Payment app returned invalid response. Missing field "shipping option".'

नीचे दिया गया कोड सैंपल, एक मान्य जवाब का उदाहरण है:

fun Intent.populateRequestedPaymentOptions() {
    if (requestPayerName) {
        putExtra("payerName", "John Smith")
    }
    if (requestPayerPhone) {
        putExtra("payerPhone", "4169158200")
    }
    if (requestPayerEmail) {
        putExtra("payerEmail", "john.smith@gmail.com")
    }
    if(requestShipping) {
        val address: Bundle = Bundle()
        address.putString("countryCode", "CA")
        val addressLines: Array<String> =
                arrayOf<String>("111 Richmond st. West")
        address.putStringArray("addressLines", addressLines)
        address.putString("region", "Ontario")
        address.putString("city", "Toronto")
        address.putString("postalCode", "M5H2G4")
        address.putString("recipient", "John Smith")
        address.putString("phone", "4169158200")
        putExtra("shippingAddress", address)
        putExtra("shippingOptionId", "standard")
    }
}

ज़रूरी नहीं: डाइनैमिक फ़्लो के साथ काम करता है

कभी-कभी लेन-देन की कुल लागत बढ़ जाती है, जैसे कि जब उपयोगकर्ता एक्सप्रेस शिपिंग का विकल्प चुनता है या तब चुनता है, जब उपलब्ध शिपिंग की सूची में उपयोगकर्ता के अंतरराष्ट्रीय शिपिंग का विकल्प चुनने पर, उनके विकल्पों या कीमतों में बदलाव होता है इससे पहले ही अपने कारोबार के हिसाब से name@yourcompany.com जैसा कोई ईमेल पता बनाएं. जब आपका ऐप्लिकेशन, उपयोगकर्ता का चुना गया शिपिंग पता या विकल्प उपलब्ध कराता है, तो वह किसी भी शिपिंग पते या विकल्प के बारे में व्यापारी को सूचित करने में सक्षम होना चाहिए बदल सकते हैं और उपयोगकर्ता को अपडेट किए गए पेमेंट के तरीके की जानकारी दिखा सकते हैं. व्यापारी/कंपनी/कारोबारी) के तौर पर शामिल होना चाहिए.

एआईडीएल

व्यापारी/कंपनी को नए बदलावों के बारे में बताने के लिए, PaymentDetailsUpdateService का इस्तेमाल करें सेवा का एलान Chrome की AndroidManifest.xml में कर दिया गया है. इस सेवा का उपयोग करने के लिए दो बनाएं ऐसी एआईडीएल फ़ाइलें जिनमें यह कॉन्टेंट होता है:

app/src/main/aidl/org/chromium/components/payments/IPaymentDetailsUpdateService

package org.chromium.components.payments;
import android.os.Bundle;

interface IPaymentDetailsUpdateServiceCallback {
    oneway void updateWith(in Bundle updatedPaymentDetails);

    oneway void paymentDetailsNotUpdated();
}

app/src/main/aidl/org/chromium/components/payments/IPaymentDetailsUpdateServiceCallback

package org.chromium.components.payments;
import android.os.Bundle;
import org.chromium.components.payments.IPaymentDetailsUpdateServiceCallback;

interface IPaymentDetailsUpdateService {
    oneway void changePaymentMethod(in Bundle paymentHandlerMethodData,
            IPaymentDetailsUpdateServiceCallback callback);

    oneway void changeShippingOption(in String shippingOptionId,
            IPaymentDetailsUpdateServiceCallback callback);

    oneway void changeShippingAddress(in Bundle shippingAddress,
            IPaymentDetailsUpdateServiceCallback callback);
}

उपयोगकर्ता के चुने गए पेमेंट के तरीके, शिपिंग पते या शिपिंग के विकल्प में हुए बदलावों के बारे में कारोबारी को सूचना दें

private fun bind() {
    // The action is introduced in Chrome version 92, which supports the service in Chrome
    // and other browsers (e.g., WebLayer).
    val newIntent = Intent("org.chromium.intent.action.UPDATE_PAYMENT_DETAILS")
        .setPackage(callingBrowserPackage)
    if (packageManager.resolveService(newIntent, PackageManager.GET_RESOLVED_FILTER) == null) {
        // Fallback to Chrome-only approach.
        newIntent.setClassName(
            callingBrowserPackage,
            "org.chromium.components.payments.PaymentDetailsUpdateService")
        newIntent.action = IPaymentDetailsUpdateService::class.java.name
    }
    isBound = bindService(newIntent, connection, Context.BIND_AUTO_CREATE)
}

private val connection = object : ServiceConnection {
    override fun onServiceConnected(className: ComponentName, service: IBinder) {
        val service = IPaymentDetailsUpdateService.Stub.asInterface(service)
        try {
            if (isOptionChange) {
                service?.changeShippingOption(selectedOptionId, callback)
            } else (isAddressChange) {
                service?.changeShippingAddress(selectedAddress, callback)
            } else {
                service?.changePaymentMethod(methodData, callback)
            }
        } catch (e: RemoteException) {
            // Handle the remote exception
        }
    }
}

सेवा के शुरुआती इंटेंट के लिए इस्तेमाल किए जाने वाले callingPackageName में इनमें से कोई एक हो सकता है भुगतान शुरू करने वाले ब्राउज़र के आधार पर नीचे दिया गया मान दिखाई देगा अनुरोध.

Chrome चैनल पैकेज का नाम
स्थिर रुझान "com.android.chrome"
बीटा "com.chrome.beta"
डेव "com.chrome.dev"
कैनेरी "com.chrome.canary"
Chromium "org.chromium.chrome"
Google क्विक सर्च बॉक्स (Weblayer एम्बेडर) "com.google.android.googlequicksearchbox"

changePaymentMethod

उपयोगकर्ता के चुने गए पेमेंट के तरीके में हुए बदलावों के बारे में व्यापारी/कंपनी को सूचना देता है. कॉन्टेंट बनाने paymentHandlerMethodData बंडल में methodName और वैकल्पिक details शामिल है दोनों कुंजियों को स्ट्रिंग मान के साथ सेट करती है. Chrome ऐसे बंडल की जांच करेगा जो खाली नहीं है. साथ ही, methodName खाली नहीं है और इनमें से किसी एक के साथ updatePaymentDetails भेजें पुष्टि नहीं होती है, तो callback.updateWith के ज़रिए गड़बड़ी के मैसेज दिखाई देंगे.

'Method data required.'
'Method name required.'

changeShippingOption

व्यापारी/कंपनी को, उपयोगकर्ता के चुने गए शिपिंग विकल्प में हुए बदलावों के बारे में सूचना देता है. shippingOptionId, व्यापारी/कंपनी/कारोबारी की ओर से बताए गए किसी एक आइडेंटिफ़ायर का आइडेंटिफ़ायर होना चाहिए शिपिंग के विकल्प दिए जाते हैं. Chrome, shippingOptionId खाली नहीं होने की जांच करेगा और उसे इसके ज़रिए एक updatePaymentDetails पुष्टि नहीं हो पाती है, तो callback.updateWith.

'Shipping option identifier required.'

changeShippingAddress

उपयोगकर्ता के दिए गए शिपिंग पते में हुए बदलाव के बारे में, व्यापारी/कंपनी को सूचना देता है. Chrome ऐसे shippingAddress बंडल की जांच करेगा जो खाली न हो और जिसमें मान्य countryCode शामिल हो और इसके ज़रिए नीचे गड़बड़ी के मैसेज के साथ updatePaymentDetails भेजें पुष्टि नहीं हो पाती है, तो callback.updateWith.

'Payment app returned invalid shipping address in response.'

अमान्य स्थिति की गड़बड़ी का मैसेज

अगर बदलाव करने का कोई भी अनुरोध मिलने पर, Chrome को किसी अमान्य स्थिति का सामना करना पड़ता है यह callback.updateWith को कॉल करेगा और जानकारी को छिपाने के लिए बदलाव किया गया updatePaymentDetails होगा बंडल. बंडल में "Invalid state" वाली सिर्फ़ error कुंजी होगी. अमान्य स्थिति के उदाहरण यहां दिए गए हैं:

  • जब Chrome पिछले बदलाव के लिए कारोबारी के जवाब का इंतज़ार कर रहा हो (जैसे, लगातार होने वाले बदलाव से जुड़ा इवेंट).
  • पेमेंट ऐप्लिकेशन से मिला शिपिंग के विकल्प का आइडेंटिफ़ायर, इनमें से किसी भी वैल्यू से नहीं जुड़ा है शिपिंग के विकल्प दिए जाते हैं.

कारोबारी से पेमेंट के तरीके की अपडेट की गई जानकारी पाना

private fun unbind() {
    if (isBound) {
        unbindService(connection)
        isBound = false
    }
}

private val callback: IPaymentDetailsUpdateServiceCallback =
    object : IPaymentDetailsUpdateServiceCallback.Stub() {
        override fun paymentDetailsNotUpdated() {
            // Payment request details have not changed.
            unbind()
        }

        override fun updateWith(updatedPaymentDetails: Bundle) {
            newPaymentDetails = updatedPaymentDetails
            unbind()
        }
    }

updatePaymentDetails इसके बराबर है PaymentRequestDetailsUpdate WebIDL डिक्शनरी (डेटा को छिपाने के लिए modifiers फ़ील्ड) और ये वैकल्पिक कुंजियां होती हैं:

  • total - एक बंडल जिसमें currency और value कुंजियां हैं, दोनों में ये कुंजियां हैं स्ट्रिंग की वैल्यू
  • shippingOptions - shipping (शिपिंग) का पार्स किया जा सकने वाला अरे विकल्प
  • error - ऐसी स्ट्रिंग जिसमें सामान्य गड़बड़ी का मैसेज होता है (जैसे, जब changeShippingOption, शिपिंग के विकल्प का मान्य आइडेंटिफ़ायर नहीं देता)
  • stringifiedPaymentMethodErrors - पुष्टि करने वाली JSON स्ट्रिंग पेमेंट के तरीके से जुड़ी गड़बड़ियां
  • addressErrors - शिपिंग के समान वैकल्पिक कुंजियों वाला बंडल पता और स्ट्रिंग वैल्यू. हर कुंजी, एक-दूसरे से जुड़ी पुष्टि की गड़बड़ी दिखाती है शिपिंग पते का हिस्सा होता है.

कुंजी मौजूद न होने का मतलब है कि उसकी वैल्यू में बदलाव नहीं हुआ है.