? Question

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:

  • follow standard RESTful conventions
  • accept JSON-formatted request payloads
  • return JSON-formatted response payloads

Authentication

API authentication is token-based.

API tokens can only be generated by users who have verified their identity. You can verify your identity in either of these ways:

After your identity has been verified, please 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 100 per 24 hour period.

Endpoint

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

Parameters

  • amount_cents (Integer) - Required
    The total agreed price for the items, in cents (excluding shipping amount and sales tax). No minimum. No maximum, however amounts over $3,000 must be paid by wire transfer.
  • buyer_email (String) - Optional
    The buyer's email address. Provide this if you want GunTab to send an email to the buyer with the response_url. Leave this empty if you do not know the buyer's email address or want to send the response_url to the buyer your own way.
  • sales_tax_amount_cents (Integer) - Optional
    The sales tax paid by the buyer, in cents. If this is not given, GunTab will calculate it based on your policy.
  • seller_order_id (String) - Optional
    The order ID you want to be associated with this Invoice and the resulting transaction. This is usually generated by your shopping cart or ecommerce store software. This will be included in GunTab webhook payloads so you can easily find the order. Maximum of 100 characters.
  • shipping_amount_cents (Integer) - Required
    The cost of the shipping to the buyer, in cents. No minimum. Maximum of 20000. Zero indicates that shipping is free to the buyer.
  • listings (JSON array containing JSON objects)
    • amount_cents (Integer) - Optional
      The price per unit for this item, in cents.
    • description (String) - Required unless url given
      A complete, detailed description of the item. Minimum of 50 characters. Maximum of 10000 characters. This is unnecessary if you provide a 'url' to a webpage that includes a description.
    • listing_type_id (String) - Optional
      A code that describes the item's category. We use this to provide type-specific guidance to the buyer and seller. If you do not provide it, we will ask the buyer to set it. Choose from:
      • aow - Any other weapon (AOW)
      • handgun - Handgun (pistol or revolver)
      • handgun_ammunition - Handgun ammunition
      • handgun_frame - Handgun frame/lower/receiver
      • long_gun - Long gun (rifle or shotgun)
      • long_gun_ammunition - Long gun ammunition
      • long_gun_receiver - Long gun frame/lower/receiver
      • machine_gun - Machine gun
      • magazine - Magazines
      • parts_and_accessories - Parts and accessories
      • short_barreled_long_gun - Short-barreled rifle (SBR) or shotgun (SBS)
      • suppressor - Silencer/Suppressor
    • quantity (Integer) - Optional
      The number of units being purchased. Defaults to 1.
    • serial_number (String) - Optional
      The item's serial number. Most often provided when the item is an antique or collectible where the serial number influences the value of the item.
    • title (String) - Required
      A descriptive title for the item, like what would appear at the top of a webpage.
    • url (String) - Required unless description given
      A URL for a webpage with a complete, detailed description of the item. Must be a complete URL, including 'http'.

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

{
  "amount_cents": "75000",
  "buyer_email": "buyer@example.com",
  "sales_tax_amount_cents": "6375",
  "seller_order_id": "555555",
  "shipping_amount_cents": "3500",
  "listings": [
    {
      "listing_type_id": "handgun",
      "quantity": 1,
      "title": "Colt Python 357 Magnum",
      "url": "https://www.gunbroker.com/item/350556560"
    }
  ]
}

Example Response JSON

{
  "amount_cents": 75000,
  "buyer_email": "buyer@example.com",
  "created_at": "2021-09-20T17:40:35.305Z",
  "id": "aea11e86-8fd2-4d07-b90c-99485055f298",
  "object": "Invoice",
  "production": false,
  "response": null,
  "response_at": null,
  "response_url": "http://example.org/invoices/aea11e86-8fd2-4d07-b90c-99485055f298/responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_order_id": "555555",
  "shipping_amount_cents": 3500,
  "listings": [
    {
      "amount_cents": null,
      "description": null,
      "listing_type_id": "handgun",
      "quantity": 1,
      "serial_number": null,
      "title": "Colt Python 357 Magnum",
      "url": "https://www.gunbroker.com/item/350556560"
    }
  ]
}

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/55555555-5555-5555-5555-555555555555

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": "2021-09-20T17:40:35.305Z",
  "id": "aea11e86-8fd2-4d07-b90c-99485055f298",
  "object": "Invoice",
  "production": false,
  "response": null,
  "response_at": null,
  "response_url": "http://example.org/invoices/aea11e86-8fd2-4d07-b90c-99485055f298/responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_order_id": "555555",
  "shipping_amount_cents": 3500,
  "listings": [
    {
      "amount_cents": null,
      "description": null,
      "listing_type_id": "handgun",
      "quantity": 1,
      "serial_number": null,
      "title": "Colt Python 357 Magnum",
      "url": "https://www.gunbroker.com/item/350556560"
    }
  ]
}

Support

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