# Composing Requests

# Base Urls

TIP

Whenever you see the placeholder { url goes here } within this documentation, you will need to replace it with one of the following urls based on which API environment you are processing against.

When accessing endpoints, the request url should always obey the following format:

https://{ base url }{ url endpoint }

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 }

See Request JWT and API Keys > Create for guidance on generating these assets.

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

# API Keys

API keys give a user access to manage data within a gateway account without needing to generate and persist a JWT token.

TIP

There are two key types: API and Public. The "API" type is a secret key for use on the back-end of your application. "Public" keys are safe to use in front-end code (for example, initializing the tokenizer) and do not have full access to all endpoints.

# Create API Key

Generate a new API key for the user account associated with the API key or JWT token provided in the Authorization header of this request.

Request Method: POST

URL Endpoint: /api/user/apikey

    # Get API Keys

    Get a list of API keys attached to the user account associated with the API key or JWT token provided in the Authorization header of this request.

    Request Method: GET

    URL Endpoint: /api/user/apikeys

      # Delete API Key

      Delete the API Key specified in the request url. Public keys cannot be used in the Authorization header for this request.

      Request Method: DELETE

      URL Endpoint: /api/user/apikey/{ API Key }

        # Authentication

        To authenticate with a username and password:

        1. Collect login credentials from the user.

        2. Pass the credentials to the /api/token-auth endpoint to obtain a token.

        3. Use the token to authenticate subsequent calls by using it as the value of your Authorization header.

        TIP

        An active JWT will expire if 20 minutes have elapsed since it has been used in a request.

        # Request JWT

        Supply the user's login credentials and receive a token that can be used to authenticate subsequent API requests.

        Request Method: POST

        URL Endpoint: /api/token-auth

          # Forgot Username

          Supply the email address associated with a user's account to send an email containing the usernames listed for that account.

          Request Method: POST

          Request Endpoint: /api/user/forgot-username

            # Forgot Password

            Supply the username associated with a user account and an email will be sent to the address on file with a password reset token. This token is used to make a Password Reset request.

            Request Method: POST

            Request Endpoint: /api/user/forgot-password

              # Password Reset

              Supply a username, a valid password reset token, and a new password to be set for the account in order to update the user's saved password.

              Request Method: POST

              URL Endpoint: /api/user/forgot-password/reset

                # Logout

                Logout will terminate the JWT used to authorize the request.

                Request Method: GET

                URL Endpoint: /api/logout

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

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