शिपिंग का पता और पैसे चुकाने वाले व्यक्ति की संपर्क जानकारी देने के लिए, Android पर पेमेंट करने वाले ऐप्लिकेशन को Web Payments API के साथ अपडेट करने का तरीका.
पब्लिश होने की तारीख: 17 जुलाई, 2020, पिछली बार अपडेट किए जाने की तारीख: 27 मई, 2025
वेब फ़ॉर्म के ज़रिए शिपिंग का पता और संपर्क जानकारी डालना, ग्राहकों के लिए मुश्किल हो सकता है. इससे गड़बड़ियां हो सकती हैं और कन्वर्ज़न रेट कम हो सकता है.
इसलिए, Payment Request API में शिपिंग पते और संपर्क जानकारी का अनुरोध करने की सुविधा उपलब्ध है. इससे कई फ़ायदे मिलते हैं:
- उपयोगकर्ता, कुछ ही टैप में सही पता चुन सकते हैं.
- पते को हमेशा स्टैंडर्ड फ़ॉर्मैट में दिखाया जाता है.
- गलत पता सबमिट करने की संभावना कम हो जाती है.
ब्राउज़र, शिपिंग के पते और संपर्क जानकारी को पेमेंट ऐप्लिकेशन के साथ शेयर करने में देरी कर सकते हैं, ताकि पेमेंट करने का एक जैसा अनुभव मिल सके. इस सुविधा को प्रतिनिधि के तौर पर काम करना कहा जाता है.
जब भी मुमकिन होता है, Chrome, खरीदार के शिपिंग पते और संपर्क जानकारी को इकट्ठा करने का काम, Android पर पेमेंट की सुविधा देने वाले ऐप्लिकेशन को सौंप देता है. ऐसा करने से, चेकआउट के दौरान आने वाली समस्याएं कम हो जाती हैं.
कारोबारी या कंपनी की वेबसाइट, शिपिंग के विकल्पों और कुल कीमत को डाइनैमिक तौर पर अपडेट कर सकती है. यह अपडेट, ग्राहक के चुने गए शिपिंग पते और शिपिंग के विकल्प के आधार पर होता है.
किसी मौजूदा Android पेमेंट ऐप्लिकेशन में डेलिगेशन की सुविधा जोड़ने के लिए, यह तरीका अपनाएं:
- डेलिगेशन की सुविधा के बारे में एलान करें.
- पेमेंट के ज़रूरी विकल्पों के लिए,
PAY
इंटेंट एक्स्ट्रा पार्स करें. - पेमेंट के रिस्पॉन्स में ज़रूरी जानकारी दें.
- ज़रूरी नहीं: डाइनैमिक फ़्लो की सुविधा चालू करें:
प्रतिनिधि के तौर पर काम करने की सुविधा के बारे में जानकारी देना
ब्राउज़र को उस अतिरिक्त जानकारी की सूची के बारे में पता होना चाहिए जो आपका पेमेंट ऐप्लिकेशन दे सकता है, ताकि वह उस जानकारी को इकट्ठा करने का काम आपके ऐप्लिकेशन को सौंप सके. अपने ऐप्लिकेशन के AndroidManifest.xml में, <meta-data>
के तौर पर, उन डेलिगेशन के बारे में एलान करें जिनके लिए सहायता उपलब्ध है.
<activity
android:name=".PaymentActivity"
…
<meta-data
android:name="org.chromium.payment_supported_delegations"
android:resource="@array/chromium_payment_supported_delegations" />
</activity>
android:resource
को ऐसे <string-array>
की ओर ले जाना चाहिए जिसमें ये सभी या इनमें से कुछ वैल्यू शामिल हों:
payerName
payerEmail
payerPhone
shippingAddress
यहां दिए गए उदाहरण में, सिर्फ़ शिपिंग का पता और खरीदार का ईमेल पता दिया जा सकता है.
<?xml version="1.0" encoding="utf-8"?>
<resources>
<string-array name="chromium_payment_supported_delegations">
<item>payerEmail</item>
<item>shippingAddress</item>
</string-array>
</resources>
पेमेंट के ज़रूरी विकल्पों के लिए, PAY
इंटेंट एक्स्ट्रा पार्स करें
कारोबारी या कंपनी, paymentOptions
डिक्शनरी का इस्तेमाल करके, ज़रूरी अतिरिक्त जानकारी दे सकती है. Chrome, ज़रूरी विकल्पों की सूची देगा. आपका ऐप्लिकेशन, PAY
गतिविधि को paymentOptions
इंटेंट एक्स्ट्रा पास करके, ये विकल्प उपलब्ध करा सकता है.
paymentOptions
paymentOptions
, कारोबारी या कंपनी की ओर से तय किए गए पेमेंट के उन विकल्पों का सबसेट है जिनके लिए आपके ऐप्लिकेशन ने डेलिगेशन की सुविधा उपलब्ध कराई है.
Kotlin
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")
Java
Bundle paymentOptions = extras.getBundle("paymentOptions");
if (paymentOptions != null) {
Boolean requestPayerName = paymentOptions.getBoolean("requestPayerName");
Boolean requestPayerPhone = paymentOptions.getBoolean("requestPayerPhone");
Boolean requestPayerEmail = paymentOptions.getBoolean("requestPayerEmail");
Boolean requestShipping = paymentOptions.getBoolean("requestShipping");
String shippingType = paymentOptions.getString("shippingType");
}
इसमें ये पैरामीटर शामिल हो सकते हैं:
requestPayerName
- यह बूलियन वैल्यू बताती है कि पेमेंट करने वाले का नाम ज़रूरी है या नहीं.requestPayerPhone
- यह बूलियन वैल्यू है. इससे पता चलता है कि खरीदार का फ़ोन नंबर देना ज़रूरी है या नहीं.requestPayerEmail
- यह बूलियन वैल्यू बताती है कि खरीदार का ईमेल पता देना ज़रूरी है या नहीं.requestShipping
- यह बूलियन वैल्यू बताती है कि शिपिंग की जानकारी देना ज़रूरी है या नहीं.shippingType
- शिपिंग का टाइप दिखाने वाली स्ट्रिंग. शिपिंग टाइप की वैल्यू"shipping"
,"delivery"
या"pickup"
हो सकती है. जब आपका ऐप्लिकेशन, उपयोगकर्ता से पता या शिपिंग के विकल्प चुनने के लिए कहता है, तब वह इस हिंट का इस्तेमाल अपने यूज़र इंटरफ़ेस (यूआई) में कर सकता है.
shippingOptions
shippingOptions
, कारोबारी या कंपनी के तय किए गए शिपिंग के विकल्पों का पार्सल किया जा सकने वाला कलेक्शन है. यह पैरामीटर सिर्फ़ तब मौजूद होगा, जब paymentOptions.requestShipping ==
true
.
Kotlin
val shippingOptions: List<ShippingOption>? =
extras.getParcelableArray("shippingOptions")?.mapNotNull {
p -> from(p as Bundle)
}
Java
Parcelable[] shippingOptions = extras.getParcelableArray("shippingOptions");
for (Parcelable it : shippingOptions) {
if (it != null && it instanceof Bundle) {
Bundle shippingOption = (Bundle) it;
}
}
हर शिपिंग विकल्प एक Bundle
होता है. इसमें ये कुंजियां होती हैं.
id
- शिपिंग के विकल्प का आइडेंटिफ़ायर.label
- शिपिंग के विकल्प का वह लेबल जो खरीदार को दिखाया जाता है.amount
- शिपिंग के लिए खरीदार से लिए जाने वाले शुल्क का बंडल. इसमेंcurrency
औरvalue
कुंजियां होती हैं. इनकी वैल्यू स्ट्रिंग होती हैं.currency
में शिपिंग के लिए खरीदार से लिए जाने वाले शुल्क की मुद्रा दिखाई गई है. यह ISO4217 के मुताबिक, तीन अक्षरों वाला मान्य कोड हैvalue
में शिपिंग के लिए खरीदार से लिए जाने वाले शुल्क की वैल्यू को दशमलव में मान्य मुद्रा वैल्यू के तौर पर दिखाया गया है
selected
- Whether or not the shipping option should be selected when the payment app displays the shipping options.
selected
को छोड़कर, सभी कुंजियों में स्ट्रिंग वैल्यू होती हैं. selected
की वैल्यू बूलियन है.
Kotlin
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)
Java
String id = bundle.getString("id");
String label = bundle.getString("label");
Bundle amount = bundle.getBundle("amount");
Boolean selected = bundle.getBoolean("selected", false);
पेमेंट के रिस्पॉन्स में ज़रूरी जानकारी देना
आपके ऐप्लिकेशन को PAY
गतिविधि के जवाब में, ज़रूरी अतिरिक्त जानकारी शामिल करनी चाहिए.
इसके लिए, इन पैरामीटर को Intent के अतिरिक्त डेटा के तौर पर सेट करना होगा:
payerName
- पेमेंट करने वाले का पूरा नाम.paymentOptions.requestPayerName
की वैल्यू 'सही' होने पर, इस फ़ील्ड में कोई वर्ण होना चाहिए.payerPhone
- पैसे चुकाने वाले का फ़ोन नंबर.paymentOptions.requestPayerPhone
की वैल्यू 'सही' होने पर, इस फ़ील्ड में कोई वर्ण होना चाहिए.payerEmail
- पेमेंट करने वाले का ईमेल पता.paymentOptions.requestPayerEmail
के सही होने पर, यह एक ऐसी स्ट्रिंग होनी चाहिए जिसमें कोई वैल्यू मौजूद हो.shippingAddress
- उपयोगकर्ता ने शिपिंग के लिए जो पता दिया है.paymentOptions.requestShipping
की वैल्यू 'सही' होने पर, यह बंडल खाली नहीं होना चाहिए. बंडल में ये कुंजियां होनी चाहिए. ये भौतिक पते के अलग-अलग हिस्सों को दिखाती हैं.countryCode
postalCode
sortingCode
region
city
dependentLocality
addressLine
organization
recipient
phone
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".'
यहां दिए गए कोड का सैंपल, मान्य जवाब का एक उदाहरण है:
Kotlin
fun Intent.populateRequestedPaymentOptions() {
if (requestPayerName) {
putExtra("payerName", "John Smith")
}
if (requestPayerPhone) {
putExtra("payerPhone", "5555555555")
}
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", "5555555555")
putExtra("shippingAddress", address)
putExtra("shippingOptionId", "standard")
}
}
Java
private Intent populateRequestedPaymentOptions() {
Intent result = new Intent();
if (requestPayerName) {
result.putExtra("payerName", "John Smith");
}
if (requestPayerPhone) {
presult.utExtra("payerPhone", "5555555555");
}
if (requestPayerEmail) {
result.putExtra("payerEmail", "john.smith@gmail.com");
}
if (requestShipping) {
Bundle address = new Bundle();
address.putExtra("countryCode", "CA");
address.putExtra("postalCode", "M5H2G4");
address.putExtra("region", "Ontario");
address.putExtra("city", "Toronto");
String[] addressLines = new String[] {"111 Richmond st. West"};
address.putExtra("addressLines", addressLines);
address.putExtra("recipient", "John Smith");
address.putExtra("phone", "5555555555");
result.putExtra("shippingAddress", address);
result.putExtra("shippingOptionId", "standard");
}
return result;
}
ज़रूरी नहीं: डाइनैमिक फ़्लो की सुविधा
कभी-कभी लेन-देन की कुल लागत बढ़ जाती है. जैसे, जब उपयोगकर्ता एक्सप्रेस शिपिंग का विकल्प चुनता है या जब उपयोगकर्ता किसी दूसरे देश का शिपिंग पता चुनता है, तो शिपिंग के लिए उपलब्ध विकल्पों या उनकी कीमतों की सूची बदल जाती है. अगर आपका ऐप्लिकेशन, खरीदार के चुने गए शिपिंग पते या विकल्प की जानकारी देता है, तो उसे कारोबारी या कंपनी को शिपिंग पते या विकल्प में हुए किसी भी बदलाव के बारे में सूचना देनी चाहिए. साथ ही, खरीदार को पेमेंट के अपडेट की गई जानकारी (कारोबारी या कंपनी से मिली) दिखानी चाहिए.
कारोबारी या कंपनी को नए बदलावों के बारे में सूचना देने के लिए, IPaymentDetailsUpdateServiceCallback
इंटरफ़ेस लागू करें. साथ ही, UPDATE_PAYMENT_DETAILS
इंटेंट फ़िल्टर के साथ IPaymentDetailsUpdateServiceCallback
में इसकी जानकारी दें.AndroidManifest.xml
PAY
इंटेंट को शुरू करने के तुरंत बाद, Chrome उसी पैकेज में मौजूद UPDATE_PAYMENT_DETAILS
सेवा से कनेक्ट हो जाएगा जिसमें PAY
इंटेंट मौजूद है. इसके बाद, Chrome setPaymentDetailsUpdateService(service)
को कॉल करेगा, ताकि आपके पेमेंट ऐप्लिकेशन को IPaymentDetailsUpdateService
एंड-पॉइंट मिल सके. इससे, उपयोगकर्ता के पेमेंट के तरीके, शिपिंग के विकल्प या शिपिंग के पते में हुए बदलावों के बारे में सूचना दी जा सके.
packageManager.getPackagesForUid(Binder.getCallingUid())
का इस्तेमाल तब करें, जब इंटर-प्रोसेस कम्यूनिकेशन (आईपीसी) के ज़रिए डेटा मिल रहा हो. इससे यह पुष्टि की जा सकेगी कि PAY
इंटेंट को शुरू करने वाले ऐप्लिकेशन का पैकेज नाम, IPaymentDetailsUpdateServiceCallback
तरीकों को शुरू करने वाले ऐप्लिकेशन के पैकेज नाम के जैसा ही है.
एआईडीएल
यहां दिए गए कॉन्टेंट के साथ दो AIDL फ़ाइलें बनाएं:
org/chromium/components/payments/IPaymentDetailsUpdateServiceCallback.aidl
package org.chromium.components.payments;
import android.os.Bundle;
import org.chromium.components.payments.IPaymentDetailsUpdateService;
interface IPaymentDetailsUpdateServiceCallback {
oneway void updateWith(in Bundle updatedPaymentDetails);
oneway void paymentDetailsNotUpdated();
oneway void setPaymentDetailsUpdateService(IPaymentDetailsUpdateService service);
}
org/chromium/components/payments/IPaymentDetailsUpdateService.aidl
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);
}
सेवा
IPaymentDetailsUpdateServiceCallback
सेवा लागू करें.
Kotlin
class SampleUpdatePaymentDetailsCallbackService : Service() {
private val binder = object : IPaymentDetailsUpdateServiceCallback.Stub() {
override fun updateWith(updatedPaymentDetails: Bundle) {}
override fun paymentDetailsNotUpdated() {}
override fun setPaymentDetailsUpdateService(service: IPaymentDetailsUpdateService) {}
}
override fun onBind(intent: Intent?): IBinder? {
return binder
}
}
Java
import org.chromium.components.paymsnts.IPaymentDetailsUpdateServiceCallback;
public class SampleUpdatePaymentDetailsCallbackService extends Service {
private final IPaymentDetailsUpdateServiceCallback.Stub mBinder =
new IPaymentDetailsUpdateServiceCallback.Stub() {
@Override
public void updateWith(Bundle updatedPaymentDetails) {}
@Override
public void paymentDetailsNotUpdated() {}
@Override
public void setPaymentDetailsUpdateService(IPaymentDetailsUpdateService service) {}
};
@Override
public IBinder onBind(Intent intent) {
return mBinder;
}
}
AndroidManifest.xml
अपनी AndroidManifest.xml
में, IPaymentDetailsUpdateServiceCallback
के लिए सेवा को चालू करें.
<service
android:name=".SampleUpdatePaymentDetailsCallbackService"
android:exported="true">
<intent-filter>
<action android:name="org.chromium.intent.action.UPDATE_PAYMENT_DETAILS" />
</intent-filter>
</service>
खरीदार के चुने गए पेमेंट के तरीके, शिपिंग पते या शिपिंग के विकल्प में हुए बदलावों के बारे में कारोबारी या कंपनी को सूचना देना
Kotlin
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
}
Java
if (service == null) {
return;
}
try {
if (isOptionChange) {
service.changeShippingOption(selectedOptionId, callback);
} else (isAddressChange) {
service.changeShippingAddress(selectedAddress, callback);
} else {
service.changePaymentMethod(methodData, callback);
}
} catch (RemoteException e) {
// Handle the remote exception
}
changePaymentMethod
यह कुकी, कारोबारी या कंपनी को उपयोगकर्ता के चुने गए पेमेंट के तरीके में हुए बदलावों के बारे में सूचना देती है. paymentHandlerMethodData
बंडल में methodName
और वैकल्पिक details
कुंजियां शामिल होती हैं. इन दोनों में स्ट्रिंग वैल्यू होती हैं. Chrome, ऐसे बंडल की जांच करेगा जिसमें methodName
एट्रिब्यूट की वैल्यू मौजूद हो. अगर पुष्टि नहीं हो पाती है, तो Chrome, callback.updateWith
एट्रिब्यूट का इस्तेमाल करके, updatePaymentDetails
एट्रिब्यूट की वैल्यू के साथ इनमें से कोई एक गड़बड़ी का मैसेज भेजेगा.
'Method data required.'
'Method name required.'
changeShippingOption
यह कुकी, कारोबारी या कंपनी को उपयोगकर्ता के चुने गए शिपिंग के विकल्प में हुए बदलावों के बारे में सूचना देती है.
shippingOptionId
, कारोबारी या कंपनी की ओर से तय किए गए शिपिंग के विकल्पों में से किसी एक का आइडेंटिफ़ायर होना चाहिए. Chrome, shippingOptionId
की जांच करेगा. अगर पुष्टि नहीं हो पाती है, तो वह callback.updateWith
का इस्तेमाल करके, गड़बड़ी के इस मैसेज के साथ updatePaymentDetails
भेजेगा.
'Shipping option identifier required.'
changeShippingAddress
यह कुकी, कारोबारी या कंपनी को खरीदार की ओर से दिए गए शिपिंग पते में हुए बदलावों के बारे में सूचना देती है. Chrome, shippingAddress
बंडल की जांच करेगा. अगर यह बंडल खाली नहीं है और इसमें मान्य countryCode
मौजूद है, तो Chrome callback.updateWith
का इस्तेमाल करके, updatePaymentDetails
भेजेगा. इसमें गड़बड़ी का यह मैसेज होगा:
'Payment app returned invalid shipping address in response.'
स्थिति अमान्य होने की वजह से दिखने वाला गड़बड़ी का मैसेज
अगर Chrome को बदलाव के किसी अनुरोध को स्वीकार करने पर कोई अमान्य स्थिति मिलती है, तो वह callback.updateWith
को updatePaymentDetails
बंडल के साथ कॉल करेगा. बंडल में सिर्फ़ error
कुंजी और "Invalid state"
शामिल होगा.
अमान्य स्थिति के उदाहरण:
- जब Chrome, कारोबारी या कंपनी के पिछले बदलाव (जैसे, बदलाव से जुड़ा कोई मौजूदा इवेंट) के जवाब का इंतज़ार कर रहा हो.
- पेमेंट ऐप्लिकेशन की ओर से दिए गए शिपिंग के विकल्प का आइडेंटिफ़ायर, कारोबारी या कंपनी की ओर से दिए गए शिपिंग के किसी भी विकल्प से मेल नहीं खाता.
कारोबारी या कंपनी से पेमेंट की अपडेट की गई जानकारी पाना
Kotlin
override fun updateWith(updatedPaymentDetails: Bundle) {}
override fun paymentDetailsNotUpdated() {}
Java
@Override
public void updateWith(Bundle updatedPaymentDetails) {}
@Override
public void paymentDetailsNotUpdated() {}
updatedPaymentDetails
, PaymentRequestDetailsUpdate
WebIDL डिक्शनरी के बराबर बंडल है. इसमें ये वैकल्पिक कुंजियां शामिल हैं:
total
- एक बंडल, जिसमेंcurrency
औरvalue
कुंजियां शामिल हैं. दोनों कुंजियों में स्ट्रिंग वैल्यू हैंshippingOptions
- shipping options का पार्सल किया जा सकने वाला ऐरेerror
- एक स्ट्रिंग, जिसमें सामान्य गड़बड़ी का मैसेज होता है. उदाहरण के लिए, जबchangeShippingOption
शिपिंग के विकल्प का मान्य आइडेंटिफ़ायर नहीं देता हैstringifiedPaymentMethodErrors
- यह JSON स्ट्रिंग, पेमेंट के तरीके की पुष्टि करने से जुड़ी गड़बड़ियों के बारे में बताती हैaddressErrors
- यह एक बंडल है. इसमें shipping address और string values के जैसे ही वैकल्पिक बटन होते हैं. हर कुंजी, शिपिंग पते के उस हिस्से से जुड़ी पुष्टि करने की गड़बड़ी को दिखाती है.modifiers
- यह बंडल का पार्सल किया जा सकने वाला कलेक्शन होता है. हर बंडल मेंtotal
औरmethodData
फ़ील्ड होता है. ये फ़ील्ड भी बंडल होते हैं.
अगर कोई कुंजी मौजूद नहीं है, तो इसका मतलब है कि उसकी वैल्यू में कोई बदलाव नहीं हुआ है.