Native Ticketing

The Native Ticketing API provides a way to integrate your ticket sales workflow with the Facebook platform using native components on Facebook pages for mobile and web clients.

'Buy on Facebook' feature

Before You Start

You will need the following:

  • Facebook App ID
  • Facebook Brand Page ID
  • Facebook Business Account ID
  • Product Catalog ID
  • Merchant Settings ID
  • Payments Token

Step 1: Create a Facebook App

Go to developers.facebook.com, click My Apps, and create a new app. Once you have created the app and are in the App Dashboard, navigate to Settings > Basic, scroll the bottom of page, and click Add Platform.

Choose add the platform of your app and save your changes. You can change the platform or add another later if you wish.

Step 2. Associate a Facebook Page with Your App

This can be done using the App Dashboard. Note: This will be a new page called Associate Page, not your regular Brand Facebook Page.

  • Under Settings > Advanced, scrolldown to Create New Page

Step 3. Create a Facebook Business Account

If you don't already have a Facebook Business Account go to the Facebook Business Manager to create one.

Step 4. Associate Your App with Your Business

Go to Settings > Business Settings in the Facebook Business Manager to add your app.

Step 5. Associate Your Page with Your Business

In the Facebook Business Manager, click Pages in the left side navigation menu then click Add New.

Step 6. Complete Merchant Onboarding

Following the Merchant Onboarding Guide to create the Merchant Settings and submit and accept the Merchant Application.

Product Catalog Creation Settings

ParameterDescription

merchant_page

The Page that is associated with your app and your Business Account.

payment_provider

BOF_API

payment_provider_details

Details about your payment provider.

create_cart_url

https://{your-hostname}/create_cart

update_cart_url

https://{your-hostname}/update_cart

get_cart_url

https://{your-hostname}/retrieve_cart

get_shipping_options_url

https://{your-hostname}/shipping_options

create_order_url

https://{your-hostname}/create_order

get_order_status_url

https://{your-hostname}/get_status

Visit the Ticketing Reference for information about the callback URL.

Ticketing partners do not have to Submit an On-Boarding Application as part of the Merchant Onboarding.

Step 7. Accept the Merchant Setting Terms of Service

Run the static HTML webpage on your localhost server.

Step 8. Email Your Partner Manager

When you have completed Merchant Onboarding and accepted the Merchant Terms of Service, email your Partner Manager.

Reference

Please return the responses as specified in the spec below. For example:

Create Cart endpoint

  1. email_remarketing_allowed is a string with 0 or 1. We do not return true of false.
  2. Set the following fields before sending the response back to Facebook:
    • subtotal = calculate
    • shipping_price = 0
    • tax_price = 0

Expected HTTP Status Code: 200

Update Cart

  • Similar to create cart, set following fields before sending the response back to Facebook:
    1. subtotal = calculate
    2. shipping_price = 0
    3. tax_price = 0

Expected HTTP Status Code: 200

Shipping Options

  • Return the shipping_rates id value as default
  • Do not include rates_need_calculation attribute in the response as documented in the cart management API's. It's different for Native Ticketing integration.

Expected HTTP Status Code: 200

Create Order

  • digital_codes attribute in the create_order response is a JSON encoded string and not a JSON object.

Expected HTTP Status Code: 200

Example Response

import os
from flask import Flask
from flask import jsonify
from flask import request

app = Flask(__name__)

data = {}

#NOTE: please return 200 here for now, but this endpoint will soon be deprecated
@app.route('/get_status/{int:merchant_settings_id}/{int:order_id}')
def get_status(merchant_settings_id, order_id):
# return 200
return jsonify({})

@app.route('/create_order/{int:merchant_settings_id}/{int:order_id}', methods=['POST'])
def create_order(merchant_settings_id, order_id):
# charge the card
return jsonify({
  {
   “metadata”: {
    “redirect_url”: “${claim_url}”,
    "digital_codes": "{\"id\": [
      {\"image_url\": \"http://www.otherfocus.com/wp-content/uploads/2012/03/monalisa.jpg\", 
       \"row\": \"JJJ\", 
       \"seat\": \"24\", 
       \"section\": 
       \"TER 10\", 
       \"type\": \"qrcode\"}
    ]}",
    “order_id”: “${partner_order_id}”
   }
  }
})

@app.route('/shipping_options/{int:merchant_settings_id}/{int:order_id}')
def shipping_options(merchant_settings_id, order_id):
# use this endpoint to set the tax and fees (should be 0 for the pilot)
return jsonify({
"shipping_rates": [
{
"id" : "default",
"name" : "Digital Shipping",
"shipping_price" : 0,
"tax_price" : 0,
"currency" : "USD"
},
]
})

@app.route('/update_cart/{int:merchant_settings_id}/{int:order_id}', methods=['POST'])
def update_cart(merchant_settings_id, order_id):
# these fields must match the shipping options endpoint and ticket price
request.json['subtotal'] = 100
request.json['shipping_price'] = 0
request.json['tax_price'] = 0
data[order_id] = {'cart': request.json}
return jsonify(request.json)

@app.route('/create_cart/{int:merchant_settings_id}/{int:order_id}', methods=['POST'])
def create_cart(merchant_settings_id, order_id):
# return the cart object unmodified
request.json['subtotal'] = 100
request.json['shipping_price'] = 0
request.json['tax_price'] = 0
data[order_id] = {'cart': request.json}
return jsonify(request.json)

if __name__ == '__main__':
port = int(os.environ.get('PORT', 5000))
app.run(host='0.0.0.0', port=port, debug=True)

    

Ticket Metadata Updates

You have the ability to update the issued QR codes post-order to reflect changes performed due to ticket resales, order cancellations, ticket reassigning, etc.

Updates can be posted to the Graph API endpoint:

POST https://graph.facebook.com/vX.X/{order_id}/tickets

Request parameters:

ParameterDescriptionTypeRequired

order_id

FB order identifier (note this is a URL parameter, not a request body parameter).

String

Required

redirect_uri

Order claim URL

String

Optional

digital_codes

Updates to the issued tickets

digital_codes(see below)

Optional

digital_codes

is the same JSON structure that was provided in the Commerce API's create_order response, and will replace the tickets issued for the order.

{
   "<ticket_tier_id1>": [
     {
       "type": "qrcode",
       "image_url": "<qrcode_image_url>",
       "code": "<qrcode_value>",   // optional
     },
     ...
   ],
   "<ticket_tier_id2>": [
     ...
   ]
}

Response on success:

{
      "success" : true
}

FAQ

Who creates the UI for the checkout flow on Facebook?

  • Facebook. Once you implement Ticketing Tiers and enable commerce integration, Facebook will render the UI for both Desktop and Mobile.

Does Facebook have a test environment where I can test commerce integration?

  - No. You must test using your product account. 

I don't see the callbacks getting invoked when I initiate checkout or add tickets for purchase etc.

  • All your callbacks are invoked when people click on the purchase button on Facebook. Not before that.

I am seeing this error: Couldn't Complete Purchase: Sorry, something went wrong and your payment couldn't be completed. You haven't been charged for this transaction, so please try again later. What do I do next?

  • Are you calculating the subtotal and sending this attribute back in the create_cart/update request correctly?
  • Remove rates_need_calculation from the shipping_rates object
  • Make sure you are setting shipping_rates id to default since ticketing doesn’t involve.

I am seeing this error: Processing Error: Sorry, there was an issue fulfilling your order. What do I do next?

  • This is usually an error with your endpoints returning some bad data. Please check the logs on your server to before reaching out to Facebook team.

Is any new email that the user types in to the FB checkout page going to get confirmed by FB before we receive it?

  • No.

What happens when a user mistypes the email?

  • The user can see their ticket orders on the event page, with the possibility to contact the provider.

Any support for lists of specific quantities of tickets?

  • No.

Can I send a QR code for ticket redemption?

  • Yes. As a part of the create_order endpoint you can return metadata property with digital_codes.