Article

Sending an Apple Pay Payment Request

Request a payment from the customer by sending an Apple Pay payment request.

Overview

A payment request starts when a customer service agent with the business asks you to send a payment request to a customer. You should create a data dictionary to collect and store information about the payment request.

The first piece of information to collect is a payment session object. To get it, ask Apple Pay to start a new payment session (see Requesting an Apple Pay Payment Session). Apple Pay returns a payment session object which you add to the ApplePayMerchantSession dictionary in the data dictionary.

Next, add the ApplePayPaymentRequest dictionary keys to the data dictionary. This is where you specify transaction details such as the purchase amount, payment processing capabilities, available shipping methods, and a list of items or services purchased. You can also request billing and shipping address information through the ApplePayPaymentRequest dictionary.

Finally, add the ApplePayEndpoints dictionary keys to the data dictionary. This dictionary identifies the endpoints needed to process the payment and receive any updates a customer might make before confirming the payment, such as updating the shipping address or changing the shipping method.

After constructing the data dictionary, send it to Business Chat as part of an interactive message (see Sending a Custom Interactive Message). Business Chat forwards the payment request to the customer's device, and the customer authorizes the payment from the Apple Pay payment sheet using Touch ID or Face ID. The device then sends the payment information, including the encrypted Apple Pay token and any requested customer contact information, to the paymentGatewayURL endpoint listed in the endpoints dictionary. After processing the payment, the merchant sends the transaction results to the customer's device, which in turn sends the results to you to let you know the payment request is complete.

Sample Apple Pay Payment Request

{
    "type": "interactive",
    "interactiveData": {
      "bid": "com.apple.messages.MSMessageExtensionBalloonPlugin:0000000000:com.apple.icloud.apps.messages.business.extension",
      "data": {
        "images": [
          {
            "data": "base64encoded-image-file",
            "identifier": "1"
          }
        ],
        "version": "1.0",
        "payment": {
          "endpoints": {
            "fallbackUrl": "https://sams.example.com/fallback/",
            "orderTrackingUrl": "https://sams.example.com/orderTrackingUrl/",
            "paymentGatewayUrl": "https://sams.example.com/paymentGateway/",
            "paymentMethodUpdateUrl": "https://sams.example.com/paymentMethodUpdate/",
            "shippingContactUpdateUrl": "https://sams.example.com/shippingContactUpdate/",
            "shippingMethodUpdateUrl": "https://sams.example.com/shippingMethodUpdate/"
          },
          "merchantSession": {
            "epochTimestamp": 1525722894057,
            "expiresAt": 1525730094057,
            "merchantSessionIdentifier": "PSH40080EF4D655442D...FD",
            "nonce": "fe72cd0f",
            "merchantIdentifier": "302B976...8E",
            "displayName": "Sam's Fish",
            "signature": "308006092a864886f...00",
            "initiative": "messaging",
            "initiativeContext": "https://sams.example.com/paymentGateway",
            "signedFields": [
              "merchantIdentifier",
              "merchantSessionIdentifier",
              "initiative",
              "initiativeContext",
              "displayName",
              "nonce"
            ]
          }, 
          "paymentRequest": {
            "applePay": {
              "merchantCapabilities": [
                "supports3DS",
                "supportsDebit",
                "supportsCredit"
              ],
              "merchantIdentifier": "merchant.com.sams.fish",
              "supportedNetworks": [
                "amex",
                "visa",
                "discover",
                "masterCard"
              ]
            },
            "countryCode": "US",
            "currencyCode": "USD",
            "lineItems": [
              {
                "amount": "59.00",
                "label": "Halibut",
                "type": "final"
              },
              {
                "amount": "4.99",
                "label": "Shipping",
                "type": "final"
              }
            ],
            "requiredBillingContactFields": [
              "post"
            ],
            "requiredShippingContactFields": [
              "post",
              "phone",
              "email",
              "name"
            ],
            "shippingMethods": [
              {
                "amount": "0.00",
                "detail": "Available within an hour",
                "identifier": "in_store_pickup",
                "label": "In-Store Pickup"
              },
              {
                "amount": "4.99",
                "detail": "5-8 Business Days",
                "identifier": "flat_rate_shipping_id_2",
                "label": "UPS Ground"
              },
              {
                "amount": "29.99",
                "detail": "1-3 Business Days",
                "identifier": "flat_rate_shipping_id_1",
                "label": "FedEx Priority Mail"
              }
            ],
            "total": {
              "amount": "63.99",
              "label": "Sam's Fish",
              "type": "final"
            }
          }
        },
        "requestIdentifier": "8EF748B5-3DC5-47AE-B185-65E91518D209"
      },
      "receivedMessage": {
        "imageIdentifier": "1",
        "style": "large",
        "subtitle": "$63.99 at Sam's Fish",
        "title": "Halibut"
      }
  }

Topics

Dictionaries

object ApplePayData

Dictionary keys for making an Apple Pay payment request.

object ApplePayContactFieldItem

Field names used for requesting contact information in a payment request.

object ApplePayEndpoints

URLs for the endpoints dictionary.

object ApplePayItem

Keys for Apple Pay dictionary.

object ApplePayLineItem

A set of line items that explain recurring payments and additional charges and discounts.

object ApplePayPaymentRequest

Keys for the paymentRequest dictionary.

object ApplePayShippingMethodItem

The itemized shipping method for delivering physical goods.

See Also

Apple Pay Essentials

Accepting Apple Pay Payments

Accept payments from customers who use Apple Pay.

Processing Payment Requests

Process payment requests using the payment gateway endpoint.