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

This guide covers the following topics:

• Authentication
• Errors
• Invoices (also known as "payment requests")
• Webhooks

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:

• Verify ownership of your FFL (if applicable)
• Provide a copy of your driver's license

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.

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://www.guntab.com/v1/invoices

Parameters

• amount_cents (Integer) - Required
  The total agreed sale price for the merchandise, in cents (excluding shipping amount and sales tax). No minimum. No maximum, however amounts over $5,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.
• checkout_uuid (String) - Optional
  The seller's Checkout UUID value, copy-pasted from the Checkout documentation. Provide this if you are creating this Invoice on behalf of a seller. Leave this empty if you are the seller.
• payment_method_convenience_fee_paid_by (String) - Optional
  The side responsible for paying any payment method convenience fee that may apply. If not given, GunTab will use the value from your Checkout preferences if set. Defaults to buyer. Choose from:
  • buyer
  • seller
• sales_tax_amount_cents (Integer) - Optional
  The sales tax paid by the buyer, in cents. If not given, GunTab will calculate it automatically and assume zero if possible.
• 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.
• seller_redirect_url (String) - Optional
  The URL you want buyers to be redirected to after completing the GunTab checkout flow. This is usually a thank-you page in your shopping cart or ecommerce store software. Must be a complete URL, including 'https'.
• service_fee_paid_by (String) - Optional
  The side responsible for paying the GunTab service fee. If not given, GunTab will use the value from your Checkout preferences if set. Defaults to seller. Choose from:
  • buyer
  • seller
  • split
• shipping_amount_cents (Integer) - Required
  The cost of the shipping to the buyer, in cents. No minimum. Maximum of 40000. 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 merchandise, in cents.
  • description (String) - Required unless url given
    A complete, detailed description of this merchandise. 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 this merchandise 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:
    • ammunition_flammables - Ammunition flammables (powder, primers, etc)
    • antique_gun - Antique gun (fixed ammo design in manufacture before 1899)
    • aow - Any other weapon (AOW)
    • curio_relic - Curio or relic (manufactured 50+ years ago)
    • 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
    • other_non_regulated - Other (non-regulated parts, accessories, etc.)
    • short_barreled_long_gun - Short-barreled rifle (SBR) or shotgun (SBS)
    • suppressor - Silencer/Suppressor
  Deprecation notice: parts_and_accessories has been replaced by other_non_regulated. (Deprecated values will be automatically converted.)
  Have any feedback about listing_type_id options? We would love to hear it. Please email us at support@guntab.com with your thoughts/suggestions.
  • quantity (Integer) - Optional
    The number of units being purchased. Defaults to 1.
  • serial_number (String) - Optional
    The merchandise serial number. Most often provided when the merchandise is an antique or collectible where the serial number influences the value of the item.
  • title (String) - Required
    A descriptive title for this merchandise, 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 this merchandise. Must be a complete URL, including 'https'.

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.

{
  "amount_cents": "75000",
  "buyer_email": "buyer@example.com",
  "payment_method_convenience_fee_paid_by": "buyer",
  "sales_tax_amount_cents": "6375",
  "seller_order_id": "555555",
  "seller_redirect_url": "https://www.example.com/thanks-for-ordering",
  "service_fee_paid_by": "seller",
  "shipping_amount_cents": "3500",
  "listings": [
    {
      "listing_type_id": "handgun",
      "quantity": 1,
      "title": "Colt Python 357 Magnum",
      "url": "https://www.gunbroker.com/item/490721365"
    }
  ]
}

{
  "amount_cents": 75000,
  "buyer_email": "buyer@example.com",
  "created_at": "2023-03-24T19:33:28.488Z",
  "id": "8b0c9b40-ad45-439a-b3b8-dd8cf35bf8a7",
  "object": "Invoice",
  "payment_method_convenience_fee_paid_by": "buyer",
  "production": false,
  "response": null,
  "response_at": null,
  "response_url": "http://www.guntab.com/invoices/8b0c9b40-ad45-439a-b3b8-dd8cf35bf8a7/responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_order_id": "555555",
  "seller_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",
      "quantity": 1,
      "serial_number": null,
      "title": "Colt Python 357 Magnum",
      "url": "https://www.gunbroker.com/item/490721365"
    }
  ]
}

Read Invoice

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

Endpoint

GET https://www.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.

{
}

{
  "amount_cents": 75000,
  "buyer_email": "buyer@example.com",
  "created_at": "2023-03-24T19:33:28.488Z",
  "id": "8b0c9b40-ad45-439a-b3b8-dd8cf35bf8a7",
  "object": "Invoice",
  "payment_method_convenience_fee_paid_by": "buyer",
  "production": false,
  "response": null,
  "response_at": null,
  "response_url": "http://www.guntab.com/invoices/8b0c9b40-ad45-439a-b3b8-dd8cf35bf8a7/responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_order_id": "555555",
  "seller_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",
      "quantity": 1,
      "serial_number": null,
      "title": "Colt Python 357 Magnum",
      "url": "https://www.gunbroker.com/item/490721365"
    }
  ]
}

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://www.guntab.com/v1/webhooks

Parameters

• url (String) - Required
  The full URL of the endpoint you want GunTab to POST update payloads to.

Response

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

{
  "created_at": "2023-03-24T19:33:28.496Z",
  "id": "250737a0-e87a-45fd-933f-d88223382091",
  "production": false,
  "signing_secret_key": "ssk_d0d46a5db4be69b5b0a2a849435ccc41",
  "url": "https://www.example.com/guntab_webhooks"
}

Read Webhook

Get the details of an existing Webhook.

Endpoint

GET https://www.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.

{
}

{
  "created_at": "2023-03-24T19:33:28.496Z",
  "id": "250737a0-e87a-45fd-933f-d88223382091",
  "production": false,
  "signing_secret_key": "ssk_d0d46a5db4be69b5b0a2a849435ccc41",
  "url": "https://www.example.com/guntab_webhooks"
}

Delete Webhook

Delete an existing Webhook.

Endpoint

DELETE https://www.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.

{
}

{
}

Support

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