একটি Android পেমেন্ট অ্যাপ থেকে শিপিং এবং যোগাযোগের তথ্য প্রদান করা

ওয়েব পেমেন্ট API-এর সাথে শিপিং ঠিকানা এবং প্রদানকারীর যোগাযোগের তথ্য প্রদান করতে আপনার Android পেমেন্ট অ্যাপ কীভাবে আপডেট করবেন।

সাহেল শরিফী
Sahel Sharify
GitHub

একটি ওয়েব ফর্মের মাধ্যমে শিপিং ঠিকানা এবং যোগাযোগের তথ্য প্রবেশ করা গ্রাহকদের জন্য একটি কষ্টকর অভিজ্ঞতা হতে পারে। এটি ত্রুটি এবং কম রূপান্তর হার হতে পারে.

এই কারণেই অর্থপ্রদানের অনুরোধ API শিপিং ঠিকানা এবং যোগাযোগের তথ্যের অনুরোধ করার জন্য একটি বৈশিষ্ট্য সমর্থন করে। এটি একাধিক সুবিধা প্রদান করে:

  • ব্যবহারকারীরা মাত্র কয়েকটি ট্যাপ দিয়ে সঠিক ঠিকানা বেছে নিতে পারেন।
  • ঠিকানাটি সর্বদা প্রমিত বিন্যাসে ফেরত দেওয়া হয়।
  • একটি ভুল ঠিকানা জমা দেওয়ার সম্ভাবনা কম।

ব্রাউজারগুলি একটি একীভূত অর্থপ্রদানের অভিজ্ঞতা প্রদান করতে একটি অর্থপ্রদান অ্যাপে শিপিং ঠিকানা এবং যোগাযোগের তথ্য সংগ্রহকে পিছিয়ে দিতে পারে। এই কার্যকারিতাকে ডেলিগেশন বলা হয়।

যখনই সম্ভব, Chrome একজন গ্রাহকের শিপিং ঠিকানা এবং যোগাযোগের তথ্য সংগ্রহ করা Android পেমেন্ট অ্যাপে অর্পণ করে। প্রতিনিধি দল চেকআউটের সময় ঘর্ষণ হ্রাস করে।

বণিক ওয়েবসাইট গতিশীলভাবে শিপিং বিকল্প এবং মোট মূল্য আপডেট করতে পারে গ্রাহকের শিপিং ঠিকানা এবং শিপিং বিকল্পের পছন্দের উপর নির্ভর করে।

শিপিং বিকল্প এবং শিপিং ঠিকানা কর্মে পরিবর্তন. এটি কীভাবে শিপিং বিকল্পগুলি এবং মোট মূল্যকে গতিশীলভাবে প্রভাবিত করে তা দেখুন৷

ইতিমধ্যে বিদ্যমান Android পেমেন্ট অ্যাপে প্রতিনিধি সমর্থন যোগ করতে, নিম্নলিখিত পদক্ষেপগুলি বাস্তবায়ন করুন:

  1. সমর্থিত প্রতিনিধি দল ঘোষণা করুন ।
  2. প্রয়োজনীয় অর্থপ্রদানের বিকল্পগুলির জন্য PAY অভিপ্রায় অতিরিক্ত বিশ্লেষণ করুন ।
  3. পেমেন্ট প্রতিক্রিয়ায় প্রয়োজনীয় তথ্য প্রদান করুন ।
  4. [ঐচ্ছিক] গতিশীল প্রবাহ সমর্থন :
    1. ব্যবহারকারীর নির্বাচিত অর্থপ্রদানের পদ্ধতি, শিপিং ঠিকানা, বা শিপিং বিকল্পের পরিবর্তন সম্পর্কে বণিককে অবহিত করুন ।
    2. বণিকের কাছ থেকে আপডেট করা অর্থপ্রদানের বিবরণ পান (উদাহরণস্বরূপ, নির্বাচিত শিপিং বিকল্পের খরচের উপর ভিত্তি করে সামঞ্জস্যপূর্ণ মোট পরিমাণ)।

সমর্থিত প্রতিনিধি দল ঘোষণা করুন

ব্রাউজারকে অতিরিক্ত তথ্যের তালিকা জানতে হবে যা আপনার অর্থপ্রদান অ্যাপ প্রদান করতে পারে যাতে এটি সেই তথ্যের সংগ্রহ আপনার অ্যাপে অর্পণ করতে পারে। আপনার অ্যাপের AndroidManifest.xml- এ সমর্থিত প্রতিনিধিদের <meta-data> হিসেবে ঘোষণা করুন।

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

<resource> নিম্নলিখিত বৈধ মানগুলি থেকে নির্বাচিত স্ট্রিংগুলির একটি তালিকা হতে হবে:

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

নিম্নলিখিত উদাহরণটি শুধুমাত্র একটি শিপিং ঠিকানা এবং প্রদানকারীর ইমেল ঠিকানা প্রদান করতে পারে। 

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

প্রয়োজনীয় অর্থপ্রদানের বিকল্পগুলির জন্য PAY অভিপ্রায় অতিরিক্ত বিশ্লেষণ করুন

paymentOptions অভিধান ব্যবহার করে বণিক অতিরিক্ত প্রয়োজনীয় তথ্য নির্দিষ্ট করতে পারেন। ক্রোম প্রয়োজনীয় বিকল্পগুলির তালিকা প্রদান করবে যা আপনার অ্যাপ প্রদান করতে পারে নিম্নলিখিত প্যারামিটারগুলিকে ইন্টেন্ট অতিরিক্ত হিসাবে 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" হতে পারে। ব্যবহারকারীর ঠিকানা বা শিপিং বিকল্পের পছন্দের জন্য জিজ্ঞাসা করার সময় আপনার অ্যাপটি তার UI-তে এই ইঙ্গিতটি ব্যবহার করতে পারে।

shippingOptions

shippingOptions হল বণিকের নির্দিষ্ট শিপিং বিকল্পগুলির পার্সেলযোগ্য অ্যারে। এই প্যারামিটারটি তখনই বিদ্যমান থাকবে যখন paymentOptions.requestShipping == true ।

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

প্রতিটি শিপিং বিকল্প হল নিম্নলিখিত কীগুলির সাথে একটি Bundle ।

  • id - শিপিং বিকল্প শনাক্তকারী।
  • label - ব্যবহারকারীকে দেখানো শিপিং বিকল্প লেবেল।
  • amount - স্ট্রিং মান সহ currency এবং value কী ধারণকারী শিপিং খরচ বান্ডিল।
    • currency একটি ISO4217 সুগঠিত 3-অক্ষরের বর্ণমালা কোড হিসাবে শিপিং খরচের মুদ্রা দেখায়
    • 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")
    }
}

ঐচ্ছিক: গতিশীল প্রবাহ সমর্থন করে

কখনও কখনও একটি লেনদেনের মোট খরচ বেড়ে যায়, যেমন ব্যবহারকারী যখন এক্সপ্রেস শিপিং বিকল্পটি বেছে নেয়, বা যখন ব্যবহারকারী একটি আন্তর্জাতিক শিপিং ঠিকানা বেছে নেয় তখন উপলব্ধ শিপিং বিকল্পের তালিকা বা তাদের মূল্য পরিবর্তন হয়। যখন আপনার অ্যাপ ব্যবহারকারী-নির্বাচিত শিপিং ঠিকানা বা বিকল্প প্রদান করে, তখন এটি যেকোনো শিপিং ঠিকানা বা বিকল্প পরিবর্তন সম্পর্কে বণিককে অবহিত করতে এবং ব্যবহারকারীকে আপডেট করা অর্থপ্রদানের বিবরণ (বণিক দ্বারা সরবরাহ করা) দেখাতে সক্ষম হওয়া উচিত।

এআইডিএল

নতুন পরিবর্তন সম্পর্কে বণিককে অবহিত করতে Chrome-এর AndroidManifest.xml-এ ঘোষিত PaymentDetailsUpdateService পরিষেবা ব্যবহার করুন। এই পরিষেবাটি ব্যবহার করতে নিম্নলিখিত বিষয়বস্তু সহ দুটি AIDL ফাইল তৈরি করুন:

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 পেমেন্টের অনুরোধ শুরু করা ব্রাউজারের উপর নির্ভর করে নিম্নলিখিত মানগুলির মধ্যে একটি থাকতে পারে।

ক্রোম চ্যানেল প্যাকেজের নাম
স্থিতিশীল "com.android.chrome"
বেটা "com.chrome.beta"
দেব "com.chrome.dev"
ক্যানারি "com.chrome.canary"
ক্রোমিয়াম "org.chromium.chrome"
গুগল কুইক সার্চ বক্স (একটি ওয়েবলেয়ার এমবেডার) "com.google.android.googlequicksearchbox"

changePaymentMethod

ব্যবহারকারী-নির্বাচিত অর্থপ্রদানের পদ্ধতিতে পরিবর্তন সম্পর্কে বণিককে অবহিত করে। paymentHandlerMethodData বান্ডেলে methodName এবং স্ট্রিং মান সহ ঐচ্ছিক details কী রয়েছে। Chrome একটি অ-খালি methodName সহ একটি অ-খালি বান্ডিল পরীক্ষা করবে এবং বৈধতা ব্যর্থ হলে callback.updateWith এর মাধ্যমে নিম্নলিখিত ত্রুটি বার্তাগুলির মধ্যে একটি সহ একটি updatePaymentDetails পাঠাবে৷ 

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

changeShippingOption

ব্যবহারকারী-নির্বাচিত শিপিং বিকল্পের পরিবর্তন সম্পর্কে বণিককে অবহিত করে। shippingOptionId বণিক-নির্দিষ্ট শিপিং বিকল্পগুলির একটির শনাক্তকারী হওয়া উচিত। ক্রোম একটি অ-খালি shippingOptionId পরীক্ষা করবে এবং বৈধতা ব্যর্থ হলে callback.updateWith মাধ্যমে নিম্নলিখিত ত্রুটি বার্তা সহ একটি updatePaymentDetails পাঠাবে৷ 

'Shipping option identifier required.'

changeShippingAddress

ব্যবহারকারী-প্রদত্ত শিপিং ঠিকানায় পরিবর্তন সম্পর্কে বণিককে অবহিত করে। Chrome একটি বৈধ countryCode সহ একটি খালি shippingAddress বান্ডেল পরীক্ষা করবে এবং বৈধতা ব্যর্থ হলে callback.updateWith মাধ্যমে নিম্নলিখিত ত্রুটি বার্তা সহ একটি updatePaymentDetails পাঠাবে৷ 

'Payment app returned invalid shipping address in response.'

অবৈধ রাষ্ট্র ত্রুটি বার্তা

কোনো পরিবর্তনের অনুরোধ পাওয়ার পর Chrome যদি একটি অবৈধ অবস্থার সম্মুখীন হয় তবে এটি একটি সংশোধন করা updatePaymentDetails বান্ডেল সহ callback.updateWith কল করবে। বান্ডেলটিতে শুধুমাত্র "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 - শিপিং অপশনের পার্সেলযোগ্য অ্যারে
  • error - একটি সাধারণ ত্রুটি বার্তা ধারণকারী একটি স্ট্রিং (যেমন যখন changeShippingOption একটি বৈধ শিপিং বিকল্প শনাক্তকারী প্রদান করে না)
  • stringifiedPaymentMethodErrors - একটি JSON স্ট্রিং যা অর্থপ্রদানের পদ্ধতির জন্য বৈধতা ত্রুটির প্রতিনিধিত্ব করে
  • addressErrors - শিপিং ঠিকানা এবং স্ট্রিং মানগুলির সাথে অভিন্ন ঐচ্ছিক কী সহ একটি বান্ডিল৷ প্রতিটি কী শিপিং ঠিকানার সংশ্লিষ্ট অংশের সাথে সম্পর্কিত একটি বৈধতা ত্রুটি উপস্থাপন করে।

একটি অনুপস্থিত কী মানে এর মান পরিবর্তন হয়নি।