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
20 per hour and
100 per 24 hour period,
unless you request an exception.
Endpoint
POST https://api.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 $10,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 theresponse_url
. Leave this empty if you do not know the buyer's email address or want to send theresponse_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.marketplace_buyer_fee_amount_cents
(Integer) - Optional
The marketplace fees paid by the buyer, in cents. Defaults to automatic calculation.marketplace_seller_fee_amount_cents
(Integer) - Optional
The marketplace fees paid by the seller, in cents. Defaults to automatic calculation.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 Account > Checkout preferences if set. Defaults tobuyer
. 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 Account > Checkout preferences if set. Defaults toseller
. 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 unlessurl
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 ammunitionhandgun_frame
- Handgun lower receiver/framelong_gun
- Long gun (rifle or shotgun)long_gun_ammunition
- Long gun ammunitionlong_gun_receiver
- Long gun lower receiver/framemachine_gun
- Machine gunmagazine
- Magazinesother_non_regulated
- Other (non-regulated uppers, parts, accessories, etc.)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 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 unlessdescription
given
A URL for a webpage with a complete, detailed description of this merchandise. Must be a complete URL, including 'https'.
Deprecation notice:parts_and_accessories
has been replaced byother_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.
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", "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": "Sig Sauer P320 M18", "url": "https://www.gunbroker.com/item/90354651" } ] }
Example Response JSON
{ "amount_cents": 75000, "buyer_email": "buyer@example.com", "created_at": "2023-12-04T00:34:06.126Z", "id": "37715d7f-0742-40dd-9065-147100750db1", "marketplace_buyer_fee_amount_cents": 0, "marketplace_seller_fee_amount_cents": 0, "object": "Invoice", "payment_method_convenience_fee_paid_by": "buyer", "production": false, "response": null, "response_at": null, "response_url": "https://www.guntab.com/invoices/37715d7f-0742-40dd-9065-147100750db1/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": "Sig Sauer P320 M18", "url": "https://www.gunbroker.com/item/90354651" } ] }
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": "2023-12-04T00:34:06.126Z", "id": "37715d7f-0742-40dd-9065-147100750db1", "marketplace_buyer_fee_amount_cents": 0, "marketplace_seller_fee_amount_cents": 0, "object": "Invoice", "payment_method_convenience_fee_paid_by": "buyer", "production": false, "response": null, "response_at": null, "response_url": "https://www.guntab.com/invoices/37715d7f-0742-40dd-9065-147100750db1/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": "Sig Sauer P320 M18", "url": "https://www.gunbroker.com/item/90354651" } ] }
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
url
(String) - Required
The full URL of the endpoint you want GunTab to POST update payloads to.
Response
Example Request JSON
{ "url": "https://www.example.com/guntab_webhooks" }
Example Response JSON
{ "created_at": "2023-12-04T00:34:06.133Z", "id": "5c536119-8949-4f92-9bcc-19c3daf52870", "production": false, "signing_secret_key": "ssk_5098c81d27a3580e0f75e3846b39277a", "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": "2023-12-04T00:34:06.133Z", "id": "5c536119-8949-4f92-9bcc-19c3daf52870", "production": false, "signing_secret_key": "ssk_5098c81d27a3580e0f75e3846b39277a", "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
{ }
Support
Need help or have a question? Please see our Help Center, or you can contact support.