Implementing Payments With the Buy Button

The buy button can be sent in a Generic Template or List Template message. The button starts the payment flow, and prompts the message recipient to choose their payment method, shipping address, and other details.

When the message recipient taps the 'Pay' button, the Messenger Platform will automatically complete the transaction using your connected Stripe or Paypal account, or send a tokenized, single-use Discover Card to your webhook for you to process the payment. Once the transaction is completed, details are returned to your webhook.

Requirements

Before you begin, ensure you have set up a payment provider.

1. Set your Payment Privacy Policy URL

For buy button integrations, you must provide a payment privacy URL that Messenger can display to your customer.

To provide your privacy policy URL, send a POST request with the following JSON payload to the Messenger Profile API:

{
  "payment_settings" : {
    "privacy_url" : "<YOUR_PRIVACY_URL>"
  }
}

Example Request

  curl -X POST -H "Content-Type: application/json" -d '{
  "payment_settings" : {"privacy_url" : "www.facebook.com"}
  }' "https://graph.facebook.com/v2.6/me/messenger_profile?access_token=<PAGE_ACCESS_TOKEN>"

For more, see the Messenger Profile API reference

2. Regenerate Your Page Access Token

When your bot is accepted into the payments beta program, it will be granted the pages_messaging_payments permission.

Once this permission is granted, you must regenerate your access token in your Facebook app's Messenger Settings. This ensures your access token has the correct scopes to make payment-related requests.

For more on generating an access token, see Get a Page Access Token.

3. Subscribe to Buy Button Webhook Events

For buy button payments, you may subscribe to the following webhook events in the Messenger settings for your app:

Webhook EventDescription

messaging_payments

Sent to your webhook when the user's payment has been successfully completed.

messaging_checkout_updates

Optional. Sent to your webhook after the buy button is clicked. Sends you the customer's shipping information, and expects a response containing shipping options and taxes.

messaging_pre_checkouts

Optional. Sent to your webhook after the message recipient clicks the 'Pay' button, but before the payment is processed. This allows you to execute business logic before the payment is actually charged.

4. Send a Message With the Buy Button

The buy button can be sent using the generic template or the list template. To send the buy button, specify type: "payment" and a payment_summary object in the buttons array of the template.

When the message recipient clicks the buy button, the Messenger Platform will display a payment dialog.

For more, see the buy button reference.

Example

{
...
  buttons: [{
      "type":"payment",
      "title":"buy",
      "payload":"DEVELOPER_DEFINED_PAYLOAD",
      "payment_summary":{
        "currency":"USD",
        "payment_type":"FIXED_AMOUNT",
        "is_test_payment" : true, 
        "merchant_name":"Peter's Apparel",
        "requested_user_info":[
          "shipping_address",
          "contact_name",
          "contact_phone",
          "contact_email"
        ],
        "price_list":[
          {
            "label":"Subtotal",
            "amount":"29.99"
          },
          {
            "label":"Taxes",
            "amount":"2.47"
          }
        ]
      }
    }
  ]
...
}

5. Handle the messaging_checkout_updates Event (Optional)

Beta Access Required

Note that the messaging_checkout_updates event will not appear in the Messenger webhook interface until you have been accepted into the beta program.

You must support the messaging_checkout_updates webhook event if you are using flexible-amount payments. The event sends your webhook the customer's shipping address in the checkout_update property.

Required HTTP Response

You must respond to this event with a 200 OK HTTP status, along with an array of updated shipping options and price details. The Messenger Platform will then display an updated checkout summary for the customer to accept.

Example Event

{
  "object": "page",
  "entry": [
    {
      "id": "PAGE_ID",
      "time": 1473204787206,
      "messaging": [
        {
          "recipient": {
            "id": "PAGE_ID"
          },
          "timestamp": 1473204787206,
          "sender": {
            "id": "USER_ID"
          },
          "checkout_update": {
            "payload": "DEVELOPER_DEFINED_PAYLOAD",
            "shipping_address": {
              "id": 10105655000959552,
              "country": "US",
              "city": "MENLO PARK",
              "street1": "1 Hacker Way",
              "street2": "",
              "state": "CA",
              "postal_code": "94025"
            }
          }
        }
      ]
    }
  ]
}

Example Response

For more, see the checkout update reference.

{
 "shipping":[
    {
      "option_id":"1", //custom ID
      "option_title":"Fedex", //plain-text description
      "price_list":[
        {
          "label":"Shipping", //label to display
          "amount":5.99 //cost to display
        },
        {
          "label":"Tax",
          "amount":1.99
        }
      ]
    },...  
  ]
}

6. Handle the Payment Event

For buy button integrations, payments are handled with the messaging_payments webhook event. The event will vary based on whether you are using a connected Stripe/PayPal account or tokenized payments as your payment provider.

Connected Stripe/PayPal Accounts

After your customer clicks the 'Pay' button, the Messenger Platform will pass the their payment information to Stripe/PayPal on your behalf to complete the charge.

On success, the messaging_payments event will be sent to your webhook with customer and payment details, including the Stripe/PayPal charge_id.

Please note that Stripe/PayPal payments have a $0.50 minimum charge.

{
  "object": "page",
  "entry": [
    {
      "id": "PAGE_ID",
      "time": 1473208792799,
      "messaging": [
        {
          "recipient": {
            "id": "PAGE_ID"
          },
          "timestamp": 1473208792799,
          "sender": {
            "id": "USER_ID"
          },
          "payment": {
            "payload": "DEVELOPER_DEFINED_PAYLOAD",
            "requested_user_info": {
              "shipping_address": {
                "country": "US",
                "city": "MENLO PARK",
                "street1": "1 Hacker Way",
                "street2": "",
                "state": "CA",
                "postal_code": "94025"
              },
              "contact_name": "Peter Chang",
              "contact_email": "peter@anemail.com",
              "contact_phone": "+15105551234"
            },
           "payment_credential": {
              "provider_type": "<stripe|paypal>",
              "charge_id": "ch_18tmdBEoNIH3FPJHa60ep123",
              "fb_payment_id": "123456789",
            },      
            "amount": {
              "currency": "USD",
              "amount": "29.62"
            }, 
            "shipping_option_id": "123"
          }
        }
      ]
    }
  ]
}

For more, see the payment callback reference.

Tokenized Payments

After your customer clicks the 'Pay' button, the Messenger Platform will pass their payment information in the messaging_payments event to your webhook. The event will include a tokenized, single-use Discover Card number in the payment_credential object.

To complete the payment, decrypt the tokenized card and use it to process the payment. Please note that many payment processors require you to submit the payer's zip code as part of the payment information; failing to do so can lead to unexpected payment rejections.

{
  "object": "page",
  "entry": [
    {
      "id": "PAGE_ID",
      "time": 1473208792799,
      "messaging": [
        {
          "recipient": {
            "id": "PAGE_ID"
          },
          "timestamp": 1473208792799,
          "sender": {
            "id": "USER_ID"
          },
          "payment": {
            "payload": "<DEVELOPER_DEFINED_PAYLOAD>",
            "requested_user_info": {
              "shipping_address": {
                "country": "US",
                "city": "MENLO PARK",
                "street1": "1 Hacker Way",
                "street2": "",
                "state": "CA",
                "postal_code": "94025"
              },
              "contact_name": "Peter Chang",
              "contact_email": "peter@anemailprovider.com",
              "contact_phone": "+15105551234"
            },
            "payment_credential":{
               "provider_type" : "token",
               "tokenized_card": "<TOKENIZED_CARD>",
               "tokenized_cvv":"<TOKENIZED_CVV>",
               "token_expiry_month":"3",
               "token_expiry_year":"2019"
               "fb_payment_id" : "123456789",
            },
            "amount": {
              "currency": "USD",
              "amount": "29.62"
            }, 
            "shipping_option_id": "123"
          }
        }
      ]
    }
  ]
}

For more, see the messaging_payments webhook event reference.


7. Complete the Payment

Once you receive the messaging_payments webhook event and have completed any additional processing, you must return a 200 OK HTTP response to the Messenger Platform to complete the payment process.