Payment Webhook (Beta)


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 →

This callback occurs when the user taps the pay button from the checkout dialog produced via the Buy Button.

It contains the requested user information as well as payment credentials. Depending on the payment provider you use, the payment credentials passed may differ.

You must subscribe to this callback by selecting the messaging_payments field when setting up your webhook.

For more, see the payments guide.

Event Properties

The following are the properties that will be sent in the body of the event to your webhook.

payment object

Field Name Description Type

payload

Metadata defined in the Buy Button.

String

requested_user_info

Information that was requested from the user by the Buy Button.

Object

payment_credential

Payment credentials.

Object

amount

Total amount of transaction.

Object

shipping_option_id

The option_id of the selected shipping option sent via the checkout update callback. Only applicable for flexible payments.

String

requested_user_info object

Data in this object will depend on the requested user information defined on the Buy Button.

Field Name Description Type

shipping_address

Person's shipping address

Object

contact_name

Person's name

String

contact_email

Person's email

String

contact_phone

Person's phone number

String

shipping_address object

Field Name Description Type

street1

Shipping address street, first line

String

street2

Shipping address street, second line

String

city

Shipping address city

String

state

Shipping address state

String

country

Shipping address country

String

postal_code

Shipping address postal code

String

payment_credential object

Field Name Description Type

provider_type

Payment provider type (one of stripe/paypal/token)

String

charge_id

Payment provider charge id (for stripe/paypal, null for tokenization), for a test_payment, the charge id will be test_charge_id_12345

String

tokenized_card

PGP-signed tokenized charge card (null for stripe/paypal)

String

tokenized_cvv

PGP-signed CVV number (null for stripe/paypal)

String

token_expiry_month

Expiry month (null for stripe/paypal)

String

token_expiry_year

Expiry year (null for stripe/paypal)

String

fb_payment_id

A facebook issued payment id for tracking. If it is a test payment, the id will be test_payment_id_12345.

String

amount object

Field Name Description Type

currency

Currency of amount

Object

amount

Total amount

String

Example Event

Stripe/PayPal

The following is an example event that will be sent to the messaging_payments webhook for bots using a connected Stripe/PayPal account as their payment provider. The event will be sent to your webhook once the user has been charged and the funds have been successfully transferred to your Stripe/PayPal account.

{
  "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": {
                "street_1": "1 Hacker Way",
                "street_2": "",
                "city": "MENLO PARK",
                "state": "CA",
                "country": "US",
                "postal_code": "94025"
              },
              "contact_name": "Peter Chang",
              "contact_email": "peter@anemailprovider.com",
              "contact_phone": "+15105551234"
            },
           "payment_credential": {
              "provider_type": "stripe", # paypal if you are using paypal as provider
              "charge_id": "ch_18tmdBEoNIH3FPJHa60ep123",
              "fb_payment_id": "123456789",
            },      
            "amount": {
              "currency": "USD",
              "amount": "29.62"
            }, 
            "shipping_option_id": "123"
          }
        }
      ]
    }
  ]
}

Tokenized Payment

The following is the example event that will be sent to the messaging_payments webhook for bots using tokenized payments in the Messenger webview.

{
  "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": {
                "street_1": "1 Hacker Way",
                "street_2": "",
                "city": "MENLO PARK",
                "state": "CA",
                "country": "US",
                "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"
          }
        }
      ]
    }
  ]
}

Decrypted Payment Result

Field Description Type

name

Person name

String

amount

Amount of transaction

Number

timestamp

Epoch timestamp

Number

external_transaction_id

Transaction ID from payment processor, in case of test payment, the value will be test_charge_id_12345.

String

fb_payment_id

Facebook payment ID, in case of a test payment, the value will be test_payment_id_12345.

String

provider

Facebook payment provider ID

String

You can learn how to decrypt the data by following the detailed decrypting guide here.