日本語ドキュメント

Developer

Apple Payプログラミングガイド

このページの内容

ペイメントリクエストの作成

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  1. PKContact *contact = [[PKContact alloc] init];
  2. NSPersonNameComponents *name = [[NSPersonNameComponents alloc] init];
  3. name.givenName = @"John";
  4. name.familyName = @"Appleseed";
  5. contact.name = name;
  6. CNMutablePostalAddress *address = [[CNMutablePostalAddress alloc] init];
  7. address.street = @"1234 Laurel Street";
  8. address.city = @"Atlanta";
  9. address.state = @"GA";
  10. address.postalCode = @"30303";
  11. contact.postalAddress = address;
  12. request.shippingContact = contact;

追加情報の保存

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