Overview
The Apple Messages for Business messaging channel now supports a new Rich Message type that allows you to submit payment requests to consumers using Apple Pay. The consumers can then respond to the payment request using their preferred Apple Pay payment methods.
See the general message flow below:
-
Send the Apple Pay template via an agent or bot with the Structured Content framework and configuration (similar to list and time picker).
-
Payment transactions will be performed by your payment gateway.
-
Upon successful or failed payment, Conversational Cloud will support passing the payment details back to Conversational Cloud Conversational Metadata (via the Agent SDK) in order to allow you to perform validation on the payment information against the Apple Pay account
Setup
-
The first step is to configure your Apple developer account for Apple Pay.
-
Register a Merchant Identifier (Merchant ID) in your Apple Developer Account to enable Apple Pay payments in Messages. For more information on creating your merchant ID, see Configuring Your Environment.
-
Then, create a private Apple Pay account and supply your Apple Pay Merchant ID in your Apple management area register.apple.com.
You will use your Merchant ID in the merchantIdentifier properties of the Apple Pay Request metadata template below so save it somewhere you can easily access.
Sending an Apple Pay Request to a Consumer
You will send a metadata template and a body template for the Apple Pay request to the consumer.
See how to send Structured Content for more information on how to send these.
The body template will only define how the Apple Pay bubble is displayed in the Conversational Cloud agent workspace. The metadata template will define how the bubble is displayed in the consumer's Messages thread.
Agent/bot generates Apple Pay Interactive Message to consumer (using structured content on Conversational Cloud)
In the interim, consumer completes payment process and receives the reply message bubble with the payment status. Agent views Apple Pay Request in Conversational Cloud Agent Workspace
Request Metadata
BusinessChatMessage — receivedMessage bubbles
The BusinessChatMessage object holds the received message, which defines how the bubble element will be displayed when a message is received on the consumer’s device. The Apple Pay reply message on the consumer device is not configurable.
ConnectorPaymentRequest
The payment request holds the full Apple Pay transaction details (details of purchased services, payment capabilities, shipping methods, and transaction amounts). You can also request billing and shipping methods in this request.
To edit the ConnectorPaymentRequest and BusinessChatMessage metadata template, please use the relevant properties, as presented in the example JSON below.
Request Metadata example
[
{
"type": "BusinessChatMessage",
"receivedMessage": {
"style": "icon",
"subtitle": "Buy now for $1",
"title": "iPhone XS Max",
"imageURL":"https://i.pinimg.com/280x280_RS/96/7f/ab/967fab3e38860638878f86b26bd756e3.jpg"
}
},
{
"type": "ConnectorPaymentRequest",
"signature": "<SIGNATURE VALUE>",
"apple": {
"data": {
"version": "1.0",
"payment": {
"paymentRequest": {
"applePay": {
"merchantIdentifier": "<MERCHANTIDENTIFIER>",
"merchantCapabilities": [
"supports3DS",
"supportsCredit",
"supportsDebit"
],
"supportedNetworks": [
"amex",
"visa",
"mastercard"
]
},
"lineItems": [
{
"label": "iPhone",
"amount": "1",
"type": "pending"
}
],
"total": {
"label": "iPhone",
"amount": "1",
"type": "pending"
},
"countryCode": "US",
"currencyCode": "USD",
"supportedCountries": [
"US"
],
"shippingMethods": [
{
"label": "Free Shipping",
"detail": "Arrives in 5 to 7 days",
"amount": "0.00",
"identifier": "FreeShip"
},
{
"label": "Paid Shipping",
"detail": "Arrives in 2 to 3 days",
"amount": "9.00",
"identifier": "Paid"
}
]
},
"endpoints": {
"paymentGatewayUrl": "https://<DOMAIN>/paymentGateway",
"fallbackUrl": "https://<DOMAIN>/paymentGateway"
},
"merchantSession": {
"epochTimestamp": 1538086871973,
"expiresAt": 1538094071973,
"merchantSessionIdentifier": "MERCHANTSESSIONIDENTIFIER ENCODED",
"nonce": "ee020db9",
"merchantIdentifier": "MERCHANTIDENTIFIER ENCODED",
"displayName": "Vikram Bhatt /Jayshree Bhatt",
"signature": "SESSIONSTRING",
"initiative": "messaging",
"initiativeContext": "https://<DOMAIN>/paymentGateway",
"signedProperties": [
"merchantIdentifier",
"merchantSessionIdentifier",
"initiative",
"initiativeContext",
"displayName",
"nonce"
]
}
},
"requestIdentifier": "<UUID>"
}
}
}
]
Request Metadata Properties
| Property Name | Description | Type | Required |
|---|---|---|---|
| BusinessChatMessage | Represents the Business Chat bubbles view objects | Object | Y |
| ConnectorPaymentRequest | Represents a Business Chat apple pay request | Object | Y |
BusinessChatMessage Object Properties
receivedMessage Object Properties
This object defines how the Apple Pay template is displayed on the consumer device and not how it is displayed in the Agent Workspace.
| Property Name | Description | Type | Required |
|---|---|---|---|
| Style | The Style of the apple pay Rich Message reply bubble. Can be set to icon, small or large. Defaults to icon | Enum — icon, small, large | N |
| title | The title of the bubble | String | Y |
| subtitle | Subtitle to be displayed under title | String | N |
| imageURL | Image to be placed in the apple pay Rich Message received bubble template | String | N |
ConnectorPaymentRequest Object Properties
| Property Name | Description | Type | Required |
|---|---|---|---|
| apple | This is where you specify the "data" object | object | Y |
| signature | This is where you specify the "signature" value. For more information, see Apple Pay Signature Flow Guide | string | N |
apple Object Properties
| Property Name | Description | Type | Required |
|---|---|---|---|
| Data | This is where you specify the "requestIdentifier", "payment" and the "version". | object | Y |
data Object Properties
| Property Name | Description | Type | Required |
|---|---|---|---|
| requestIdentifier | A UUID for the request. Business Chat includes the identifier in its response to Conversational Cloud — this is an important property which allows you to correlate the payment response with your backend payment service | string | Y |
| payment | A dictionary with information about the payment request. For the full details list of the payment dictionary keys, see Apple’s Payment Request Dictionary. | object | Y |
| version | The version number of the message extension schema; the version should be 1.0. | string | Y |
payment Object Properties
| Property Name | Description | Type | Required |
|---|---|---|---|
| paymentRequest | This is where you specify the — apple pay identifiers, line items, total amount, country code, currency code, supported countries, shipping methods | object | Y |
| merchantSession | Containing the payment session provided by Apple Pay after requesting a new payment session. For more information, see Requesting an Apple Pay Payment Session. | object | Y |
| endpoints | The endpoints dictionary contains a list of URLs that Apple Pay calls during the payment process. Apple Pay requires the paymentGatewayUrl endpoint for use in asking the payment provider to process the payment; all other endpoints are optional. | object | Y |
Request Body
The request body is standard structured content. The template is sent to Conversational Cloud and defines how the Apple Pay bubble looks in the Conversational Cloud Agent Workspace and not how the bubble looks on the consumer device (which is determined by the objects described above). This request body template is useful for conversational context, transcript and historical records, as well as ease of use for agents.
See the introduction to templates for information on a basic template that you can send.
Example
A very simple, basic structured content template for Apple Pay would be an image and text in a horizontal arrangement.
{
"type": "horizontal",
"elements": [
{
"type": "image",
"url": "apple_pay_image_url"
},
{
"type": "text",
"text": "Your Order"
}
]
}
Apple Pay Signature Flow
The Apple Pay Signature Flow is an extra layer of validation for Apple Pay transactions. In the Request Metadata payload, there is a "signature" property that you can include. This signature is set on the account level. The Apple Messages for Business connector takes the signature value that you sent and validates that with the signature attached to your account. If the validation fails, agents will see a red warning icon in the conversation window next to the message.
The signature flow is optional, and provides an extra layer of security before sending the payment request to Apple.
If you would like to opt in for this additional verification, internal account configurations are required. Please contact your LivePerson representative (other contact options: chat with us on this page, or message Support) for help and further information on setting up this additional flow.
How to generate the signed payload to include in the Apple Pay payload for verification:
- Generate signature value
- Generate the Apple Pay payload
- Generate SHA1 Hash of the payload from step 1
- Generate the signature, sign the generated hash from step 2 using the secret key and preferred algorithm required during onboarding to opt in to the verification flow
- Add signature to payload
- Add “signature” property and the value generated from step 1C to the original payload
Receiving an Apple Pay Response from a Consumer
After the consumer submits their Apple Pay details in the form, the Apple Pay response is delivered back to Conversational Cloud.
If you are looking to receive the payment response using a bot, you can listen for the payment response via Conversational Metadata. Conversational Metadata provides a way for developers to pass metadata or context information to a bot built with the Messaging Agent SDK. Please see the Conversational Metadata guide for how to listen for Conversational Metadata with the correct Apple Pay response structure.
If you are looking to receive and share the payment response with a human agent, you can listen for the auth response in an Agent Widget. See the bind method for how to listen for incoming data. Instead of visitorInfo.visitorName in the example, the pathToData that you will bind to is metadata.connectorPaymentResponse.
Response Metadata
Apple Pay response metadata is contextual information about the consumer payment status and details. You will receive the payment response inside the requestIdentifier parameter that was sent with the initial request. This requestIdentifier parameter should then be used to allow the bot to validate the payment against your payment backend.
Successful payment response example
{
"type":"ConnectorPaymentResponse",
"status":true,
"requestIdentifier":"b0bbb054-6f71-4de1-831a-9f93ddc93968"
}
Failed payment response example
{
"type":"ConnectorPaymentResponse",
"status":false,
"requestIdentifier":"16238516-02a2-4b19-bd0b-d98c144f3b3f"
}
ConnectorPaymentResponse Object Properties
| Property Name | Description | Type |
|---|---|---|
| Status | Status of the payment response | Boolean |
| requestIdentifier | UUID of the payment response. This information should be used to allow the bot to validate the payment against your payment backend. | String |
Guidelines
General guidelines
-
Upon payment response from consumer - it is very important that you perform validation on the payment response against your payment backend using the request identifier.
-
Each Apple Pay merchant session will be available for only 5 minutes (based on Apple standards) - if the consumer will not reply to the payment request within that time frame the session will end, and you will need to perform another payment request to allow the consumer to pay.
Consumer received and reply bubble behavior
If using received bubble with style "icon":
-
Received bubble experience - the image in the received bubble will only be presented in the push preview message. Once you tap to view the bubble in the conversation thread, the image will not be presented (only the default Apple Pay logo) and the size will be set to "icon" as the default view.
-
Reply bubble experience - image in the reply bubble will not be presented, but only the payment details in text. The size of the reply bubble will be defaulted to "icon".
If using received bubble with style "small":
-
Received bubble experience - the image in the bubble will only be presented in the push preview message. Once the you tap to view the bubble in the conversation thread, the image will not be presented (only the default Apple Pay logo) and the size will be set to "icon" as the default view.
-
Reply bubble experience - image in the reply bubble will not be presented, but only the payment details in text. The size of the reply bubble will be defaulted to "icon".
If using received bubble with style "large":
-
Received bubble experience - the image in the bubble will be presented in the push message preview as well as in the conversation thread bubble. The size of the bubble will stay "large" as set in the SC request.
-
Reply bubble experience - the image in the reply bubble will be displayed, with the same image that was set in the received bubble. The size of the bubble will stay "large" as set in the received bubble in the SC request.
The URL passed in ImageURL of the received bubble must be whitelisted in Conversational Cloud. The image added in the RecievedMessage must be whitelisted in the structured content image whitelisting area. Contact your LivePerson representative (other contact options: chat with us on this page, or message Support) to whitelist images.
Limitations
- In the current version of the Apple Pay template, only a bot in Conversational Cloud (using the Messaging Agent SDK) will be able to receive the payment response (using the Conversation Metadata). A Human Agent is currently not exposed to these events. There will be an option to receive payment response data without the Messaging Agent SDK in the near future.