REST API

Do you have an online marketplace or a retail website? Do you want to empower your customers with safe and convenient payments? Integrate with GunTab through our API.

Overview

The GunTab API is a RESTful JSON API. That means it is designed to:

This guide covers the following topics:

Authentication

API authentication is token-based.

API tokens can only be generated by users who have verified their email.

After your email has been verified, create a token from your GunTab account. The token value should be used to build your "Authorization" header with a "Token" type, like this:

Authorization: Token 55555555-5555-5555-5555-555555555555

API token types

By default, API tokens are non-production. This means they will return dummy responses without actually taking any action. These dummy responses are formatted exactly like production responses. Please use these non-production API keys for all development and testing pursposes. For live production purposes, please generate a production API key.

Warning: Don't forget to use a production API key in your production environment. If GunTab is giving you success responses, but your requests don't otherwise seem successful, it is because you are using a non-production API key.

Errors

All errors have the same format: 

{
  "errors": [
    "Your authentication token is invalid."
  ]
}

Invoices

You can use the API to create and read Invoices. These are also known as "payment requests". An Invoice is how a seller initiates a GunTab transaction to get paid. If a buyer accepts an Invoice, GunTab will help the buyer select a local FFL and make payment.

Create Invoice

Create a new Invoice. Give the buyer_email if you want GunTab to send an email to the buyer, or leave it empty and send the response_url to the buyer your own way. Maximum of 20 per hour and 100 per 24 hour period, unless you request an exception.

Endpoint

POST https://api.guntab.com/v1/invoices

Parameters

Response

After creating an Invoice with a buyer_email value, you can ask the buyer to check their email for a payment request from GunTab.

After creating an Invoice without a buyer_email value, you should redirect the buyer to the response_url that appears in the response payload.

Example Request JSON

{
  "delivery_to": "buyer@example.com",
  "manual_sales_tax_amount_cents": "6375",
  "merchandise_amount_cents": "75000",
  "payment_method_convenience_fee_paid_by": "buyer",
  "seller_order_id": "555555",
  "redirect_url": "https://www.example.com/thanks-for-ordering",
  "service_fee_paid_by": "seller",
  "shipping_amount_cents": "3500",
  "type": "Invoice",
  "listings": [
    {
      "listing_type_id": "handgun",
      "quantity": 1,
      "title": "Heckler & Koch HK45C",
      "url": "https://www.gunbroker.com/item/27932389"
    }
  ]
}

Example Response JSON

{
  "amount_cents": 75000,
  "buyer_email": "buyer@example.com",
  "created_at": "2025-02-05T04:38:37.143Z",
  "id": "bc516559-f1ff-4598-b8f9-12a79fe1bcec",
  "manual_sales_tax_amount_cents": 6375,
  "marketplace_buyer_fee_amount_cents": 0,
  "marketplace_seller_fee_amount_cents": 0,
  "merchandise_amount_cents": 75000,
  "object": "Invoice",
  "payment_method_convenience_fee_paid_by": "buyer",
  "production": false,
  "receiving_address": null,
  "receiving_ffl_license_number": null,
  "response": null,
  "response_at": null,
  "response_url": "https://www.guntab.com/purchases/bc516559-f1ff-4598-b8f9-12a79fe1bcec/counterparty_responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_email": "seller@example.com",
  "seller_order_id": "555555",
  "redirect_url": "https://www.example.com/thanks-for-ordering",
  "service_fee_paid_by": "seller",
  "shipping_amount_cents": 3500,
  "listings": [
    {
      "amount_cents": null,
      "description": null,
      "listing_type_id": "handgun",
      "external_id": null,
      "quantity": 1,
      "serial_number": null,
      "title": "Heckler & Koch HK45C",
      "url": "https://www.gunbroker.com/item/27932389"
    }
  ]
}

Read Invoice

Get the details of an existing Invoice, including the response_url that can be shared with the buyer.

Endpoint

GET https://api.guntab.com/v1/invoices/:id

Response

When using a non-production API token, this endpoint will return dummy data. The production key in the response indicates if you are using a production API token.

Example Request JSON

{}

Example Response JSON

{
  "amount_cents": 75000,
  "buyer_email": "buyer@example.com",
  "created_at": "2025-02-05T04:38:37.143Z",
  "id": "bc516559-f1ff-4598-b8f9-12a79fe1bcec",
  "manual_sales_tax_amount_cents": 6375,
  "marketplace_buyer_fee_amount_cents": 0,
  "marketplace_seller_fee_amount_cents": 0,
  "merchandise_amount_cents": 75000,
  "object": "Invoice",
  "payment_method_convenience_fee_paid_by": "buyer",
  "production": false,
  "receiving_address": null,
  "receiving_ffl_license_number": null,
  "response": null,
  "response_at": null,
  "response_url": "https://www.guntab.com/purchases/bc516559-f1ff-4598-b8f9-12a79fe1bcec/counterparty_responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_email": "seller@example.com",
  "seller_order_id": "555555",
  "redirect_url": "https://www.example.com/thanks-for-ordering",
  "service_fee_paid_by": "seller",
  "shipping_amount_cents": 3500,
  "listings": [
    {
      "amount_cents": null,
      "description": null,
      "listing_type_id": "handgun",
      "external_id": null,
      "quantity": 1,
      "serial_number": null,
      "title": "Heckler & Koch HK45C",
      "url": "https://www.gunbroker.com/item/27932389"
    }
  ]
}

Webhooks

You can use the API to create, read, and delete Webhooks. GunTab will send transaction updates to each of your Webhooks, for each of your transactions. You can use these updates to keep your own systems updated, especially your inventory and accounting systems.

Create Webhook

Create a new Webhook. GunTab will begin sending transaction updates immediately.

Endpoint

POST https://api.guntab.com/v1/webhooks

Parameters

Response

Example Request JSON

{
  "url": "https://www.example.com/guntab_webhooks"
}

Example Response JSON

{
  "created_at": "2025-02-05T04:38:37.178Z",
  "id": "c7bb137d-54fc-4c34-8ac7-a748edda78d0",
  "production": false,
  "signing_secret_key": "ssk_a0adf422ffdd5806d8389576af1c23d6",
  "url": "https://www.example.com/guntab_webhooks"
}

Read Webhook

Get the details of an existing Webhook.

Endpoint

GET https://api.guntab.com/v1/webhooks/:id

Response

When using a non-production API token, this endpoint will return dummy data. The production key in the response indicates if you are using a production API token.

Example Request JSON

{}

Example Response JSON

{
  "created_at": "2025-02-05T04:38:37.178Z",
  "id": "c7bb137d-54fc-4c34-8ac7-a748edda78d0",
  "production": false,
  "signing_secret_key": "ssk_a0adf422ffdd5806d8389576af1c23d6",
  "url": "https://www.example.com/guntab_webhooks"
}

Delete Webhook

Delete an existing Webhook.

Endpoint

DELETE https://api.guntab.com/v1/webhooks/:id

Response

When using a non-production API token, this endpoint will have no effect. Returns a status of 200 when successful, without any JSON payload.

Example Request JSON

{}

Example Response JSON

{}

FFL verifications

You can use the API to call an FFL and provide your verification code. This is useful for marketplaces and other services that want assurance their users' FFL claims are authentic.

Warning: This is an alpha-stage endpoint which may change in the future.
For marketplace users only.

Call FFL to provide verification code

Trigger an automated phone call to phone number the FFL has on file with the BATF, to provide your verification code. If the FFL does not answer, we will leave a voicemail. After this, you should ask the FFL to input your verification code so you can confirm it matches.

Endpoint

POST https://api.guntab.com/v1/ffls/X-XX-XXX-XX--XXXXX/claim_verification_code_calls
(where X's represent the FFL license number)

Parameters

Response

Either 201 for success or 422 for failure.

Example Request JSON

{
  "verification_code": "55555"
}

Example Response JSON

{
  "claim_verification_code": "55555",
  "firearm_license_id": "7282f68a-2ee1-4a27-a067-04fc0eb9c707",
  "firearm_license_number": "X-XX-XXX-XX--XXXXX",
  "production": false
}

Users

You can use the API to get information about a user based on their email. The intent is to help you determine if a user has a GunTab account, and whether it is in good standing.

Warning: This is an alpha-stage endpoint which may change in the future.
For marketplace users only.

Read User

Get the details of an existing User by providing a URL-encoded email address. If no User is associated with the email, an error will be returned.

Endpoint

GET https://api.guntab.com/v1/users/EMAIL
(where EMAIL represents a URL-encoded email address)

Response

Either 200 for success or 422 for failure.

Example Request JSON

{}

Example Response JSON

{
  "active": true,
  "email": "seller@example.com",
  "object": "User",
  "payment_method_convenience_fee_paid_by_default": "buyer",
  "payment_method_convenience_fee_percent": 3.0,
  "production": false,
  "service_fee_paid_by_default": "seller",
  "service_fee_percent": 2.9
}

Support

Need help or have a question? Please see our Help Center, or you can contact support.