Предоставьте информацию о доставке и контактную информацию из платежного приложения Android

Как обновить платежное приложение Android, чтобы оно предоставляло адрес доставки и контактную информацию плательщика с помощью API веб-платежей.

Sahel Sharify

Опубликовано: 17 июля 2020 г., Последнее обновление: 27 мая 2025 г.

Ввод адреса доставки и контактной информации через веб-форму может быть затруднительным для клиентов. Это может привести к ошибкам и снижению конверсии.

Именно поэтому 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/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 предоставит список необходимых параметров, которые может предоставить ваше приложение, передав дополнительные параметры намерения 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")

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 .

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

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 — следует ли выбирать вариант доставки, когда платежное приложение отображает варианты доставки.

Все ключи, кроме 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)

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 имеет значение true.
• payerPhone — номер телефона плательщика. Должен быть непустой строкой, если paymentOptions.requestPayerPhone имеет значение true.
• payerEmail — адрес электронной почты плательщика. Должен быть непустой строкой, если paymentOptions.requestPayerEmail имеет значение true.
• shippingAddress — адрес доставки, предоставленный пользователем. Это должен быть непустой пакет, если paymentOptions.requestShipping имеет значение true. Пакет должен иметь следующие ключи, представляющие различные части физического адреса .
  • countryCode
  • postalCode
  • sortingCode
  • region
  • city
  • dependentLocality
  • addressLine
  • organization
  • recipient
  • Все phone , кроме addressLine , имеют строковые значения. addressLine — это массив строк.
• shippingOptionId — идентификатор выбранного пользователем варианта доставки. Должен быть непустой строкой, если paymentOptions.requestShipping имеет значение true.

Подтвердить ответ на платеж

Если результат действия платежного ответа, полученного от вызванного платёжного приложения, установлен на 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", "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")
    }
}

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 и объявите его в AndroidManifest.xml с фильтром намерений UPDATE_PAYMENT_DETAILS .

Сразу после вызова намерения PAY Chrome подключится к службе UPDATE_PAYMENT_DETAILS (если она существует) в том же пакете, что и намерение PAY , и вызовет setPaymentDetailsUpdateService(service) , чтобы предоставить вашему платежному приложению конечную точку IPaymentDetailsUpdateService для уведомления об изменениях в способе оплаты пользователя, варианте доставки или адресе доставки.

Используйте packageManager.getPackagesForUid(Binder.getCallingUid()) при получении межпроцессного взаимодействия (IPC), чтобы проверить, что приложение, вызвавшее намерение PAY , имеет то же имя пакета, что и приложение, вызвавшее методы IPaymentDetailsUpdateServiceCallback .

AIDL

Создайте два файла 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 .

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
    }
}

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

Предоставьте доступ к службе IPaymentDetailsUpdateServiceCallback в вашем AndroidManifest.xml .

<service
    android:name=".SampleUpdatePaymentDetailsCallbackService"
    android:exported="true">
    <intent-filter>
        <action android:name="org.chromium.intent.action.UPDATE_PAYMENT_DETAILS" />
    </intent-filter>
</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
}

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 и отправит 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 . Пакет будет содержать только ключ error с пометкой "Invalid state" . Примеры недопустимого состояния:

• Когда Chrome все еще ожидает ответа продавца на предыдущее изменение (например, текущее событие изменения).
• Идентификатор способа доставки, предоставленный платежным приложением, не принадлежит ни одному из способов доставки, указанных продавцом.

Получите обновленные платежные реквизиты от продавца

override fun updateWith(updatedPaymentDetails: Bundle) {}

override fun paymentDetailsNotUpdated() {}

@Override
public void updateWith(Bundle updatedPaymentDetails) {}

@Override
public void paymentDetailsNotUpdated() {}

updatedPaymentDetails — это пакет, эквивалентный словарю PaymentRequestDetailsUpdate WebIDL , и содержит следующие необязательные ключи:

• total - пакет, содержащий ключи currency и value , оба ключа имеют строковые значения
• shippingOptions — широкий выбор вариантов доставки
• error — строка, содержащая общее сообщение об ошибке (например, когда changeShippingOption не предоставляет допустимый идентификатор варианта доставки)
• stringifiedPaymentMethodErrors — строка JSON, представляющая ошибки проверки способа оплаты.
• addressErrors — набор с необязательными ключами, идентичными адресу доставки и строковым значениям. Каждый ключ представляет собой ошибку проверки, связанную с соответствующей частью адреса доставки.
• modifiers — пакетируемый массив пакетов, каждый из которых имеет поле total и поле methodData , которые также являются пакетами.

Отсутствие ключа означает, что его значение не изменилось.