JSON format for payment data (Apple Pay)

The client's system needs to provide REST endpoints that expose details about products to be purchased, shipping methods and so on. Converse requires the payment data to be JSON formatted text, in the format given below.

The following example shows all the required and optional variables. For example items and total are required but you can leave out shippingMethods and requiredShippingContactFields if these aren't relevant.

{
  "title": "Your order from the Widget Store",
  "coverImageUrl": "https://fdfjkdjfk/djfjdfkj/jfkdfkj/image.png",
  "items": [
    {
      "label": "Large Widgets (Pack of 50)",
      "amount": 28.50
    },
    {
      "label": "Small Widgets (Pack of 1000)",
      "amount": 8.00
    }
  ],
  "total": {
    "amount": 36.50,
    "label": "Total cost"
  },
  "countryCode": "US",
  "currencyCode": "USD",
  "shippingMethods": [
    {
      "label": "Free shipping",
      "detail": "Expected delivery: Tuesday 11th",
      "amount": 0,
      "identifier": "FREE"
    },
    {
      "label": "Fast shipping",
      "detail": "Tomorrow before 1pm",
      "amount": 7.00,
      "identifier": "FAST"
    }
  ],
  "requiredBillingContactFields": [
    "postalAddress",
    "name",
    "phoneticName",
    "phone",
    "email"
  ],
  "requiredShippingContactFields": [
    "postalAddress",
    "name",
    "phoneticName",
    "phone",
    "email"
  ]
}

Variables

For additional information, refer to the Apple Developer documentation.

Variable Description
title The heading that appears in the pay bubble inviting the customer to pay.
coverImageUrl Optional. The URL of an image to appear in the pay bubble. This must be:
  • JPEG or PNG
  • Approximately 320 x 185 pixels (Apple will resize the image to fit)
items An array of one or more payment summary items, which will be shown on the payment sheet. Each summary item has a:
  • label – the description of the summary item. This could be a product or any additional charges. Required.
  • amount – the amount to pay as a float or double. Required.
total The total amount to pay, as a float or double. Required.
countryCode The country of origin of the merchant. Required.

Enter this as a two-letter ISO 3166 country code.

currencyCode The currency that will be used. Required.

Enter this as a three-letter ISO 4217 currency code.

shippingMethods Optional. An array of the available shipping methods offered by the business, which will be shown on the payment sheet. Where:
  • label – first line of the shipping method
  • detail – additional information about the shipping method
  • amount – shipping cost for the order, as a float or double
  • identifier – an internal ID
requiredBillingContactFields An array of the fields for a billing contact. The fields are required in order to process the transaction. The customer will fill in this information:
  • postalAddress – billing address
  • name – name
  • phoneticName – phonetic spelling of the name.
  • phone – telephone number
  • email – email address
requiredShippingContactFields Optional. An array of the fields for a shipping contact. The fields are required in order to process the transaction. The customer will fill in this information.

In Converse messages, you can access these variables through the Payment data variable set on the Advanced tab of the Payment interaction. For more information, see Payment variables.