Android 결제 앱의 배송 및 연락처 정보 제공

Android 결제 앱을 업데이트하여 웹 결제 API에 배송지 주소와 결제자의 연락처 정보를 제공하는 방법

Sahel Sharify
Sahel Sharify

웹 양식을 통해 배송지 주소와 연락처 정보를 입력하는 것은 고객에게 번거로운 경험일 수 있습니다. 오류가 발생하고 전환율이 낮아질 수 있습니다.

그렇기 때문에 Payment Request 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 사전을 사용하여 추가 필수 정보를 지정할 수 있습니다. 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 - 문자열 값이 있는 currencyvalue 키가 포함된 배송비 번들입니다.
    • 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 번들에는 문자열 값이 있는 methodNamedetails 키(선택사항)가 포함되어 있습니다. 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()
        }
    }

updatePaymentDetailsmodifiers 필드를 수정한 후 PaymentRequestDetailsUpdate WebIDL 사전과 동일한 번들이며 다음과 같은 선택적 키를 포함합니다.

  • total - currencyvalue 키가 포함된 번들로, 두 키 모두 문자열 값을 갖습니다.
  • shippingOptions - 배송 옵션의 parcelable 배열
  • error - 일반 오류 메시지가 포함된 문자열입니다(예: changeShippingOption가 유효한 배송 옵션 식별자를 제공하지 않는 경우).
  • stringifiedPaymentMethodErrors - 결제 수단의 유효성 검사 오류를 나타내는 JSON 문자열
  • addressErrors - 배송지 주소 및 문자열 값과 동일한 선택적 키가 포함된 번들입니다. 각 키는 배송지 주소의 해당 부분과 관련된 유효성 검사 오류를 나타냅니다.

키가 없으면 값이 변경되지 않은 것입니다.