# Composing Requests

# Base Urls

Sandbox

The Sandbox environment is provided for testing. Transaction responses are simulated and do not leave the platform for processing. No billing related items occur within this environment.

Sandbox url:

Production

The Production environment should be used for all LIVE transactional processing.

Production url:

# Versioning

The platform's semi-RESTful API is fully backwards compatible and versioning is not necessary. Changes and feature updates are sent out via the platform prior to release.

Current version: 1.5.1

# Headers

The following headers should be included with your requests:

# Authorization

Calls to the API must include an Authorization header with the request. Either a JWT (JSON Web Token) or an API Key can be used as the value of this header, like so:

Authorization: Bearer { JWTToken }

Authorization: { API Key }

# Api Keys

API keys are used to authenticate your requests to the API. You can create and manage your API keys in the control panel. API keys are tied to a user account.

Their are two types of API keys:

  • Public API keys (ex: pub_***) - used for making requests to the API from the client side (ex. Tokenizer and Cart Sessions)
  • Private API keys (ex: api_***) - used for making requests to the API from the server side (ex. Transaction Processing)

DANGER

Private API keys should never be exposed to the public. Please do not include them in client side code, emails or support ticket request.

DANGER

Use of Public API keys to make requests to the API from the server side will result in an unauthorzed response.

# Content-Type

Content-Type should typically be set to application/json, unless you need to send your request body in a different format. All API responses will be in JSON format.

# Users

# Create User

Create a new user account.

Request Method: POST

URL Endpoint: /api/user

    # Get User By ID

    Retrieve the properties of a specific user.

    Request Method: GET

    URL Endpoint: /api/user/{ user id }

      # Get Authenticated User

      Retrieve the properties of the currently authenticated user. This is intended as a helper function, it is recommended to get a specific user by providing the ID if possible.

      Request Method: GET

      URL Endpoint: /api/user

        # Get All Users

        Retrieve the properties of all users for the gateway or partner account associated with the API Key or JWT token provided in the Authorization header.

        Request Method: GET

        URL Endpoint: /api/users

          # Update User

          Edit the properties of an existing user account.

          Request Method: POST

          URL Endpoint: /api/user/{ user id }

            # Delete User

            Delete a specific user.

            Request Method: DELETE

            URL Endpoint: /api/user/{ user id }

              # Change Password

              Change a user's password. Must provide an API Key or JWT token associated with the user as the Authorization header value.

              Request Method: POST

              URL Endpoint: /api/user/change-password

                # Create API Key

                Create an API key for a user.

                Request Method: POST

                URL Endpoint: /api/user/apikey

                  # Get All API Keys

                  Retrieve all API keys for the gateway or partner account associated with the API Key or JWT token provided in the Authorization header.

                  Request Method: GET

                  URL Endpoint: /api/user/apikeys

                    # Delete API Key

                    Delete a specific API key.

                    Request Method: DELETE

                    URL Endpoint: /api/user/apikey/{ api key }

                      # Transactions

                      # Process a Transaction

                      Process a transaction through the gateway.

                      TIP

                      If you do not have a default processor set, you must include the processor_id property in the request body or the transaction will fail.

                      TIP

                      Base Amount - If you are using base_amount it will be the base amount of the transaction. The surcharge and other related fees(if applicable) will be calculated and added unless those values are specifically passed in.

                      Amount - This will be the final amount you want charged and will include all surcharges and related fees(if applicable).

                      Request Method: POST

                      URL Endpoint: /api/transaction

                        # Process a Transaction - Code Samples

                          # CIT - MIT

                          TIP

                          When processing transactions the following variables are available for including CIT/MIT variables to the processors.

                          Name Required Description
                          card_on_file_indicator Optional
                          initiated_by Required Indicates who initiated the transaction.
                          initial_transaction_id Optional Optional if using our tokenization
                          stored_credential_indicator Optional Indicates if a stored payment was used or not
                          billing_method Optional Defaults to "straight", but if this is a recurring transaction, passing "recurring" will set recurring indicators on the transaction

                          # Fee Calculation


                          TIP

                          Using this endpoint will calculate any applicable fees that should be applied to the transaction. This includes Surcharge, Cash Discount Fees and Payment Adjustment, if applicable.

                          Request Method: POST

                          URL Endpoint: /api/lookup/fees

                          Name Type Required Description
                          type string yes type of request, "integrations"
                          state string no billing address state
                          bin string yes 6 - 19 digits of a card
                          payment_method string yes card
                          base_amount uint yes amount in lowest form of currency. $1.00 = 100
                          ➜  ~ curl -H 'Authorization: API_KEY' -H "Content-Type: application/json" -X POST -d '{
                                  "type": "integrations",
                                  "type_id":"",
                                  "state": "IL",
                                  "bin": "517246700",
                                  "payment_method": "card",
                                  "base_amount": 1000
                          }' { url goes here }/api/api/lookup/fees
                          
                          {
                            "status": "success",
                            "msg": "success",
                            "data": {
                              "service_fee": 0,
                              "payment_adjustment": {
                                "value": 0,
                                "type": ""
                              },
                              "requested_amount": 1350,
                              "discount_amount": null,
                              "surcharge": 350
                            }
                          }
                          

                          # Amount calculation


                          Request Method: POST

                          URL Endpoint: /api/calculate/amounts

                          Name Type Required Default Description
                          processor_id string true
                          subtotal uint true null
                          amount uint if line_items or products not present null
                          currency string true
                          payment_method string true Can be 'card' or 'ach'
                          transaction_type string true Can be 'verification', 'auth', 'sale', 'void', 'refund', 'credit'
                          products array if amount or line_items not present null
                          products[].id string true
                          products[].name string true
                          products[].description string false
                          products[].price string true
                          products[].local_tax string false
                          products[].national_tax string false
                          products[].fixed_amount bool false false
                          products[].fixed_qty bool false false
                          products[].unit_of_measure string false null
                          line_items array if amount or products not present null
                          line_items[].id string true
                          line_items[].status string true Can be 'paid', 'pending', 'rejected'
                          line_items[].type string true Can be 'flat' or 'percentage'
                          line_items[].name string true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          line_items[].description string false false If true, the calculated amount will be added to the total amount
                          line_items[].unit_price int true
                          line_items[].quantity float64 true
                          line_items[].quantity_shipped float64 false
                          line_items[].product_code string false
                          line_items[].commodity_code string false
                          line_items[].unit_of_measure string false
                          line_items[].alternate_tax_identifier string false
                          line_items[].taxable bool false false
                          line_items[].local_tax_rate string false Format is 10.25
                          line_items[].national_tax_rate string false Format is 10.25
                          line_items[].tax_rate string false Format is 10.25
                          line_items[].discount_amount uint false
                          line_items[].freight_amount uint false
                          line_items[].discount_rate string false
                          processor_payment_adjustment object false null
                          processor_payment_adjustment.type string true Can be 'flat' or 'percentage'
                          processor_payment_adjustment.value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          processor_payment_adjustment.include bool false false If true, the calculated amount will be added to the total amount
                          shipping_amount object false null
                          shipping_amount.type string true Can be 'flat' or 'percentage'
                          shipping_amount.value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          shipping_amount.include bool false false If true, the calculated amount will be added to the total amount
                          addon_amount array false null
                          addon_amount[].type string true Can be 'flat' or 'percentage'
                          addon_amount[].value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          addon_amount[].include bool false false If true, the calculated amount will be added to the total amount
                          discount_amount array false null
                          discount_amount[].type string true Can be 'flat' or 'percentage'
                          discount_amount[].value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          discount_amount[].include bool false false If true, the calculated amount will be added to the total amount
                          duty_amount object false null
                          duty_amount.type string true Can be 'flat' or 'percentage'
                          duty_amount.value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          duty_amount.include bool false false If true, the calculated amount will be added to the total amount
                          tip_amount object false null
                          tip_amount.type string true Can be 'flat' or 'percentage'
                          tip_amount.value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          tip_amount.include bool false false If true, the calculated amount will be added to the total amount
                          additional_amounts array false null
                          additional_amounts[].type string true Can be 'flat' or 'percentage'
                          additional_amounts[].value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          additional_amounts[].include bool false false If true, the calculated amount will be added to the total amount
                          tax_amount object false null
                          tax_amount.type string true Can be 'flat' or 'percentage'
                          tax_amount.value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          tax_amount.include bool false false If true, the calculated amount will be added to the total amount
                          national_tax_amount object false null
                          national_tax_amount.type string true Can be 'flat' or 'percentage'
                          national_tax_amount.value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          national_tax_amount.include bool false false If true, the calculated amount will be added to the total amount
                          local_tax_amount object false null
                          local_tax_amount.type string true Can be 'flat' or 'percentage'
                          local_tax_amount.value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          local_tax_amount.include bool false false If true, the calculated amount will be added to the total amount
                          service_fee object false null
                          service_fee.type string true Can be 'flat' or 'percentage'
                          service_fee.value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          service_fee.include bool false false If true, the calculated amount will be added to the total amount
                          surcharge object false null
                          surcharge.type string true Can be 'flat' or 'percentage'
                          surcharge.value uint true If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000)
                          surcharge.include bool false false If true, the calculated amount will be added to the total amount
                          cc_bin string if surcharge allowed null
                          country string if surcharge allowed null
                          state string if surcharge allowed null
                          flags object false
                          flags.skip_cash_discount bool false false If true, skips the cash discount calculation
                          flags.skip_surcharge bool false false If true, skips the cash surcharge calculation
                          flags.skip_service_fee bool false false If true, skips the cash service fee calculation
                          flags.skip_consumer_choice bool false false If true, skips the cash consumer choice calculation
                          flags.include_default_tax_to_total bool false null If true, and tax has not been overridden, the merchant's default tax amount will be added to the total amount
                          flags.tax_exempt bool false null If true, sets the national, local and tax amount fields to 0
                          flags.processor_surcharge_fallback bool false false If true, processor's surcharge fallback will be available
                          flags.add_tax_to_total bool false null If true, the tax will be added to the total amount
                          source string false

                          Workflow:

                          1. Call the Amount calculation endpoint with the properly filled request
                          2. Take the response of the Amount calculation and place it into the Transaction Request into the amounts field and fill the other fields of the request
                          3. Submit the transaction with the pre-calculated amounts
                          ➜  ~ curl -H 'Authorization: API_KEY' -H "Content-Type: application/json" -X POST -d '{
                              "processor_id": "<processor id>",
                              "amount" : 1000,
                              "subtotal" : 1000,
                              "currency": "USD",
                              "payment_method": "card",
                              "transaction_type": "sale"
                          }' { url goes here }/api/calculate/amounts
                          
                          {
                            "status": "success",
                            "msg": "success",
                            "data": {
                              "line_items": null,
                              "shipping_amount": null,
                              "discount_amount": null,
                              "freight_amount": null,
                              "addon_amount": null,
                              "duty_amount": null,
                              "tip_amount": null,
                              "additional_amounts": null,
                              "tax_amount": 180,
                              "national_tax_amount": null,
                              "local_tax_amount": null,
                              "service_fee": 350,
                              "surcharge": null,
                              "processor_id": "<processor id>",
                              "payment_method": "card",
                              "included_amounts": {
                                "shipping_amount": null,
                                "discount_amount": null,
                                "duty_amount": null,
                                "tip_amount": null,
                                "tax_amount": 180,
                                "national_tax_amount": null,
                                "local_tax_amount": null,
                                "service_fee": 350,
                                "surcharge": null
                              },
                              "subtotal": 1000,
                              "amount": 1000,
                              "additional_total": 0,
                              "total": 1530,
                              "features": {
                                "surcharge": false,
                                "cash_discount": false,
                                "dual_pricing": false,
                                "dual_pricing_v2": false
                              },
                              "display": {
                                "subtotal": {
                                  "value": 1000,
                                  "display": true
                                },
                                "amount": {
                                  "value": 1000,
                                  "display": true
                                },
                                "shipping": {
                                  "value": 0,
                                  "display": false
                                },
                                "freight": {
                                  "value": 0,
                                  "display": false
                                },
                                "duty": {
                                  "value": 0,
                                  "display": false
                                },
                                "discount": {
                                  "value": 0,
                                  "display": false
                                },
                                "service_fee": {
                                  "value": 350,
                                  "display": true
                                },
                                "surcharge": {
                                  "value": 0,
                                  "display": false
                                },
                                "tax": {
                                  "value": 180,
                                  "display": true
                                },
                                "national_tax": {
                                  "value": 0,
                                  "display": false
                                },
                                "local_tax": {
                                  "value": 0,
                                  "display": false
                                },
                                "tip": {
                                  "value": 0,
                                  "display": false
                                },
                                "total": {
                                  "value": 1530,
                                  "display": true
                                },
                                "consumer_choice": {
                                  "card": 0,
                                  "ach": 0,
                                  "display": false
                                }
                              },
                              "disclaimer": {
                                "text": "",
                                "html": "",
                                "display": false
                              }
                            }
                          }
                          

                          # Response Codes


                          TIP

                          Response Codes are grouped as follows: 100 thru 199 are Approvals and Partial Approvals. 200 thru 299 are Declined via the processor. 300 thru 399 are Gateway Declines. 400 thru 499 are processor rejection errors.



                            # Address Verification Response Codes (AVS)


                            AVS Response Code Definition Code Applies to Card Brands
                            0 AVS Not Available Domestic + International V, MC, AX, D, PP, JCB
                            A Address match only Domestic + International V, AX, D,PP, JCB
                            B Address matches, ZIP not verified Domestic + International V
                            C Incompatible format Domestic + International V
                            D Exact match International V
                            F Exact match, UK-issued cards Domestic + International V
                            G Non-U.S. Issuer does not participate International V
                            I Not verified International V, D, PP, JCB
                            M Exact match International V
                            N No address or ZIP match Domestic + International V, MC, AX, D, PP, JCB
                            P Postal Code match Domestic + International V
                            R Issuer system unavailable Domestic V, MC, AX, D, PP, JCB
                            S Service not supported Domestic MC, AX, D, PP, JCB
                            U Address unavailable Domestic V, MC, AX, D, PP, JCB
                            W 9-character numeric ZIP match only Domestic + International (MC) MC, D, PP, JCB
                            X Exact match, 9-character numeric ZIP Domestic + International (MC) MC, D, PP, JCB
                            Y Exact match, 5-character numeric ZIP Domestic V, MC, AX, D, PP, JCB
                            Z 5-character ZIP match only Domestic + International (V) V, MC, AX, D, PP, JCB
                            L Partial match, Name and billing postal code match For AMEX cards only AX
                            1 Cardholder name and ZIP match Domestic AX
                            2 Cardholder name, address and ZIP match Domestic AX
                            3 Cardholder name and address match Domestic AX
                            4 Cardholder name matches Domestic AX
                            5 Cardholder name incorrect, ZIP matches Domestic AX
                            6 Cardholder name incorrect, address and zip match Domestic AX
                            7 Cardholder name incorrect, address matches Domestic AX
                            8 Cardholder name, address, and ZIP do not match Domestic AX

                            # Get Transaction By ID

                            Retrieve details for a specific transaction.

                            Request Method: GET

                            URL Endpoint: /api/transaction/{ transaction ID }

                              # Search Transactions

                              Retrieve details for all transactions that match provided search criteria.

                              Request Method: POST

                              URL Endpoint: /api/transaction/search

                                # Capture

                                Capture funds for a specified transaction that has already been authorized.

                                Request Method: POST

                                URL Endpoint: /api/transaction/{ transaction ID }/capture

                                  # Void / Auth Reversal

                                  Void a transaction that is pending settlement. Where applicable, a void will be processed as an auth reversal.

                                  Request Method: POST

                                  URL Endpoint: /api/transaction/{ transaction ID }/void

                                    # Refund

                                    Process a refund for a transaction that has already been settled. Multiple partial refunds can be processed, but the total amount of all refunds cannot exceed the previously settled amount.

                                    Request Method: POST

                                    URL Endpoint: /api/transaction/{ transaction ID }/refund

                                      # Settlement Batches

                                      # Search Settlement Batches

                                      Retrieve details for all settlement batches that match provided search criteria.

                                      Request Method: POST

                                      URL Endpoint: /api/settlement/batch/search

                                        # Upload Batch File

                                        Upload a CSV file for batch processing.

                                        TIP

                                        CSV File Format

                                        The input file for the upload endpoint should contain records to process in the following format (example below):

                                        • First row should be a header using the fields below, fields can be in any order and not all fields are required.
                                        • Each field should be wrapped in quotes and should not contain any quotes
                                        • Each field should be seperated with a comma
                                        • Each row should be terminated with a newline \n character.

                                        Request Method: POST

                                        URL Endpoint: /api/filebatch

                                          # Get Batch Status

                                          Get the current status of a specified settlement batch.

                                          Request Method: GET

                                          URL Endpoint: /api/filebatch/{ batch id }

                                            # Download Batch File

                                            Returns a CSV text response for the specified batch.

                                            Request Method: GET

                                            URL Endpoint: /api/filebatch/{ batch id }/download

                                              # Recurring

                                              # Create Add-On

                                              Create a new recurring plan add-on. Add-ons are used to adjust a recurring charge amount, either by a set amount or a percentage of the subscription amount.

                                              Request Method: POST

                                              URL Endpoint: /api/recurring/addon

                                                :::

                                                # Get Add-On By ID

                                                Retrieve details for the specified add-on.

                                                Request Method: GET

                                                URL Endpoint: /api/recurring/addon/{ add-on id }

                                                  # Get All Add-Ons

                                                  Retrieve details for all add-ons accosciated with the gateway account.

                                                  Request Method: GET

                                                  URL Endpoint: /api/recurring/addons

                                                    # Update Add-On

                                                    Edit details for the specified add-on.

                                                    Request Method: POST

                                                    URL Endpoint: /api/recurring/addon/{ add-on id }

                                                      :::

                                                      # Delete Add-On

                                                      Delete the specified add-on.

                                                      Request Method: DELETE

                                                      URL Endpoint: /api/recurring/addon/{ add-on id }

                                                        # Create Discount

                                                        Create a new recurring plan discount. Discounts are used to adjust a recurring charge amount either by a set amount or a percentage of the subscription amount.

                                                        Request Method: POST

                                                        URL Endpoint: /api/recurring/discount

                                                          :::

                                                          # Get Discount By ID

                                                          Retrieve details for the specified discount.

                                                          Request Method: GET

                                                          URL Endpoint: /api/recurring/discount/{ discount id }

                                                            # Get All Discounts

                                                            Retrieve the properties of all discounts for the gateway account associated with the API Key or JWT token provided in the Authorization header.

                                                            Request Method: GET

                                                            URL Endpoint: /api/recurring/discounts

                                                              # Update Discount

                                                              Edit details for the specified discount.

                                                              Request Method: POST

                                                              URL Endpoint: /api/recurring/discount/{ discount id }

                                                                :::

                                                                # Delete Discount

                                                                Delete the specified discount.

                                                                Request Method: DELETE

                                                                URL Endpoint: /api/recurring/discount/{ discount id }

                                                                  # Create Plan

                                                                  Creates a new recurring plan with discounts and/or add-ons.

                                                                  Request Method: POST

                                                                  URL Endpoint: /api/recurring/plan