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

{
  "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/984564391"
    }
  ]
}

Example Response JSON

{
  "amount_cents": 75000,
  "buyer_email": "buyer@example.com",
  "created_at": "2024-11-21T09:08:48.266Z",
  "id": "dd8c0851-aae1-45fc-82b2-9be4eb6f5dab",
  "marketplace_buyer_fee_amount_cents": 0,
  "marketplace_seller_fee_amount_cents": 0,
  "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/invoices/dd8c0851-aae1-45fc-82b2-9be4eb6f5dab/responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_email": "seller@example.com",
  "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/984564391"
    }
  ]
}

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": "2024-11-21T09:08:48.266Z",
  "id": "dd8c0851-aae1-45fc-82b2-9be4eb6f5dab",
  "marketplace_buyer_fee_amount_cents": 0,
  "marketplace_seller_fee_amount_cents": 0,
  "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/invoices/dd8c0851-aae1-45fc-82b2-9be4eb6f5dab/responses/new",
  "sales_tax_amount_cents": 6375,
  "seller_email": "seller@example.com",
  "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/984564391"
    }
  ]
}

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": "2024-11-21T09:08:48.277Z",
  "id": "6750a089-d474-4634-908b-6260aaf898eb",
  "production": false,
  "signing_secret_key": "ssk_a3ffe892c1c7fb5c193e3f4bcbda6844",
  "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": "2024-11-21T09:08:48.277Z",
  "id": "6750a089-d474-4634-908b-6260aaf898eb",
  "production": false,
  "signing_secret_key": "ssk_a3ffe892c1c7fb5c193e3f4bcbda6844",
  "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.