API

THE DIY SOLUTION

Overview

GloBee provides a standards-based REST interface which enables application developers to interact in a powerful, yet secure way with their GloBee account. Using the GloBee API, clients can create and manage invoices, issue refunds, manage bills, retrieve real-time rates information, view merchant ledger entries, and much more. Developers may call the API directly over HTTPS using the language of their choice, or take advantage of one of GloBee's Node.js, PHP, and Ruby API clients.

Concepts

API Contract

GloBee considers the following types of API changes to be non-breaking and backwards-compatible:

  • exposing a new resource type
  • adding a new method to an existing resource type
  • adding an optional property to an existing resource type
  • adding an optional query parameter to an existing resource method
  • deprecating an existing resource method and providing an alternative

Identities

Authentication in GloBee's API utilizes a specialized identification scheme, BitAuth Identity Protocol. Every Identity is represented in public form as a Client ID, which much like the Bitcoin protocol, 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.

Facades

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

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 My Account -> API Tokens 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 My Account -> API Tokens 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 My Account -> API Tokens, 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 My Account -> API Tokens)

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.

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

Signing Your Request

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.

Cross-Origin Resource Sharing

The GloBee REST API supports CORS, so that you may send requests directly from the client, however remember to never expose your private key. If your key becomes compromised, you will want to disable your old Client ID and register a new one.

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.

References

Ledger Entry Codes

Codes marked as deprecated may have been used in the past, but are no longer used for newly written ledger entries.

GloBee Code Name
1000 Invoice
1001 (deprecated) Fee
1002 (deprecated) Payment
1003 (deprecated) Other
1004 Fee Refund
1005 (deprecated) Deposit
1006 Exchange
1007 Exchange Fee
1008 Plan Charge
1009 Plan Prorated Credit
1010 Plan Underutilization Credit
1011 Payoff Negative Balance
1012 Donation
1013 (deprecated) Corrective
1014 (deprecated) Settlement Fee
1016 Custom
1017 Account Settlement
1018 Overpayment Credit Fee
1019 Overpayment Credit
1020 Invoice Refund
1021 Overpayment Credit Refund
1022 Corrective for Failed Account Settlement
1023 Invoice Fee
1024 Bitcoin Deposit
1025 Fiat Deposit
1026 Donation Fee
1027 Custom Fee
1030 Affiliate Commission
1031 Manual Affiliate Commission
1032 Merchant Card Deposit
1033 Custom Plan Charge
1034 Funding Payout Request
1035 Manually Funding Payout Request
1036 Custom Fee Reimbursement
1037 Custom Plan Charge Reimbursement
1038 Testnet Bitcoin Settlement
1039 Refund Fee
1040 Payout Fee

Available Resources

Bills

Resource

Bills are payment requests addressed to specific buyers. Bill line items have fixed prices, typically denominated in fiat currency.

Schema
Name Type Read-Only
id
Resource id
string
token
API token for bill resource
string
createdDate
Time of bill creation
date
delivered
Indicates whether bill has been delivered to buyer
boolean
number
Bill identifier, specified by merchant
string
status
Can be `draft`, `sent`, `paid`, or `complete`
string
currency
ISO 4217 3-character currency code
string
showRate
Indicates whether corresponding invoice web page should display equivalent fiat amount
boolean
archived
Indicates whether bill is visible in GloBee website
boolean
name
Buyer Name
string
address1
Buyer Street Address
string
address2
Buyer Apartment or Suite Number
string
city
Buyer Locality or City
string
state
Buyer State or province
string
zip
Buyer Zip or Postal Code
string
country
Buyer Country Code (ISO 3166-1 alpha-2)
string
email
Buyer Email
string
phone
Buyer Phone
string
dueDate
UTC date, ISO-8601 format yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ. Default is current time.
date
items
List of line items
array
description
Line item description
string
price
Line item unit price, in `currency`
number
quantity
Line item number of units
number

POST /bills

Creates a bill for the calling merchant.

Required Parameters description price quantity
Facades merchant

GET /bills

Retrieves all of the caller's bills.

Parameters status
Facades merchant

GET /bills/:billId

Retrieves the specified bill.

Parameters none
Facades merchant

PUT /bills/:billId

Updates the specified bill.

Required Parameters description price quantity
Facades merchant

POST /bills/:billId/deliveries

Delivers the bill to the recipient's email.

Parameters none
Facades merchant

Currencies

Resource

Currencies are fiat currencies supported by GloBee

Schema
Name Type Read-Only
code
ISO 4217 3-character currency code
string
symbol
Display symbol
string
precision
Number of decimal places
number
exchangePctFee
Basis points
number
payoutEnabled
Indicates whether GloBee can exchange currency for BTC
boolean
name
English currency name
string
plural
English plural form
string
alts
Alternative currency name(s)
string
minimum
Minimum supported value
string
payoutFields
Can be `merchantEIN`
array

GET /currencies

Retrieves the list of supported currencies.

Parameters none
Facades public

Invoices

Resource

Invoices are time-sensitive payment requests addressed to specific buyers. An invoice has a fixed price, typically denominated in fiat currency. It also has a BTC equivalent price, calculated by GloBee, with an expiration time of about 15 minutes.

Schema
Name Type Read-Only
id
Resource id
string
token
API token for invoice resource
string
price
Fixed price amount, denominated in `currency`
number
currency
Fixed price currency, not the expiring BTC price
string
orderId
Order id
string
orderID
Order id (deprecated)
string
itemDesc
Invoice description, from first line item of bill
string
itemCode
`bitcoindonation` for donations, otherwise null
string
notificationEmail
Contact for notification of invoice status change. If missing, then account notification email address is notified.
string
notificationURL
Webhook URL for instant payment notification (IPN)
string
redirectURL
URL to redirect your shopper back to your website after a successful purchase. Be sure to include "http://" or "https://" in the url.
string
paymentUrls
All URLs where your shopper can pay the invoice. URLs are temporary and will change and not be available after 15 minutes when the invoice expires, unless the invoice has been paid
array
`BIP protocol`
URL for given BIP protocol
string
posData
Order reference number from the point-of-sale (POS). It should be a unique identifer for each order that you submit. Field is a passthru-variable returned in the payment notification post, without any modifications, for you to match up the GloBee payment notification with the request that was sent to GloBee.
string
transactionSpeed
Can be `high`, `medium`, or `low`. HIGH speed confirmations typically take 5-10 seconds, and can be used for digital goods or low-risk items. LOW speed confirmations take about 1 hour, and should be used for high-value items. If missing, then account transaction speed is used.
string
fullNotifications
Indicates whether email and IPN notifications should be sent for this invoice. If missing, then account notification settings are used.
boolean
extendedNotifications
Indicates whether IPN notifications should be sent for this invoice when the invoice expires or is refunded. If true, then fullNotifications is automatically set to true.
boolean
physical
Indicates whether items are physical goods. Alternatives include digital goods and services.
boolean
buyer
Customer who pays the invoice
object
name
Buyer Name
string
address1
Buyer Street Address
string
address2
Buyer Apartment or Suite Number
string
locality
Buyer Locality or City
string
region
Buyer State or province
string
postalCode
Buyer Zip or Postal Code
string
country
Buyer Country code
string
email
Buyer Email
string
phone
Buyer Phone
string
notify
Indicates whether receipt email should be sent to buyer for this invoice
boolean
url
Web address of invoice, expires at `expirationTime`
string
status
Can be `new` (invoice has not yet been fully paid), `paid` (received payment but has not yet been fully confirmed), `confirmed` (confirmed based on the transaction speed settings), `complete` (confirmed by GloBee and credited to the ledger), `expired` (can no longer receive payments), and `invalid` (invoice has received payments but was invalid)
string
btcDue
BTC amount due. This is what the purchaser should pay. This value changes as payments are made to the invoice. Merchants should check that this field is 0 before considering this invoice fully paid.
number
btcPaid
BTC amount paid. The total amount paid to the invoice so far.
number
btcPrice
BTC equivalent of `price`, expires at `expirationTime`. This value does not change as payments are made to the invoice. GloBee adds its fees to this total, so the actual amount GloBee needs to collect will be higher than this value.
number
invoiceTime
UNIX time of invoice creation, in milliseconds
number
expirationTime
UNIX time when invoice is last available to be paid, in milliseconds
number
currentTime
Time of API call
date
exceptionStatus
Can be `paidPartial`, `paidOver`, or false
boolean
rate
BTC exchange rate used for invoice, denominated in `currency`
number
exRates
All exchange rates used for invoice
array
`currency code`
Exchange rate for given currency code
number
transactions
All transactions used to pay invoice
array
amount
Amount paid, in satoshis
number
confirmations
Number of confirmations in blockchain
number
time
Time of transaction from bitcoin network
date
receivedTime
Time when GloBee received transaction from network
date
flags
Miscellaneous invoice attributes
object
refundable
Indicates whether buyer bitcoin address is available for this invoice
boolean
creditedOverpaymentAmounts
For invoices where an overpayment has been credited to the merchant's ledger, this shows the overpayment amount credited. The amounts are listed in terms of all of the currencies that the invoice has exchange rates for. The key is the currency code, and the value is the amount.
object
refundAmounts
If this invoice was fully paid and was then refunded from the ledger, this object will include the amounts refunded. This does not include refunds from the invoice for overpaid and underpaid amounts. The key is the currency code, and the value is the amount. BTC will always be listed. Notice: this field is deprecated; use refundInfo
object
refundInfo
If this invoice has one or more refund from the ledger, refundInfo gives an array with an object per refund that includes information about the refund. refundInfo may not be available for invoices before August 2017.
array
supportRequest
the id of the refund support request
string
currency
the currency code of the refund currency
string
amounts
a map of currency codes to the refunded amount in that currency, includes refunded amount in the refund currency, settlement currency, and BTC
object

POST /invoices

Creates an invoice for the calling merchant.

Required Parameters price currency
Facades merchant pos

GET /invoices/:invoiceId

Retrieves the specified invoice for the calling merchant.

Parameters none
Facades public merchant

GET /invoices

Retrieves invoices for the calling merchant filtered by query. The `limit` and `offset` parameters specify pages for large query sets.

Parameters status orderId itemCode dateStart dateEnd limit offset
Facades merchant

POST /invoices/:invoiceId/refunds

Creates a refund request for the given invoice.

Parameters
Name Type Required Facades
bitcoinAddress string merchant
amount number merchant
currency string merchant
Response
Name Type
id
Refund request resource id
string
requestDate
Time of API call
date
status
Can be `pending`, `success`, or `failure`
string
token
API token for invoice refund request resource
string

GET /invoices/:invoiceId/refunds/:requestId

Returns the status of a refund.

Parameters none
Facades merchant

DELETE /invoices/:invoiceId/refunds/:requestId

Cancels a pending refund request.

Parameters none
Facades merchant

GET /invoices/:invoiceId/refunds

Returns the status of all refunds on an invoice.

Parameters none
Facades merchant

POST /invoices/:invoiceId/notifications

Resends the IPN for the specified invoice.

Parameters none
Facades merchant

Ledgers

Resource

Ledgers are records of money movement.

Schema
Name Type Read-Only
code
Numeric ledger entry code. See the References section at the top of the page for a list of codes and their respective types. New codes may be added in the future for new purposes. Some codes that were once used have since been deprecated and replaced by newer codes. Any integration looking at ledger entry codes needs to anticipate that new codes may be added. Entries with unrecognized codes should be treated as general purpose entries until the integration can be updated to understand the purpose of the new code.
number
type
English description of the ledger entry type based on the code. This is for descriptive purposes only and is subject to change.
string
txType
[DEPRECATED] Similar to `type`, but some of the strings may be different. This may not be available on some entries.
string
amount
Ledger entry amount
number
timestamp
Ledger entry timestamp
date
description
Ledger entry description
string
scale
Power of 10 used for conversion
number
invoiceId
Invoice identifier
string
invoiceAmount
Invoice amount
number
invoiceCurrency
Invoice currency code
string
exRates
All exchange rates used for invoice
array
`currency code`
Exchange rate for given currency code
number
rateEstimated
Some entries do not have exchange rates of their own. For these entries, the listed exchange rate is estimated based on historical data and the timestamp.
boolean

GET /ledgers/:currency

Retrieves the caller's ledger entries for the given currency.

Parameters startDate endDate
Facades merchant

GET /ledgers

Retrieves the caller's ledgers for each currency with summary.

Parameters none
Facades merchant
Response
Name Type
currency
ISO 4217 3-character currency code
string
balance
Account balance, in given currency code
number

Payouts

Resource

Payouts are batches of bitcoin payments to employees, customers, partners, etc.

Schema
Name Type Read-Only
id
Resource id
string
token
API token for payout request resource
string
account
Merchant account id
string
status
Can be `new`, `funded`, `processing`, `complete`, `failed`, and `cancelled`
string
btc
BTC equivalent amount
number
requestDate
Date when request was submitted
date
instructions
Payout instructions
array
id
Resource id of instructions
string
status
Can be `unpaid`
string
btc
BTC payment summary
object
paid
Amount paid
number
unpaid
Amount unpaid
number
transactions
Transactions
array
amount
BTC amount
number
address
Bitcoin address
string
label
Label
string
walletProvider
If the payout request is for more than 3000 USD and sends to an address controlled by one of the specified wallet providers, the name of the wallet provider and the receiverInfo for the recipient must be provided. The list of wallet providers can be found in the references section at the top of the page.
string
receiverInfo object
name
Full name of the individual who is receiving the payout
string
emailAddress
email address of the individual who is receiving the payout
string
address
street address of the recipient
object
streetAddress1 string
streetAddress2 string
locality
equivalent to city
string
region
equivalent to state or province
string
postalCode string
country string
amount
Fiat or BTC amount
number
currency
Payout currency
string
percentFee
Percent fee charged on the payout
number
fee
Absolute amount of the fee charged, in the currency of the payout
number
depositTotal
Total amount, including the fee, that must be deposited to fund the payout
number
effectiveDate
Date when request is effective. Note that the time of day will automatically be set to 09:00:00.000 UTC time for the given day. Only requests submitted before 09:00:00.000 UTC are guaranteed to be processed on the same day.
date
reference
Merchant-provided data
string
bankTransferId
Merchant-provided data, to help match funding payments to payout batches
string
supportPhone
GloBee support phone number
string
pricingMethod
Can be `manual_2` or `vwap_24hr`
string
notificationEmail
IPN email address
string
notificationURL
IPN webhooks URL
string

POST /payouts

Creates a payout batch request.

Required Parameters instructions amount address amount currency effectiveDate
Facades payroll

GET /payouts

Retrieves all of the caller's payout requests by status.

Parameters status
Facades payroll

DELETE /payouts/:payoutId

Cancels the given payout request if status is still new.

Parameters none
Facades payroll

GET /payouts/:payoutId

Retrieves the specified payout request.

Parameters none
Facades payroll

Rates

Resource

Rates are exchange rates, representing the number of fiat currency units equivalent to one BTC.

Schema
Name Type Read-Only
code
ISO 4217 3-character currency code
string
name
English currency name
string
rate
Currency units per BTC
number

GET /rates

Retrieves the list of exchange rates.

Parameters none
Facades public

GET /rates/:currency

Retrieves the exchange rate for the given currency.

Parameters none
Facades public

Sessions

POST /sessions

Creates an API session to protect against replay attacks and ensure requests are received in the same order they are sent.

Required Parameters none
Facades public

Settlements

Resource

Settlements are transfers of payment profits from GloBee to bank accounts and bitcoin wallets owned by merchants, partners, etc. This endpoint exposes reports detailing these settlements.

Schema
Name Type Read-Only
id
Resource id
string
accountId
Account Id
string
currency
`BTC` or ISO 4217 3-character currency code
string
payoutInfo object
name
Name on bank account
string
account
Bank account number
string
routing
Bank routing number
string
merchantEIN
Merchant EIN number
string
label
Account label
string
bankCountry
Country of bank account
string
status
Can be `processing`, `completed`, or `failed`
string
dateCreated
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Indicates date when settlement was created.
date
dateExecuted
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Indicates date when settlement was executed. This is the time when ledger entries were written.
date
dateCompleted
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Indicates date when settlement was completed. Present for `completed` and `failed` settlements only.
date
openingDate
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Ledger entries newer than or equal to this date and older than closingDate are included in this settlement.
date
closingDate
UTC date, ISO-8601 format yyyy-mm-ddThh:mm:ssZ. Ledger entries older than this date and newer than openingDate are included in this settlement.
date
openingBalance
Opening balance as of openingDate
number
ledgerEntriesSum
Sum of all ledger entries included in the settlement
number
withholdings array
amount
Amount withheld from settlement
number
code
Code identifying what type of withholding
string
description
Description of withholding
string
notes
Any additional notes about this withholding
string
withholdingsSum
Sum of withholdings
number
totalAmount
Total amount settled, in `currency`
number

GET /settlements

Retrieves settlement reports for the calling merchant filtered by query. The `limit` and `offset` parameters specify pages for large query sets.

Parameters startDate endDate currency status limit offset
Facades merchant

GET /settlements/:settlementId

Retrieves a summary of the specified settlement.

Parameters none
Facades merchant

Subscriptions

Resource

Subscriptions are repeat billing agreements with specific buyers. GloBee sends bill emails to buyers identified in active subscriptions according to the specified schedule.

Schema
Name Type Read-Only
id
Resource id
string
token
API token for subscription resource
string
billData
See `bills` resource
object
schedule
Schedule of repeat bill due dates. Can be `weekly`, `monthly`, `quarterly`, `yearly`, or a simple cron expression specifying seconds, minutes, hours, day of month, month, and day of week. GloBee maintains the difference between the due date and the delivery date in all subsequent, automatically-generated bills.
string
status
Can be `draft` or `active` or `cancelled`. Subscriptions in active state will create new Bills on the nextDelivery date.
string
nextDelivery
UTC date, ISO-8601 format yyyy-mm-dd or yyyy-mm-ddThh:mm:ssZ. Default is current time. Current or past date indicates that the bill can be delivered immediately. GloBee may modify the hh:mm:ss values in order to distribute deliveries evenly throughout the day.
date

POST /subscriptions

Creates a repeat billing subscription.

Required Parameters billData schedule
Facades merchant

GET /subscriptions

Retrieves all of the caller's subscriptions.

Parameters status
Facades merchant

GET /subscriptions/:subscriptionId

Retrieves the specified subscription.

Parameters none
Facades merchant

PUT /subscriptions/:subscriptionId

Updates the specified subscription.

Required Parameters none
Facades merchant

Tokens

Resource

Tokens are API access identifiers which are associated with a set of capabilities. A capability may be very broad, for example, retrieve the list of all exchange rates. Or a capability may be very specific, for example, update bill #12345.

Schema
Name Type Read-Only
id
Client identity based on bitcoin identity protocol
string
pairingCode
Access approval code
string
facade
Can be `merchant`, or `pos`
string
label
Token label, may include spaces, underscores, and dashes
string

POST /tokens

Creates or claims an access token.

Required Parameters id
Facades public merchant onboarding
Response
Name Type
policies
undefined
array
policy
Can be `sin`, `access`, `events`, `id`, or `session`
string
method
Can be `requireSin`, `requireFacadeAccess`, `allowEventStream`, `invalidated`, `inactive`, `unclaimed`, `requireSession`
string
params
Can be `support`, SIN value, or null
array
resource
Token identifier
string
token
API token for token resource
string
facade
Can be `merchant`, or `pos`
string
dateCreated
UNIX time of creation, in milliseconds
number
pairingExpiration
UNIX time of expiration, in milliseconds
number
pairingCode
Access approval code
string