Steps to Implement Master FFL Using APIs and SDKs

This document is intended to be a quick start guide which provides high-level guidance for the using the Master FFL SDKs and API.

Frontend Implementations Using the SDK

A proper frontend implementation includes:

Identifying Regulated Items
Determining if any NFA Items are present
Displaying eligible Receiving Dealers

Identifying Regulated Items

When integrating using the Checkout SDK or Checkout API SDK, identifying Regulated Items is the platform’s responsibility.

This is typically handled by:

Allowing the Seller to map categories or individual products to ItemType\ItemSubType.
Using those mapped values in checkout logic to determine dealer filtering requirements.

These mappings directly affect dealer eligibility results.

Determining if NFA Items Are Present

If any cart item is mapped to an NFA ItemType the dealer search must filter to only show dealers willing and able to perform NFA transfers.

When using:

Checkout SDK: Pass the appropriate flag when initializing the FFL Checkout Iframe (e.g., options.onlyNFADealers = true).
Checkout API SDK: Apply the equivalent filter in the search request.

Displaying Receiving Dealers

MasterFFL provides two approaches:

1. Checkout SDK (FFL Checkout Iframe Recommended)

https://masterffl.readme.io/docs/using-checkout-sdk

Hosted iframe solution
Requires minimal custom UI development
Handles dealer filtering and presentation
Recommended for most use cases

Provides an easy to implement, low maintenance solution suitable for most use cases.

2. Checkout API SDK

https://masterffl.readme.io/docs/using-api-checkout-sdk

Returns paginated dealer search results as JSON
Allows full UI customization
Requires additional interface development

While the API SDK offers maximum flexibility, most integrations benefit from the Checkout SDK due to reduced development time and built-in UX optimization.

Backend Implementations Using the System API

Once a Receiving Dealer is selected and checkout completes, backend integration begins.

Base URL: ffl-api.masterffl.com

Initiate Transfer v2 API

POST /v2/ffl/transfers/ - Documentation Link

Purpose:
Create and initiate a Transfer Workflow in FFL360.

When to call:
Immediately after order placement, once the Receiving Dealer has been selected.

You must pass:

Buyer details
Seller details
Order information
Receiving Dealer’s FFL License Number
Details about Regulated Items

Best Practice:
If using consignment shipping, only pass items that must ship to the Receiving Dealer.

This call begins the compliance validation process and ultimately results in generation of the Master FFL Transfer Proof.

Transfer Webhooks

Documentation Link

Within FFL360 store administration:

Enable post Transfer Workflow Webhooks
Configure a receiving URL

When the Transfer Workflow completes, the webhook sends:

Link to the Master FFL Transfer Proof
Final Receiving Dealer license details
Receiving Dealer preferred shipping address

Important:

The Receiving Dealer may have changed during the workflow.
The platform must update the shipping address for regulated consignments based on webhook data.
License details should be stored with the order for compliance tracking.

Send E-comm Status Update

PUT /v1/ffl/transfers/{orderId}/status - Documentation Link

Purpose:
Synchronize order status changes from your platform to MasterFFL.

When to call:
Whenever the e-commerce order status changes.

This keeps the Transfer Workflow aligned with the order lifecycle.

Send Shipment Tracking Information

PUT /v1/ffl/transfers/{orderId}/trackingDetails - Documentation Link

Purpose:
Update shipment tracking details for the transfer.

When to call:
After tracking information is generated in your system.

Tracking information may be reflected on the Master FFL Transfer Proof.

Fetch Dealer Summary from License Number

GET /ffl/dealers/details - Documentation Link

Purpose:
Retrieve Receiving Dealer license and address details using FFL License Number.

Common uses:

Populate profile data for saved dealers

Optional Enhancements

Saving a Preferred Dealer

https://masterffl.readme.io/docs/using-the-saved-dealer

Function: verifySavedDealerOrderAcceptance

Purpose:

Validate FFL License status
Confirm willingness and ability
Confirm compatibility with cart ItemTypes

You may pass an orderCharacteristics object to control which checks are applied.

If validation fails:

A detailed error message is returned
Prompt the Buyer to select a new Receiving Dealer

Performing B2B Transfers

Some Buyers are licensed dealers who have opted-out of public transfers but need to receive items themselves.

Implementation approach:

Allow Buyer to enter their FFL License Number during checkout or store this value in their account details.
Validate using verifySavedDealerOrderAcceptance.
When calling Initiate Transfer v2:
- Pass the Buyer’s license in the Buyer object
- Pass the same license via receivingFFL.fflLicenseNumber

This bypasses opt-out checks while still validating license eligibility.

State-Based Restrictions (Ammo and Firearm Parts)

State laws may require final handoff of state regulated items via a Receiving Dealer.

Implementation:

Use category or item mapping to flag state-restricted items.
Detects Buyer shipping state.
Trigger the FFL Checkout Iframe when required.

Custom Implementations