Android 결제 앱을 업데이트하여 웹 결제 API에 배송지 주소와 결제자의 연락처 정보를 제공하는 방법
고객이 웹 양식을 통해 배송지 주소와 연락처 정보를 입력하는 것은 번거로운 일일 수 있습니다. 오류가 발생하고 전환율이 낮아질 수 있습니다.
그렇기 때문에 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
활동에 대한 응답에 필요한 추가 정보를 포함해야 합니다.
이렇게 하려면 다음 매개변수를 인텐트 추가 항목으로 지정해야 합니다.
payerName
- 결제자의 성명입니다.paymentOptions.requestPayerName
이 true인 경우 비어 있지 않은 문자열이어야 합니다.payerPhone
- 결제자의 전화번호입니다.paymentOptions.requestPayerPhone
가 true인 경우 비어 있지 않은 문자열이어야 합니다.payerEmail
- 결제자의 이메일 주소입니다.paymentOptions.requestPayerEmail
가 true인 경우 비어 있지 않은 문자열이어야 합니다.shippingAddress
- 사용자가 제공한 배송지 주소입니다.paymentOptions.requestShipping
가 true인 경우 비어 있지 않은 번들여야 합니다. 번들에는 물리적 주소의 여러 부분을 나타내는 다음 키가 있어야 합니다.city
countryCode
dependentLocality
organization
phone
postalCode
recipient
region
sortingCode
addressLine
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", "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
- 배송지 주소 및 문자열 값과 동일한 선택적 키가 포함된 번들입니다. 각 키는 배송지 주소의 해당 부분과 관련된 유효성 검사 오류를 나타냅니다.
키가 없으면 값이 변경되지 않은 것입니다.