Glossary

A glossary for anything and everything about Basys' APIs

API Reference

The Basys API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Authentication

Basys' APIs follows the OAuth 2.0 authentication protocol by utilizing JSON Web Tokens (JWT) to authenticate requests. To generate a JWT see the Getting Started page. These JWTs allow you access Basys' APIs which can submit invoices, add customers and process transactions so keep them save and secure! Do not share your JWT Tokens and the client_ids and secretIds that generate them in publicly accessible areas such as GitHub, client-side code, or anywhere they can be easily copied from.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

API Definitions & Statuses

HTTP Methods:

HTTP methods enable API clients to perform CRUD (Create, Read, Update, and Delete) actions on an API’s resources in a standardized and predictable way. The following describes each HTTP Method:

GET

The GET method is used to retrieve data on a server. Clients can use the GET method to access all of the resources of a given type, or they can use it to access a specific resource. For instance, a GET request to the /gateway endpoint of the Gateway API would return all of the gateways in the database, while a GET request to the /gateway/123 endpoint would return the specific Gateway with an ID of 123. GET requests typically do not include a request body, as the client is not attempting to create or update data.

POST

The POST method is used to create new resources. For instance, if the client wanted to add a new gateway to the database, they would send a POST request to the /gateway endpoint. Unlike GET requests, POST requests typically include a request body, which is where the client specifies the attributes of the resource to be created. For example, a POST request to the /gateway endpoint might have a request body that looks like this:

{
"name": "string", 
"description": "string", 
"phone": "string", 
"phoneExternal": "string", 
"receiptEmail": "string", 
"website": "string", 
"timezone": "string", 
"merchantId": "string", 
"addresses": [ 
    { 
       "isPrimary": true, 
       "isBilling": true, 
       "isInvoice": true, 
       "address": { 
              "addressLine1": "string", 
              "addressLine2": "string", 
              "city": "string", 
              "state": "string", 
              "postalCode": "string", 
              "country": "string", 
              "firstName": "string", 
              "lastName": "string", 
              "email": "user@example.com", 
              "phone": "2096087464", 
              "fax": "5273006741", 
              "company": "string" 
       } 
    } 
], 
"gatewayMetadata": [ 
    { 
       "preferenceType": "string", 
       "gatewaySettings": [ 
           { 
              "code": "string", 
              "value": "string" 
           } 
        ] 
    } 
], 
"gatewayConfigurations": [ 
    { 
    "categoryCode": "string", 
    "fieldEntryValues": [ 
        { 
            "fieldCode": "string", 
            "fieldValue": [ 
                "string" 
                ] 
            } 
        ] 
    } 
] 
}

PUT

The PUT method is used to replace an existing resource with an updated version. This method works by replacing the entire resource (i.e., the specific gateway located at the /gateway/123/configuration endpoint) with the data that is included in the request’s body. This means that any fields or properties not included in the request body are deleted, and any new fields or properties are added.

PATCH

The PATCH method is used to update an existing resource. It is similar to PUT, except that PATCH enables clients to update specific properties on a resource—without overwriting the others. For instance, if you have a gateway resource with fields for name, andaddress, but you only want to update the address, you could use the PATCH method to send a request that only includes the new value for the address field. The rest of the resource would remain unchanged. This behavior makes the PATCH method more flexible and efficient than PUT.

DELETE

The DELETE method is used to remove data from a database. When a client sends a DELETE request, it is requesting that the resource at the specified URL be removed. For example, a DELETE request to the /gateway/123 endpoint will permanently remove the gateway with an ID of 123 from the database. Some APIs may leverage authorization mechanisms to ensure that only clients with the appropriate permissions are able to delete resources.

HTTP Status Codes

Credit Card Processing Technology Terms

• ACH - ACH (Automated Clearing House) is a computer-based electronic network for processing transactions, usually domestic low-value payments, between participating financial institutions. It may support both credit transfers and direct debits.

• Gateway - A gateway is a technology platform that securely transmits online payment data to the processor for transactions the merchant runs.

• Processor - The network used to facilitate the electronic transfer of funds between the card issuer's bank and the merchant’s bank.

• Virtual Terminal - The POS (Point of Sale) web UI that connects to the processor allowing you to process credit card and ACH transactions.

• Transaction - Any billable occurrence completed or submitted under a merchant’s account including but not limited to capture, authorization, validation, sale, void, blind credit, or refund.

• Capture - Capture is when an authorized transaction is marked for settlement.

• Authorization - Authorization is a transaction type where the cardholder's issuing bank returns whether the cardholder has sufficient funds to cover the cost of the transaction. A transaction with the transaction type of Authorization won’t be settled until a capture has occurred on that transaction. Think of how a restaurant runs your card for the original amount but updates it later to include a tip.

• Incremental Authorization - An additional authorized amount applied to an already authorized amount. This is used for total price changes or the customer adds goods or services and you need to update the amount on the payment.

• Validation - Validation is the transaction type to validate the authenticity and validity of the credit card or ACH account.

• Sale - Sale is a transaction type where a transaction is automatically flagged for settlement.

• Void - Voiding is an action that can be taken on an existing transaction before it is settled. Voiding a transaction cancels it from being settled.

• Blind Credit - A blind credit is a refund issued to the cardholder that isn’t associated with an existing transaction.

• Refund - Refund is a transaction type where the captured amount is refunded to the cardholder.

• Settlement - Settlement is the process of transferring the funds from the cardholder’s issuing bank to the merchant’s bank account for a transaction. All transactions are settled once a day.

• Captured Amount - The final amount for a transaction that is collected by the merchant’s bank during settlement.

• Invoice - An invoice is a billing statement issued to a customer to pay via, credit card or ACH.

• Customer Payable Token -  Customer Payable Token is a unique, encrypted identifier generated for each customer, enabling them to view all their outstanding invoices via a "Customer Payables" link provided by the merchant.

• Subscriptions - Subscriptions are recurring payments in which a customer authorizes a merchant to process a transaction for them automatically and at regular intervals configured by the merchant.

• Tokenization - The process of exchanging sensitive data for nonsensitive data called “tokens” that can be used in a database or internal system without bringing it into scope.  

• CSV - Comma-separated values (CSV) is a text file format that uses commas to separate values, and newlines to separate records.

• Idempotency - A property of certain operations or API requests, which guarantees that performing the same operation multiple times in quick succession will yield the same result as if it was executed only once.

• Triggers - Specific codes that are hard-coded to generate a predetermined response in the system.

• JWT - JSON Web Token (JWT), pronounced "jot", is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object.

• Webhooks - A callback method in which one software system uses APIs to instantly notify another system of an event.