Payments (BETA)

We've made it easy for you to accept payments from people in your bot.

There are two options for integration:

Both are well-integrated with Messenger and allow you to obtain the user, shipping, and payment information needed to complete a purchase. Both allow you to use the information already stored in Messenger, making payments fast and seamless.

Buy Button

The Buy Button can be used with Generic Template messages. The button opens a checkout dialog, allowing a person to choose their payment method, shipping address, and other details.

When the Pay Button is tapped, the credentials are sent to your webhook, allowing you to complete the transaction. The entire buying experience happens in Messenger.

Refer to the reference docs for the Buy Button for more details.

Implementation

Go through the following steps to implement payment with buy button end to end.

  1. Set up your payment provider
  2. Regenerate Page Access Token
  3. Subscribe to Payment Webhook Events
  4. Send a message with Buy Button
  5. Process payment webhook callback
  6. Process checkout update callback (optional)

Set up payment provider

Currently, we support Stripe/PayPal or Tokenized Payments.

Stripe and PayPal

Stripe/PayPal requires linking your payment account in page settings. Every page needs to link its Stripe/Paypal account in order to receive payments through Stripe/Paypal. User payments will be sent directly to your linked Stripe/Paypal account when a user clicks Pay.

Tokenized Payment

Tokenized payments do not require any extra account linking on a page level. We will send an encrypted tokenized card to your webhook once a user makes a payment. You can then charge the card with the payment provider you prefer. You will need to set your public key through thread setting for using tokenized payments. This is a good way to scale payment integrations for an App that manages multiple pages.

Follow the required payments setup steps to finish your payments setup.

Regenerate Page Access Token

Once you've been accepted into the beta program for payments, your app will have the pages_messaging_payments permission. After you've been granted this permission, you must regenerate your token so that your new token has the correct scopes needed to make payment-related calls.

Subscribe to Payment Webhook Events

You must subscribe to messaging_payments webhook events to complete the flow and enable user payments. If you are using flexible price payment type, you also need to subscribe to messaging_checkout_updates.

You can also optionally subscribe to the pre-checkout webhook event.

Send Message with Buy Button

You can now send messages to a user using the buy button. Test payment is supported for development. Refer to reference docs for the Buy Button for more information.

Process Payment Callback

After a user clicks on the buy button, a native payment dialog will appear as described in the buy button reference. After user clicks on pay, user and payment credentials are sent to you to as a webhook event for you to complete the transaction. You must subscribe to messaging_payments webhook event to receive the payment event. This event will not appear in the Webhook interface until you've been accepted into the beta program. The format of the credential differs depending on which payment provider you use. After a payment is made successfully, we will to send a receipt to the user to confirm the payment.

See more details in the reference doc for the Payment Callback to learn about the data format and how to handle events.

Process Checkout Update Callback (Optional)

You must support this callback if you're using flexible-amount payments. This callback sends the person's shipping address to you, enabling you to provide users with a list of available shipping options and prices. This event will not appear in the Webhook interface until you've been accepted into the beta program.

See more details in the reference doc for the Checkout Update Callback.

Webview and Messenger Extensions

Using Webview and Messenger Extensions, you can integrate payments into your own checkout page. By using the Messenger Extensions Javascript SDK, you can trigger a dialog in Messenger allowing you to obtain the user information needed to complete a purchase. The buying experience happens on your checkout page.

Read the reference docs for Webview and Messenger Extensions for more details.

Implementation

Go through the following steps to implement payments in the webview end-to-end.

  1. Set up your payment provider
  2. Open a payment dialog
  3. Process the payment

Set up a payment provider

Similar to the Buy Button integration, we also support Stripe/Paypal/Tokenized payment for webview. Stripe/Paypal requires a linked payment account, which can be done in page settings. Every page need to link a Stripe/Paypal account in order to receive payments. User payments will be sent directly to your linked account.

Tokenized payments do not require any extra account linking on your page. We will send an encrypted tokenized card to your webview callback when users submit payments. You can then charge the card with your preferred payment provider.

For webview, you will need to set your public key regardless of which payment provider you choose since we will always encrypt the data we send to you through the SDK.

Follow the required payments setup steps to finish setting up payments.

Open payment dialog

After you set up your payment provider, you can use the SDK we provided to open a native payment dialog inside webview. Users can select their payment method from the dialog and enter other required information such as shipping address. After users click continue on the dialog, we will send the information as a callback to your SDK call. You can then calculate the final cost based on the information provided and update your own webview checkout flow. This step is required to authorize the payment.

Read the Open Payment Dialog reference docs for Webview and Messenger Extension for more details on how to trigger the native payment dialog.

Process the payment

After you calculate the final price and the user completes a transaction on your checkout flow, there are two ways to process the payment:

Tokenized Payment

To use a tokenized payment with an encrypted tokenized card, you can call requestAuthorizedPaymentCredentials in SDK and we we will send you the tokenized card through the callback function. Please remember you have to call requestPaymentCredentials prior to this. Read the Request Authorized Payment Credential reference docs for spec and details.

After you receive the tokenized card, you can decrypt the card and CVV numbers and charge it using your preferred payment provider. You can learn how to decrypt by reading the detailed decrypting guide.

Stripe/Paypal

If you are linking a Stripe/Paypal account to your page, you can call processPayment on the SDK to charge the user. The payment will be sent directly to your Stripe/Paypal account. We will send the confirmation and Stripe/Paypal charge id back to your callback once the payment is successful.

Set Up Payments

To set up payments for the Messenger Platform:

  1. Set your Payment Policy
  2. Connect a Payment Method
  3. Set your Encryption Key (optional)

Set your Payment Policy

You must set your payment privacy URL so that we can display it in our payment dialogs and allow users to view your terms.

Connect a Payment Method

You can accept payments with Stripe or Paypal. Go to the Payments tab in your Page Settings to connect your Stripe/Paypal account. If you are using a Buy Button with tokenized payments, you can skip this step, as a page payment account is not required.

Paypal does not allow you to pay yourself. If you attempt to make a purchase and the email for your Facebook account is the same as your Paypal account, you may encounter an error. You can avoid this error by modifying either your Facebook or Paypal account email address.

If you are using Buy Button with Paypal/Stripe, you have completed the payments set up and can skip the rest of this guide.

Set your Encryption Key (Optional)

You may also set a payment public key to encrypt sensitive data that is sent to you. This is only required for payments initiated from the Web View and Buy Button if you are receiving tokenized payments. If you are using the Buy Button with Stripe/Paypal, a public key is optional and you can skip the rest of this set up.

1) Generate Key with RSA, 4096 bits, non-expiring. Note output which contains the Key ID

$ gpg --gen-key

...  

gpg: key [KEY_ID] marked as ultimately trusted
public and secret key created and signed.

2) Export public key with armor

$ gpg --armor --export [KEY_ID] > public.key

3) Format the key so that you can set it using thread_settings. Replace newlines with "\n"

$ perl -p -e 's#\n#\\n#g' public.key > escaped_key.txt

4) Upload to thread settings

curl -X POST -H "Content-Type: application/json" -d '{
  "setting_type" : "payment",
  "payment_public_key" : "-----BEGIN PGP PUBLIC KEY BLOCK-----\nVersion: GnuPG v1\n\nmQINB....WbaF19IQXE=\n=TI+h\n-----END PGP PUBLIC KEY BLOCK-----\n"
  }' "https://graph.facebook.com/v2.6/me/thread_settings?access_token=PAGE_ACCESS_TOKEN"

Learn How to Decrypt

In some cases, sensitive data is encrypted when transmitted. For tokenized payments in buy button integration and all payment types in webview integration, we encrypt data using your public key, enabling you to decrypt it.

Example: The response to completing a payment using Messenger Extensions.

{
  "payment_result":"-----BEGIN PGP MESSAGE-----\n\nhQIMA6FrXqi2gpwjAQ/7BvmxbMQRmrVhKCzauTPaub3ySabTP+pxg8\n=aYwc\n-----END PGP MESSAGE-----\n"
}

Import Facebook's Public PGP Key

Get Facebook's public key and import it into your key ring. Decrypted files from Facebook will be signed and can be verified using our public key.

Download Facebook's Public Key
$ gpg -a --import facebook_public.key

Steps

1) Get the encrypted value (armor and data) from the response.

Example

-----BEGIN PGP MESSAGE-----\n\nhQIMA6FrXqi2gpwjAQ/7BvmxbMQRmrVhKCzauTPaub3ySabTP+pxg8\n=aYwc\n-----END PGP MESSAGE-----\n

2) You may have to format the encrypted response by replacing "\n" with newlines.

$ perl -pi -e 's#\\n#\n#g' encrypted_value.gpg

3) Call gpg to decrypt.

$ gpg -d encrypted_value.gpg

See the section below on GPG Notes to read more about gpg.

GPG Notes for Developers

Here are some additional notes about GPG that may help you during development.

Decryption

When using the GPG program from the command line, it may be difficult to see the decrypted content because it is interleaved with the output. In the example below, the decrypted content is "ch_18to0LEoNIH3FPJH5YJ61hup".

$ gpg -d response.gpg
You need a passphrase to unlock the secret key for
user: "Alyssa P. Hacker <hacker@hack.com>"
4096-bit RSA key, ID B1234C11, created 2016-09-14 (main key ID 1ABC23D4)

gpg: encrypted with 4096-bit RSA key, ID B1234C11, created 2016-09-14
      "Alyssa P. Hacker <hacker@hack.com>"
ch_18to0LEoNIH3FPJH5YJ61hupgpg: Signature made Wed Sep 14 17:45:32 2016 PDT using RSA key ID 71824565
gpg: Good signature from "Facebook, Inc."

Trust

During decryption, you may get a warning about the key not being certified. You can read more about validating trust in your key ring.

gpg: Signature made Wed Sep 14 17:45:32 2016 PDT using RSA key ID 12345678
gpg: Good signature from "Facebook, Inc."
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 41B8 0953 E4A2 90BA 28A7  3776 2F38 12D3 DEE9 BC32

Links

This test payment features won't be available until Nov 8th 5pm PST.

How to Test Payment

We allow people to easily test payment to unblock their payment integration development. There are two ways to test the end to end flow without charging real money. You can also test the integration without having to be accepted to the beta program.

Use is_test_payment Flag

You can test your payment on transaction level by specify is_test_payment flag in the payment button payload. Refer to the Buy Button api specs for details. Once the flag is set to true, we will not charge user's credit card, but instead, returning a predefined dummy charge_id back to you. Please note that you can only set is_test_payment flag to your app role users(admin/dev/tester). So you need to add your test user as app role user first for testing. You don't need payment permission to do the test. This currently only works for Buy Button.

Add Test Users in Thread Settings

If you are using Webview Extensions payment integrations. You would have to add your test users through thread settings. Once you added your test users there, all the payment made by test users will be a dummy charge. Please note that this works for Buy Button integration too.

Once a test payment is made by your test user, you will get a predefined result back that will flag this payment as test payment. Please refer to the payment webhook event specs and webview extension docs for details.

If you haven't been accepted to beta program yet, the test payment feature currently only works for tokenized payments.

Help Center

Visit our Help Center for more information about payments in Messenger.