MessengerExtensions.PaymentRequest (beta)

Messenger Extensions SDK

This method is a part of the Messenger Extensions SDK. For information on including the SDK in your site, see Add Messenger Extensions SDK.

Payments are currently in beta

The feature can be tested by any bot in development mode, but the bot must be accepted into our beta program to receive payments in production.

Request Access →

Using the Messenger Extensions SDK you can integrate payments in the webview, using a connected Stripe/Paypal account or tokenized, single-use Discover Card. The PaymentRequest object represents an individual payment request that conforms to the W3C standard Payment Request API.

For complete details on implementing payments, see Implementing Payments in the Messenger Webview.

Contents

Requirements

Implementing payments in the Messenger webview with PaymentRequest requires a valid payment provider, and is available for U.S.-based transactions only.

For complete details, see Implementing Payments in the Messenger Webview.

Constructor

The PaymentRequest object defines a new payment request that conforms to the W3C standard Payment Request API.

MessengerExtensions.PaymentRequest(
  methodData,
  paymentDetails,
  additionalOptions
);

The PaymentRequest returns a promise. When the promise resolves, details of the payment transaction are returned to you.

Parameters

Parameter Type Description

methodData

Array

Payment methods for the request and their setup. See methodData Properties.

paymentDetails

Object

The items, total cost, and shipping options for the payment. This information will be displayed to the user at checkout. See paymentDetails Properties.

additionalOptions

Object

Specifies additional information, including whether shipping is required, and whether additional information should be gathered from the user. See additionalOptions Properties.

methodData

Name Type Description

supportedMethods

Array

The type of payment. Currently, only 'fb' is supported.

data

Object

Details about the merchant initiating the payment. For object properties, see Data Object Properties below.

methodData.data

The following properties are the object for the data property of methodData:

Name Type Description

merchantTitle

String

Optional. The merchant name to display. Defaults to the Facebook Page name.

merchantImageUrl

String

Optional. The URL for an image to display next to the merchantTitle. Defaults to the app icon.

merchantFBPageId

String

The page id with onboarded payment method. Page id can be found in page admin tool, page > About > More Info.

termsUrl

String

URL to link to your payment privacy terms and conditions.

paymentDetails

Name Type Description

displayItems

Array

Information about the items the user will be charged for in the format:

[{
  label: 'T-shirt',
  amount: {
    currency: 'USD',
    value : '15.00'
  },
  ...
}]

total

Object

The total cost to display to the user in the format:

{
  label: 'Total', // defaults to "Total"
  amount: { 
    currency: 'USD', 
    value : '16.23' 
  }
}

shippingOptions

Array

Optional. Shipping options for the user to select in the format:

[
  {
    id: 'free-shipping',
    label: 'Free shipping in US',
    amount: {currency: 'USD', value: '0.00'},
    selected: true
  },
  ...
]

additionalOptions

Name Type Description

requestShipping

Boolean

Specifies if shipping is required. If true, you must handle the shippingaddresschange and shippingoptionchange webhook events.

requestPayerName

Boolean

Displays a required name field to the user in the UI. The payer's name is returned to you in the final response.

requestPayerEmail

Boolean

Displays a required email field to the user in the UI. The payer's email is returned to you in the final response.

requestPayerPhone

Boolean

Displays a required phone number field to the user in the UI. The payer's phone number is returned to your in the final response.

Instance Methods

The following methods can be called on an instance of PaymentRequest.


canMakePayment()

Checks if PaymentRequest is valid and the payment flow can be started.

Returns

Promise<Boolean>

Fulfillment value equals true if the payment can be made, and false if it cannot.

Example Request

request.canMakePayment()
  .then(response => {
    if (response === true) {
      // proceed
    } else {
      // something went wrong, e.g. invalid `displayItems` configuration
      // or the device does not run a 
      // recent enough version of the Facebook app
    }

  })
  .catch(error => {
    // an error such as `InvalidStateError`
    // if a payment is already in process
  });

show()

Displays the checkout dialog in the webview. Resolves when the customer has confirmed the payment details.

After the transaction, consider sending a purchase confirmation or receipt into the thread. You might use the Receipt Template to send it.

Returns

Promise<Object>

The promise returns an object with payment details that vary based on the chosen payment provider:

  • Stripe/PayPal: Returns the payment confirmation details from Stripe/PayPal, including an externalTransactionID for your records.

  • Tokenized Payments: Returns the person's payment information, including a one-time use Discover card number that you may use to complete the charge.

Example Request

request.show().then(response => {
  
  // Process the payment if using tokenized payments.
  // Process the confirmation if using Stripe/PayPal

  paymentResponse.complete('success').then(() => {
    // cleanup UI, log, etc
  });

}).catch(error => console.log(error));

Example Stripe/Paypal Response

{
  "paymentRequestID": "f12a99afd3b16ec",
  "methodName": "fb",
  "details": {
    "paymentData": {
      "name": "Michael Knight",
      "amount": "11.23",
      "timestamp": "1500937629",
      "externalTransactionId": "ch_1AjFdrDCVd5339DX6THspfeg"
    },
    "paymentId": "934481639947127",
    "orderData": {
      "totalCurrencyAmount": {
        "amount": "11.23",
        "currency": "USD"
      }
    }
  },
  "shippingAddress": {
    "phone": "",
    "country": "US",
    "addressLine": [
      "1 Hacker Way"
    ],
    "region": "CA",
    "city": "Menlo Park",
    "postalCode": "94025",
    "recipient": "Tim Jones"
  },
  "shippingOption": "extra",
  "payerName": "",
  "payerEmail": "",
  "payerPhone": ""
}

Example Tokenized Payment Response

{
  "paymentRequestID": "fe319dap33fc8",
  "methodName": "fb",
  "details": {
    "paymentData": {
      "tokenCardNumber": "<TOKENIZED_CARD>",
      "tokenCvv": "<TOKENIZED_CVV>",
      "expirationMonth": "3",
      "expirationYear": "2020",
      "billingAddress": {
        "postalCode": "94036"
      }
    },
    "paymentId": "936416393739001",
    "orderData": {
      "totalCurrencyAmount": {
        "amount": "11.23",
        "currency": "USD"
      }
    }
  },
  "shippingAddress": {
    "phone": "",
    "country": "US",
    "addressLine": [
      "1 Hacker Way"
    ],
    "region": "CA",
    "city": "Menlo Park",
    "postalCode": "94025",
    "recipient": "Tim Jones"
  },
  "shippingOption": "extra",
  "payerName": "",
  "payerEmail": "",
  "payerPhone": ""
}

Support for Deprecated Versions

As of July 27, 2017, the implementation and usage of webview payments from Messenger Platform versions v1.2 - v2.0 are deprecated. Support for the deprecated usage will continue until February 1, 2018.

All integrations for payments in the Messenger webview, using the Messenger Extensions SDK should migrate to the usage described in this document.

The documentation for the deprecated usage, can be found here: