# 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

                # 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

                    # 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
                      }
                    }
                    

                    # 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
                      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

                                                              # Get Plan By ID

                                                              Retrieve details for the specified plan.

                                                              Request Method: GET

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

                                                                # Get All Plans

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

                                                                Request Method: GET

                                                                URL Endpoint: /api/recurring/plans

                                                                  # Update Plan

                                                                  Edit details for the specified plan.

                                                                  Request Method: POST

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

                                                                    # Delete Plan

                                                                    Delete the specified plan.

                                                                    Request Method: DELETE

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

                                                                      # Create Subscription

                                                                      Creates a new subscription which applies a recurring billing plan to a customer.

                                                                      Request Method: POST

                                                                      URL Endpoint: /api/recurring/subscription