Library OpenApi Overview About these APIs Architecture Authentication Error Responses Locating a Server Sessions Design Guides Guides and Hints Examples Pricing for Websites Accepting Vouchers PreAuth Payment Replication Common Apis The most used APIs Create New Sale Payment Completion Multiple Locations Delivery Addresses Create New Sale v2 Customers Locations Products Staff WebHooks eCommerce Apis These APIs are often used with eCommerce website integrations Get Pricing Card Inquiry Report & Analysis Grouped or analysed report data. Typically used to build reports and dashboards Today Login Access Pinboard ReportRequest Advanced Information More indepth information Caller Handling HTTP Protocol Bulk Data Downloads Document Uploading RetailConfig Under Development Details of APIs that will be available shortly. Documentation provided is for early adopters Get Receipt

Authentication

Each API provided is protected by a set of access rules. The API provided is the same as the internal Fieldpine used APIs but is restricted and controlled using security rules rather than creating a seperate API for more public use. The following outlines the various ways security might be applied to an API, keep in mind that each retailer can apply different rules.

Available Techniques

No Security APIs

Some APIs have no security where the data is not considered private. For example APIs that provide validation services, such as checking an email for valid syntax, may not be protected. With this level of security you do not have to provide an X-Api-Header, but can if you wish.

Internal Network

In situations where the API caller inside your network or you are not concerned by X-Api-Keys being stolen, then simply place the X-Api-Key in the request header.

Internal networks are also able to use Negotiate and NTLM authentication schemes.

Single Use Tokens

In some cases a customer or browser may have a Url pointing to secure information. This url can include a "single use token" which is an opaque value that you can insert into the X-Api-Key to provide restricted access to a single resource. These are slightly different to general API calling but are mentioned so that all methods are clear. Single use tokens provide very granular access to resources that your webserver might not have general access too.

For example, a QR code might include a SUT (Single Use Token) to permit access to a single sales details; or a purchase order sent to a supplier

High Security APIs used from internet web server.

User Browser
or
Mobile App
Retailers
public
WebServer
⇳  Protected API server

Some APIs process sensitive information, or you need to protect the Api-Key. A web developer will often call the API from the web server host providing their secret Api-Key. With this approach the details of the backend API are invisible to the browser.

Works best on: With Firewall and Using Fieldpine configurations

Advantages

  • Secure. API keys are not divulged to browsers and apps
  • Easier to handle multiple API server hosts

Disadvantages

  • Website developer needs to code interfaces and calls
  • Website may need to pass some details of original browser, such as IP address or User-Agent
  • Additional calling latency

Lower Security APIs used from directly from browser

User Browser
or
Mobile App
(Lower Security API)
Retailers
public
WebServer
Protected API server

If the API involved is of lower security or can be protected via source IP address locking, such as when an API is called from trusted suppliers, then the end user browser can directly call the API. This method can also be used if the retailers webserver has a login type function and can issue individual Api-Keys based on your login

Works best on: With Firewall and Using Fieldpine configurations

Advantages

  • Development is client-only, no server side coding
  • Api Server has direct access to original browser so can security validate directly

Disadvantages

  • Api-Key is visible to end browser
  • Some complexity if needing to handle multiple Api Servers
  • Api needs to permit CORS
  • Can expose Origin server IP address unless obscured

Medium Security APIs used from directly from browser

This method is not currently available but will be shortly

User Browser
or
Mobile App
(Medium Security API)
Retailers
public
WebServer
Protected API server

Medium security APIs are used to access sensitive data but without exposing your API key to the browser. The flow is broadly

  1. User browses to retailer website
  2. HTML includes an IFRAME to Api-Server. This is an invisible iframe, to process Javascript only
  3. HTML communicates to IFRAME with postMessage and can retrieve sensitive data

Works best on: With Firewall and Using Fieldpine configurations

Advantages

  • Api Server has direct access to original browser so can security validate directly
  • Can work for static hosted websites
  • Api Server does not need to support CORS

Disadvantages

  • Requires postMessage support in client browser
  • Ideally servers should pass a token from server to Api-Server, and have the webpage postMessage this same token to the IFRAME. This requires server side coding but is more secure.
  • Requires loading an IFRAME/script from fieldpine.com and client side scripting
  • Can expose Origin server IP address unless obscured

Notes

APIs need to be specifically enabled for CORS support, they are not enabled by default for APIs that return data, but are generally enabled for validation type APIs. Please keep in mind that CORS is not a security mechanism, a skilled attacker can bypass CORs in some cases.

The API server can restrict by transport method, in general you should use HTTPS where possible

Requests to the server are rate limited and velocity controlled. The rate limits are high so you do not need to be concerned for normal operation. Velocity limits control the rate at which APIs can be called and are a common technique for financial applications. While the rate limit for an API might be 10,000 calls/hour the velocity limit might start slowing individual original IP addresses after 3 or 4 requests. In general the server will slow down response time as limits are approached, but may also return errors or simply close the network connection.

Different retailers may have different API servers. Premium rate customers may be using different hosts, while other retailers may be using the public servers. In general this has no bearing to you, but keep in mind that host servers can change.