Buy Button (BETA)

The Buy Button enables you to build a checkout experience in Messenger. This button opens a native checkout dialog in Messenger and enables people to use their information stored in Messenger.

When adding a Buy Button to the Generic template, two things are rendered on the message bubble: the total price and a button that opens the dialog. Currently, this only works with the Generic Template.

This dialog displays the item, a price list, and payment method. Optionally, you can also request other information such as the person's name, shipping address, phone number and email address.

When the person taps the Pay button in the dialog, we will send you the tokenized credentials so that you can charge the person for the item. You should confirm the purchase with a message (e.g., with the Receipt Template).

Fixed vs Flexible Pricing

The Buy Button supports fixed and flexible pricing. Flexible pricing can be used when you modify pricing based on shipping. When flexible pricing is declared, the Checkout dialog will render a button that the person can tap to choose the shipping method. We call your webhook to get information about the shipping names and prices.

You can control which fields are requested. You should only request information required for the purchase.

Send Message with Buy Button

The Buy Button only works with the Generic Template and List Template and it must be the first button.

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"
                    }
                  ]
                }
              }
            ]
  
  ...

buttons fields

Property Name Description Type Required

type

Must be payment.

String

Y

title

Title of Buy Button. Must be "buy".

String

Y

payload

Developer defined metadata about the purchase.

String

Y

payment_summary

Fields used in the checkout dialog.

Object

Y

payment_summary fields

Property Name Description Type Required

currency

Currency for price.

String

Y

is_test_payment

Whether this is a test payment. Once set to true, the charge will be a dummy charge.

Boolean

N

payment_type

Must be FIXED_AMOUNT or FLEXIBLE_AMOUNT.

Enum

Y

merchant_name

Name of merchant.

String

Y

requested_user_info

Information requested from person that will render in the dialog. Valid values: shipping_address, contact_name, contact_phone, contact_email. You can config these based on your product need.

Array

Y

price_list

List of objects used to calculate total price. Each label is rendered as a line item in the checkout dialog.

Array

Y

price_list fields

Property Name Description Type Required

label

Label for line item.

String

Y

amount

Amount of line item.

String

Y

Buy button functionality is only available for US users. You will get the following error if you try to send to a user that is not in US. The error_subcode 2018112 indicates the user is not eligible for payment.

{
  "error":{"message":"(#200) The user is not eligible to receive payment messages.",
  "type":"OAuthException",
  "code":200,
  "error_subcode":2018112,
  "fbtrace_id":"DdAqW91SO+K"
}
    

You can also use User Profile API and query is_payment_enabled field to check if a user is eligible for payment before hand.