Apple Payプログラミングガイド：ペイメントリクエストの作成

ペイメントリクエストは、PKPaymentRequestクラスのインスタンスです。ペイメントリクエストを構成しているのは、支払いの対象をユーザーに説明するためのサマリーアイテムのリスト、利用できる支払い方法のリスト、ユーザーが提供する必要のある配送先情報の説明、マーチャントと決済代行会社の情報です。

ユーザーが支払いを実行できるかどうかの特定

ペイメントリクエストを作成する前に、PKPaymentAuthorizationViewControllerクラスのcanMakePaymentsUsingNetworks:メソッドを呼び出すことにより、マーチャントのサポートしているネットワークを使ってユーザーが支払いを実行できるかどうかを特定します。デバイスのハードウェアおよびペアレンタルコントロールでApple Payがサポートされているかどうかを確認するには、canMakePaymentsメソッドを使います。

canMakePaymentsでNOfalseが返された場合、デバイスはApple Payをサポートしていません。Apple Payボタンを表示しないでください。代わりに、別の支払い方法へと誘導します。

canMakePaymentsでYEStrueが返されたものの、canMakePaymentsUsingNetworks:でNOfalseが返された場合、デバイスはApple Payをサポートしていますが、要求されたネットワークのいずれについても、ユーザーがカードを登録していません。この場合は、支払い方法の設定ボタンを表示して、ユーザーにカードの設定を促すこともできます。ユーザーがこのボタンをタップすると、（たとえば、openPaymentSetupメソッドを呼び出すことによって）新しいカードの設定プロセスがすぐに開始されます。

その他の場合は、ユーザーがApple Payボタンをタップした後、すぐに支払い承認プロセスを開始する必要があります。ペイメントリクエストを提示する前に、ユーザーにほかのタスクの実行を要求しないでください。たとえば、ユーザーが割引コードを入力しなければならない場合は、コードの入力を要求した後、ユーザーがApple Payボタンを押すという手順にします。

iOS 8.3以降で、ペイメントリクエストを開始するためのApple Payブランドのボタンを作成するには、PKPaymentButtonクラスを使います。Apple Payボタンおよび決済マークの使用に関するその他のガイドラインについては、『iOSヒューマンインターフェイスガイドライン』の「Apple Pay」を参照してください。

ウェブベースのインターフェイスからのブリッジ

Appで、商品やサービスの購入用にウェブベースのインターフェイスを使う場合は、Apple Pay決済を処理する前に、ウェブベースのインターフェイスからiOSのネイティブコードへと要求を移動する必要があります。リスト3-1に、ウェブビューからの要求の処理に必要な手順を示します。

リスト3-1ウェブビューからのアイテムの購入
        // Called when the web view tries to load "myShoppingApp:buyItem" 
-(void)webView:(nonnull WKWebView *)webView 
decidePolicyForNavigationAction:(nonnull WKNavigationAction *)navigationAction 
decisionHandler:(nonnull void (^)(WKNavigationActionPolicy))decisionHandler { 
 
// Get the URL for the selected link. 
NSURL *URL = navigationAction.request.URL; 
 
// If the scheme and resource specifier match those defined by your app, 
// handle the payment in native iOS code. 
if ([URL.scheme isEqualToString:@"myShoppingApp"] && 
[URL.resourceSpecifier isEqualToString:@"buyItem"]) { 
 
// Create and present the payment request here. 
 
// The web view ignores the link. 
decisionHandler(WKNavigationActionPolicyCancel); 
} 
 
// Otherwise the web view loads the link. 
decisionHandler(WKNavigationActionPolicyAllow); 
} 

      

ペイメントリクエストには通貨と地域の情報が含まれる

ペイメントリクエストに含まれているすべての集計額に、PKPaymentRequestのcurrencyCodeプロパティを使って指定されるものと同じ通貨が使われます。USDなど、3文字のISO通貨コードを使ってください。

ペイメントリクエストの国コードは、購入が発生した国または購入が処理される国を示します。USなど、2文字のISO国コードを使ってください。

ペイメントリクエストに設定するマーチャントIDは、Appのエンタイトルメントに含まれている、いずれかのマーチャントIDと一致している必要があります。

        request.currencyCode = @"USD"; 
request.countryCode = @"US"; 
request.merchantIdentifier = @"merchant.com.example"; 

      

ペイメントリクエストには支払いサマリーアイテムのリストが保持される

PKPaymentSummaryItemクラスで表される支払いサマリーアイテムは、ペイメントリクエストに含まれているさまざまな要素をユーザーに説明するためのものです。サマリーアイテムの数は少数にとどめてください。通常は、小計、割引額、配送料、税額、および合計金額です。付加的な支払い額（たとえば、配送料や税）が発生しない場合は、購入の合計額のみを使います。アイテムごとの価格の明細は、Appのその他の場所で提示してください。

サマリーアイテムは、リスト3-2に示すとおり、それぞれラベルと金額を保持しています。ラベルは、サマリーが示されているアイテムに関して、ユーザーが読むことのできる説明です。金額は、対応する支払い額です。ペイメントリクエストの金額に使われる単位は、いずれも、ペイメントリクエストで指定されている通貨です。割引またはクーポンについては、金額を負の数に設定します。

タクシー運賃など、支払いを承認する時点では実際のコストが不明な場合は、PKPaymentSummaryItemTypePendingタイプと金額0.0を使って、小計サマリーアイテムを作成します。このコストは、保留中としてマークされます。

リスト3-2支払いサマリーアイテムの作成
        // 12.75 subtotal 
NSDecimalNumber *subtotalAmount = [NSDecimalNumber decimalNumberWithMantissa:1275 exponent:-2 isNegative:NO]; 
self.subtotal = [PKPaymentSummaryItem summaryItemWithLabel:@"Subtotal" amount:subtotalAmount]; 
 
// 2.00 discount 
NSDecimalNumber *discountAmount = [NSDecimalNumber decimalNumberWithMantissa:200 exponent:-2 isNegative:YES]; 
self.discount = [PKPaymentSummaryItem summaryItemWithLabel:@"Discount" amount:discountAmount]; 

      

注意

支払いサマリーアイテムは、NSDecimalNumberクラスを使って、金額を10進法の数量として保存します。このクラスのインスタンスは、（コードリストに示しているとおり）仮数部と指数部を明示的に指定することで、または、数量を文字列として提供し、ロケールを指定することで作成できます。5%割引の金額を求める場合など、会計計算では常に10進数を使ってください。

floatやDoubleなどのIEEE浮動小数点データ型は、利便性が高いように見える場合もありますが、金額計算には適していません。これらのデータ型は、数値の2進法表現を使っています。つまり、一部の10進数を正確に表現できません。たとえば、0.42は0.41999...として近似値で表現しなければなりません。このような近似値化によって、金額計算で返される結果が不正確なものになる可能性があります。

リスト末尾の支払いサマリーアイテムは、合計金額です。合計金額を計算するには、ほかのすべてのサマリーアイテムの金額を合算します。合計金額は、ほかのサマリーアイテムとは異なる形式で表示されます。社名がラベルとして使われ、ほかのすべてのサマリーアイテムの合算額が合計金額として使われます。支払いサマリーアイテムをペイメントリクエストに追加するには、paymentSummaryItemsプロパティを使います。

        // 10.75 grand total 
NSDecimalNumber *totalAmount = [NSDecimalNumber zero]; 
totalAmount = [totalAmount decimalNumberByAdding:subtotalAmount]; 
totalAmount = [totalAmount decimalNumberByAdding:discountAmount]; 
self.total = [PKPaymentSummaryItem summaryItemWithLabel:@"My Company Name" amount:totalAmount]; 
 
self.summaryItems = @[self.subtotal, self.discount, self.total]; 
request.paymentSummaryItems = self.summaryItems; 

      

支払い方法は特殊な支払いサマリーアイテムである

利用できる支払い方法ごとに、PKShippingMethodのインスタンスを作成します。ほかの支払いサマリーアイテムと同様に、支払い方法も、ユーザーが読むことのできるラベル（「標準出荷」や「翌日出荷」など）と金額（配送料）を保持しています。ほかのサマリーアイテムと異なるのは、「7月29日までに到着」や「24時間以内に出荷」など、複数の支払い方法の違いを説明するdetailプロパティが用意されている点です。

デリゲートメソッド内で支払い方法を区別するには、identifierプロパティを使います。このプロパティはAppのみが使うもので、フレームワークではオペーク値として扱われ、UIに表示されません。支払い方法を作成する際は、支払い方法ごとに一意の識別子を割り当てます。デバッグしやすさを考慮して、「discount」、「standard」、「next-day」など、短い文字列や短縮文字列を使ってください。

支払い方法によっては、あらゆる地域で利用できるものではない場合や、住所によってコストが異なる場合があります。この情報は、「デリゲートで支払い方法とコストを更新する」で説明するとおり、ユーザーが配送先住所または配送方法を選択するときに更新できます。

サポートしている支払い処理メカニズムの指定

自社がサポートしている決済ネットワークを指定するには、supportedNetworksプロパティに文字列定数の配列で値を入力します。自社がサポートしている支払い処理プロトコルを指定するには、merchantCapabilitiesプロパティの値を設定します。3DSのサポートは必須です。中国国内でApple Payをサポートする場合のみ、EMVを指定します。

マーチャントケーパビリティはビットマスクであり、以下のように組み合わされます。

        request.supportedNetworks = @[PKPaymentNetworkAmex, PKPaymentNetworkDiscover, PKPaymentNetworkMasterCard, PKPaymentNetworkVisa]; 
 
// Supports 3DS only 
request.merchantCapabilities = PKMerchantCapability3DS; 
 
// Supports both 3DS and EMV (add EMV only if you support Apple Pay in China mainland) 
request.merchantCapabilities = PKMerchantCapability3DS | PKMerchantCapabilityEMV;

どの配送先情報と請求情報が必要であるかの指定

ペイメントオーソライゼーションビューコントローラのrequiredBillingAddressFieldsプロパティとrequiredShippingAddressFieldsプロパティに値を入力して、どの配送先情報と請求情報が必要であるかを指定します。このビューコントローラを提示すると、ユーザーに対して、要求された請求情報と配送先情報を入力するよう求めるプロンプトが表示されます。これらのプロパティの値は、フィールド定数を以下のように組み合わせることで設定されます。

        request.requiredBillingAddressFields = PKAddressFieldEmail; 
request.requiredBillingAddressFields = PKAddressFieldEmail | PKAddressFieldPostalAddress;

最新の請求情報と配送先情報を保持している場合は、支払い方法に対してそれらを設定できます。Apple Payでは、デフォルトでこの情報が使われます。ただし、支払い承認プロセスの一環として、ユーザーがほかの連絡先情報を選択することは可能です。

        PKContact *contact = [[PKContact alloc] init]; 
 
NSPersonNameComponents *name = [[NSPersonNameComponents alloc] init]; 
name.givenName = @"John"; 
name.familyName = @"Appleseed"; 
 
contact.name = name; 
 
CNMutablePostalAddress *address = [[CNMutablePostalAddress alloc] init]; 
address.street = @"1234 Laurel Street"; 
address.city = @"Atlanta"; 
address.state = @"GA"; 
address.postalCode = @"30303"; 
 
contact.postalAddress = address; 
 
request.shippingContact = contact; 

      

追加情報の保存

ショッピングカートの識別子など、ペイメントリクエストに関してApp固有の情報を保存するには、applicationDataプロパティを使います。このプロパティは、システムではオペーク値として扱われます。ユーザーがペイメントリクエストを承認すると、Appデータのハッシュがペイメントトークンに表示されます。