GETTING STARTED

APIs

GENERAL NOTES
DIFFERENT API's

PAYMENT API

LEGACY API

VERSION 2
REQUESTS
RESPONSES
AUTHENTICATION
GETTING ACCESS
FACADES
API SESSIONS
VERSION 1
RESOURCES

# LEGACY API VERSION 2

The legacy api allows users to perform more actions than simply creating payment-requests, but the authorization process is more intense and complicated for security purposes. Each message is signed using Eliptic Curve Cryptography and is verified before any actions are taken.

# REQUESTS

Requests to the GloBee REST API follow a RESTful convention using standard HTTP verbs against various GloBee resources to return JSON formatted responses. Once again the mechanics of this exchange may be simplified through the use of one of the GloBee libraries.

Each request should include in the HTTP headers:

  • x-identity(the hexadecimal public key generated from the client private key)
  • x-signature(header which is cryptographically computed as described below)
  • content-type: application/json
  • x-accept-version: 2.0.0

To make an API request send an HTTP request with a HTTP method to a resource URI and include in the body JSON parameters of the following (plus any additional parameters needed):

  • token(obtained during client registration process above)
  • guid(an optional parameter to enforce idempotence for POST requests)

For more information about specific resource URIs, please visit the resource documentation.


Making Requests

The x-signature header is the ECDSA signature of the full request URL concatenated with the request body, signed with your private key. So if you are sending a request to:

https://globee.com/invoices

And your request body is:

{"amount":500,"currency":"USD","token":"1234567"}

The string you will sign is:

https://globee.com/invoices{"amount":500,"currency":"USD","token":"1234567"}

The result should be included as the value of the x-signature request header.

# RESPONSES

All responses contain a JSON encoded string with the required information on success, or an error message on failure.

# AUTHENTICATION

Protocol

Authentication in GloBee's API utilizes a specialized identification scheme called BitAuth Identity Protocol. Every Identity is represented in public form as a Client ID, which is simply a hash of the identity's public key. For your convenience, all of GloBee's Client Libraries support this functionality.


Tokens

Authorization in GloBee's API utilizes Capability-based Security principles. Each API call must be accompanied by an API Token which grants access to the requested capability. API Tokens are analagous to a real-world event ticket, which grants access to a specific event when presented at the door. Also like tickets, they may grant broad or narrow privileges (e.g. 'General Admission' vs. 'Seat 44B') as well as add bearer requirements (e.g. 'Must be over 21' or 'Non-transferrable, must show ID').

New tokens are provided with each response from the API. For example, creating a new Invoice with one token will provide a new, second token that grants access to view and interact with that Invoice exclusively. If not using GloBee's Client Libraries, you will need to keep track of these tokens on your own.

# GETTING ACCESS

To use any non-public facade a token will need to be sent with the API request. Tokens can require authentication, which would requiring cryptographically signing each request. You can either generate a token directly from an API client or via the API -> Legacy API V2 page. To receive a token directly from an API client, send a POST request to globee.com/tokens with the following query parameters:

  • label (e.g. My GloBee Client)
  • id (e.g. Tf3wXWuwfT1TmenHF21P1nYZ7BeyrYNdiwo)
  • facade (e.g. merchant)

This will respond with a new token that will include a pairingCode. This pairing code can then be shared with a merchant organization administrator to approve access. This can be done by visiting API -> Legacy API V2 and entering the pairing code, or by visiting the url format: globee.com/api-access-request?pairingCode=<pairingcode_goes_here>.

Alternatively, pairing codes can be generated directly at API -> Legacy API V2 , and can then be claimed by API clients which associates a Client ID with the token, and will activate it for further usage. To claim a token from an API client, send a POST request to globee.com/tokens with the following parameters:

  • label (e.g. My GloBee Client)
  • id (e.g. Tf3wXWuwfT1TmenHF21P1nYZ7BeyrYNdiwo)
  • pairingCode (e.g. As retrieved from API -> Legacy API V2)

A token without a Client ID authentication restriction can be made, and a token can then be copied directly to make API calls, such as creating invoices. It is also important to note that pairing codes will expire after 24 hours, however once a token is approved or claimed the expiration is cleared.

# FACADES

Facades are named collections of capabilities that can be granted, such as the ability to create invoices or grant refunds. In the ticket analogy, this corresponds to the ticket 'level', where a 'VIP' ticket would confer broader access than a 'Standard' level ticket. When registering an Identity, it is against a specific facade. Best practices suggest that the requested facade should be limited to the minimum level that grants the required capabilities.

Facade Capabilities Description
public The implicit facade applied when no token is provided. Provides access to public methods for generating merchant applications, generating and claiming tokens, or checking exchange rates.
pos Limited to creating new invoices for the merchant's organization
merchant The broadest set of capabilities against a merchant organization. Allows for create, search, and view actions for Invoices and Bills; ledger download, as well as the creation of new merchant or pos tokens associated with the account.

# API SESSIONS

API sessions are an optional feature of our API which can be utilized to provide even greater security and reliability. In particular it protects against replay attacks and ensures api requests are processed in the same order they are received.


An API session can be created by issuing a POST to /sessions. The server responds with a sessionId. The sessionId is used in each subsequent request along with a requestNumber. These fields, sessionId and requestNumber are included as parameters either in the URL for a GET or in the data body for POST and PUT.


On the first request, the requestNumber should be 1. Each additional request should increment the requestNumber by 1. If the server receives a request out of order it will return an error. If the client does not hear back from the server because of an interruption in network connectivity or some other problem, the client may retry by sending the same request with the same requestNumber. The server will then respond with a cached copy of the data if it had already serviced that request but was interrupted when delivering it to the client.


API sessions timeout after 15 minutes of inactivity. After 15 minutes, clients will get an error, and must create a new session. Clients can be programmed to handle creation of new sessions and timeouts automatically. Please see the Node.js client library for a working implementation.