Web Payments API로 배송지 주소와 결제자의 연락처 정보를 제공하도록 Android 결제 앱을 업데이트하는 방법
고객이 웹 양식을 통해 배송지 주소와 연락처 정보를 입력하는 것은 번거로운 경험이 될 수 있습니다. 오류가 발생하고 전환율이 낮아질 수 있습니다.
따라서 Payment Request API가 배송지 주소와 연락처 정보를 요청하는 기능을 지원합니다. 이렇게 하면 여러 가지 이점이 있습니다.
- 사용자는 탭 몇 번으로 올바른 주소를 선택할 수 있습니다.
- 주소는 항상 표준화된 형식으로 반환됩니다.
- 잘못된 주소를 제출할 가능성이 낮습니다.
브라우저는 배송지 주소 및 연락처 정보 수집을 결제 앱으로 연기하여 통합된 결제 환경을 제공할 수 있습니다. 이 기능을 위임이라고 합니다.
가능한 경우 Chrome은 고객의 배송지 주소 및 연락처 정보 수집을 호출된 Android 결제 앱에 위임합니다. 위임을 통해 결제 과정의 불편함이 줄어듭니다.
판매자 웹사이트는 고객이 선택한 배송지 주소와 배송 옵션에 따라 배송 옵션 및 총 가격을 동적으로 업데이트할 수 있습니다.
기존 Android 결제 앱에 위임 지원을 추가하려면 다음 단계를 구현합니다.
지원되는 위임 선언
브라우저는 결제 앱이 제공할 수 있는 추가 정보 목록을 알아야 해당 정보 수집을 앱에 위임할 수 있습니다. 앱의 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 사전을 사용하여 추가 필수 정보를 지정할 수 있습니다. 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"일 수 있습니다. 앱은 사용자의 주소 또는 배송 옵션 선택을 요청할 때 UI에서 이 힌트를 사용할 수 있습니다.
shippingOptions
shippingOptions는 판매자가 지정한 배송 옵션의 parcelable 배열입니다. 이 매개변수는 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 활동에 관한 응답에 필요한 추가 정보를 포함해야 합니다.
이렇게 하려면 다음 매개변수를 인텐트 extras로 지정해야 합니다.
payerName- 결제자의 전체 이름입니다.paymentOptions.requestPayerName가 true인 경우 비어 있지 않은 문자열이어야 합니다.payerPhone- 결제자의 전화번호입니다.paymentOptions.requestPayerPhone가 true인 경우 비어 있지 않은 문자열이어야 합니다.payerEmail- 결제자의 이메일 주소입니다.paymentOptions.requestPayerEmail가 true인 경우 비어 있지 않은 문자열이어야 합니다.shippingAddress- 사용자가 제공한 배송지 주소입니다.paymentOptions.requestShipping이 true인 경우 비어 있지 않은 번들이어야 합니다. 번들에는 실제 주소의 서로 다른 부분을 나타내는 다음 키가 있어야 합니다.citycountryCodedependentLocalityorganizationphonepostalCoderecipientregionsortingCodeaddressLineaddressLine를 제외한 모든 키는 문자열 값을 갖습니다.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", "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")
}
}
선택사항: 동적 흐름 지원
사용자가 특급 배송 옵션을 선택하거나 사용 가능한 배송 옵션 목록 또는 가격이 변경되는 경우와 같이 총 거래 비용이 증가하는 경우가 있습니다. 앱에서 사용자가 선택한 배송지 주소 또는 옵션을 제공하면 판매자에게 배송지 주소나 옵션 변경을 알리고 판매자가 제공한 업데이트된 결제 세부정보를 사용자에게 표시할 수 있어야 합니다.
AIDL
판매자에게 새로운 변경사항을 알리려면 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는 결제 요청을 시작한 브라우저에 따라 다음 값 중 하나를 가질 수 있습니다.
| 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가 있는 비어 있지 않은 번들을 확인하고 유효성 검사에 실패하면 callback.updateWith를 통해 다음 오류 메시지 중 하나가 포함된 updatePaymentDetails를 전송합니다.
'Method data required.'
'Method name required.'
changeShippingOption
사용자가 선택한 배송 옵션의 변경사항을 판매자에게 알립니다.
shippingOptionId는 판매자가 지정한 배송 옵션 중 하나의 식별자여야 합니다. Chrome은 비어 있지 않은 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- 배송 옵션의 parcelable 배열입니다.error- 일반 오류 메시지가 포함된 문자열입니다 (예:changeShippingOption가 유효한 배송 옵션 식별자를 제공하지 않는 경우).stringifiedPaymentMethodErrors- 결제 수단의 유효성 검사 오류를 나타내는 JSON 문자열addressErrors- 배송지 주소 및 문자열 값과 동일한 선택적 키가 포함된 번들입니다. 각 키는 배송지 주소의 해당 부분과 관련된 유효성 검사 오류를 나타냅니다.
없는 키는 값이 변경되지 않았음을 의미합니다.