GETTING STARTED

APIs

GENERAL NOTES
DIFFERENT API's

PAYMENT API

VALIDATION ERRORS
STATUSES
REQUESTS
PING
PAYMENT REQUEST
PAYMENT METHODS
PAYMENT DETAILS
CALLBACK IPN

# Payment API

Our payment API is built to allow quick and easy integration with our system. Its sole purpose is to create payment-requests, which allows eCommerce site owners to accept payment using crypto currencies.

Quick Start: You can install our Payment API PHP SDK or take a look at any of our existing plugins if you don't want to implement your own solution.

Protocol

Our API follows the RESTful architectural style and can be accessed by making HTTPS requests using the GET, POST and PUT HTTP verbs.

The base URL for the LIVE API is:
https://globee.com/payment-api/v1/

The base URL for the TEST API is:
https://test.globee.com/payment-api/v1/

Requests Structure

Requests must be sent over HTTPS with any payload formatted in JSON. All requests must contain the X-AUTH-KEY header to facilitate authorization. You can generate a new authorization key in your merchant account under API -> Payment API.

Response Structure

Responses are returned as json, containing a data key with the result for all 2xx responses, or an errors key containing a list of validation errors for all 422 responses.

# Validation Errors

Validation errors return the HTTP code 422 (Unprocessable Entity).

Type Extra Description
required_field null This field is required and not provided.
invalid_number null Field is not a valid number.
invalid_email null Field is not a valid email.
invalid_url null The field is not a valid URL
invalid_selection List of possible values (eg. ["a", "b", "c"]) The field is not in the current list of accepted values
invalid_array null Field needs to be an array.
below_minimum Minimum value (eg. ["5"]) The field is below the minimum size.
above_maximum Maximum value (eg. ["99"]) The field is above the maximum size.
out_of_range Range bounds (eg. ["5", "99"]) The field is outside the allowed range.

Validation Error Response (example) 

{
  "success": false,
  "errors": [
    {
      "type": "required_field",
      "extra": null,
      "field": "customer.email",
      "message": "The customer email field is required."
    },
    {
      "type": "invalid_number",
      "extra": null,
      "field": "total",
      "message": "The total must be a number."
    },
    {
      "type": "below_minimum",
      "extra": [
        "10"
      ],
      "field": "total",
      "message": "The total must be at least 10."
    },
    {
      "type": "invalid_selection",
      "extra": [
        "AFN",
        "ALL",
        "DZD",
        "..."
      ],
      "field": "currency",
      "message": "The selected currency is invalid."
    }
  ]
}

# Statuses

Payment Requests can be in one of the following statuses:

Status Description
unpaid All payment-requests start in the unpaid state, ready to receive payment.
paid The payment request has been paid, waiting for required number of confirmations.
underpaid Payment has been received, however, the user has paid less than the amount requested. This generally should not happen, and is only if the user changed the amount during payment.
overpaid Payment has been received, however, the user has mistakenly paid more than the amount requested. This generally should not happen, and is only if the user changed the amount during payment.
paid_late Payment has been received, however, the payment was made outside of the quotation window.
confirmed Payment has been confirmed based on your profile confirmation risk settings.
completed The payment-request is now completed, having reached maximum confirmations, and Globee will start its settling process.
refunded The invoice was refunded and cancelled.
cancelled The invoice was cancelled.
draft Invoice has been saved as a draft and not yet active.

# Requests

Request endpoints are resources accessible over the API. An endpoint can be called using the different HTTP verbs (GET, POST, PATCH, PUT, DELETE) if the endpoint supports the verb. The type of verb will also determine the type of action as a result.


Ping

This endpoint is used as a test endpoint for the user to verify that the integration and authentication is done correctly.

GET/ping

Returns the merchant name and URL in order for the user to validate that the authorization has been setup correctly.

cURL Request (example) 
curl -X GET 'https://globee.com/payment-api/v1/ping' \
    -H 'Accept: application/json' \
    -H 'X-AUTH-KEY: 1a2b3c4d5e6f7g8h9i0j'
PHP (cURL) Request (example) 
<?php

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://globee.com/payment-api/v1/ping');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

curl_setopt($curl, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'X-AUTH-KEY: 1a2b3c4d5e6f7g8h9i0j',
]);

$response = curl_exec($curl);

if (curl_errno($curl) === 0) {
    $json = json_decode($response);
    print_r($json);
} else {
    echo curl_error($curl);
}

curl_close($curl);
Ruby Request (example) 
require 'net/http'
require 'uri'
require 'json'

url = 'https://globee.com/payment-api/v1/ping'
uri = URI(url)
req = Net::HTTP::Get.new(uri)
req['Accept'] = 'application/json'
req['X-AUTH-KEY'] = '1a2b3c4d5e6f7g8h9i0j'

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

response = http.request(req)

print JSON.parse(response.body)
Python Request (example) 
import requests

headers = {
    'Accept': 'application/json',
    'X-AUTH-KEY': '1a2b3c4d5e6f7g8h9i0j',
}

response = requests.get('https://globee.com/payment-api/v1/ping', headers=headers)

print response.json();
Success Response (example) 
{
  "success": true,
  "result": {
    "name": "Globee",
    "url": "http://globee.com"
  }
}

Payment Request

Payment requests are resources used to handle payments, as part of the payment process in an e-commerce checkout flow.

On the merchant website, when a user checks out and selects the option to pay with Globee, the system needs to create a new payment-request that the user will pay on. The response will contain a redirect url to which the user needs to be redirected in order to make payment. Once the payment has been received, the user will be redirected back to the success url if it was set when the payment-request was created.

A cancel url can also be set to redirect the user back to the checkout screen if the user decides not to pay using Globee.

POST/payment-request

Creates a new payment request. On a successful request, the user has to be redirected to the redirect_url contained in the response in order to complete the payment process. A payment request will only be valid for 15 minutes after it was created.

Parameters
)
Name Value Required Notes
total number Required The total amount in the invoice currency.
adjusted_total number Returned The adjusted invoice total after accepted under/over payments are applied.
currency string Recommended ISO 4217 currency codes (eg. USD), including BTC (Bitcoin) and XMR (Monero). Defaults to USD.
custom_payment_id string Optional A reference or custom identifier that you can use to link the payment back to your system.
callback_data string Optional Passthrough data that will be returned in the IPN callback.
customer.name string Recommended The name of your customer making the payment
customer.email string Required The email address of your customer making the payment.
payment_details.currency string|null Returned The method used to make payment, eg: BTC, XMR, LTC etc.
payment_details.received_amount number|null Returned The amount paid by the customer in the invoice currency.
payment_details.received_difference number|null Returned The difference between the initial amount requested, and the amount paid by the customer in the invoice currency.
redirect_url string Returned The URL to redirect the client to in order to make payment.
success_url string Recommended A URL to direct the user to after a successful payment has been made.
cancel_url string Recommended A URL to direct the user to if they decide to cancel the payment request.
ipn_url string Recommended The URL for the Instant Payment Notification callback to notify your site of updates on the payment-request, like status changes. Please note this does not follow redirects.
notification_email string Optional An email address that the system wil send a notification email to once the payment has been confirmed.
confirmation_speed string Optional The amount of confirmations required before changing the status to confirmed. Possible options are "low", "medium" or "high". High requires the least amount of confirmations, think high speed, high risk, where low requires the maximum amount of confirmations. Defaults to "medium".
custom_store_reference string Optional A custom store reference
line_items array Optional A list of all the items for this invoice. This field is optional, but if populated, ensure all line item attributes are filled as instructed below.
line_items.name string Required The name of the line item
line_items.price number Required The price of the line item
line_items.qty number Required The quantity of the line item
cURL Request (example) 
curl -X POST 'https://globee.com/payment-api/v1/payment-request' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-KEY: 1a2b3c4d5e6f7g8h9i0j' \
    -d '{
          "total": 123.45,
          "currency": "USD",
          "custom_payment_id": "742",
          "custom_store_reference": "abc",
          "callback_data": "example data",
          "customer": {
            "name": "John Smit",
            "email": "john.smit@hotmail.com"
          },
          "line_items": [
            {
              "name": "Item 1",
              "price": 125.50,
              "qty": 3
            }, {
              "name": "Item 2",
              "price": 250.00,
              "qty": 1
            }
          ],
          "success_url": "https:\/\/www.example.com/success",
          "cancel_url": "https:\/\/www.example.com/cancel",
          "confirmation_speed": "medium",
          "ipn_url": "https:\/\/www.example.com/globee/ipn-callback"
        }'
Success Response (example) 
{
  "success": true,
  "data": {
    "id": "a1B2c3D4e5F6g7H8i9J0kL",
    "status": "unpaid",
    "total": "123.45",
    "currency": "USD",
    "custom_payment_id": "742",
    "custom_store_reference": "abc",
    "callback_data": "example data",
    "customer": {
      "name": "John Smit",
      "email": "john.smit@hotmail.com"
    },
    "payment_details": {
      "currency": null
    },
    "redirect_url": "http:\/\/globee.com\/invoice\/a1B2c3D4e5F6g7H8i9J0kL",
    "success_url": "https:\/\/www.example.com/success",
    "cancel_url": "https:\/\/www.example.com/cancel",
    "ipn_url": "https:\/\/www.example.com/globee/ipn-callback",
    "notification_email": null,
    "confirmation_speed": "medium",
    "expires_at": "2018-01-25 12:31:04",
    "created_at": "2018-01-25 12:16:04"
  }
}
PUT/payment-request/{payment_id}

Updates an existing payment request. Only the parameters listed below can be updated.

Parameters
Name Value Required Notes
custom_payment_id string Optional A reference or custom identifier that you can use to link the payment back to your system.
callback_data string Optional Passthrough data that will be returned in the IPN callback.
customer.name string Recommended The name of your customer making the payment
customer.email string Required The email address of your customer making the payment.
custom_store_reference string Optional A custom store reference
cURL Request (example) 
curl -X PUT 'https://globee.com/payment-api/v1/payment-request/a1B2c3D4e5F6g7H8i9J0kL' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'X-AUTH-KEY: 1a2b3c4d5e6f7g8h9i0j' \
    -d '{
          "custom_payment_id": "742",
          "custom_store_reference": "abc",
          "callback_data": "example data",
          "customer": {
            "name": "John Smit",
            "email": "john.smit@hotmail.com"
          },
        }'
Success Response (example) 
{
  "success": true,
  "data": {
    "id": "a1B2c3D4e5F6g7H8i9J0kL",
    "status": "unpaid",
    "total": "123.45",
    "currency": "USD",
    "custom_payment_id": "742",
    "custom_store_reference": "abc",
    "callback_data": "example data",
    "customer": {
      "name": "John Smit",
      "email": "john.smit@hotmail.com"
    },
    "payment_details": {
      "currency": null
    },
    "redirect_url": "http:\/\/globee.com\/invoice\/a1B2c3D4e5F6g7H8i9J0kL",
    "success_url": "https:\/\/www.example.com/success",
    "cancel_url": "https:\/\/www.example.com/cancel",
    "ipn_url": "https:\/\/www.example.com/globee/ipn-callback",
    "notification_email": null,
    "confirmation_speed": "medium",
    "expires_at": "2018-01-25 12:31:04",
    "created_at": "2018-01-25 12:16:04"
  }
}
GET/payment-request/{payment_id}

Fetches a previously created payment request by payment_id.

Parameters
Name Value Required Notes
payment_id string Required The payment id that identifies the payment request.
cURL Request (example) 
curl -X GET 'https://globee.com/payment-api/v1/payment-request/a1B2c3D4e5F6g7H8i9J0kL' \
    -H 'Accept: application/json' \
    -H 'X-AUTH-KEY: 1a2b3c4d5e6f7g8h9i0j'
Success Response (example) 
{
  "success": true,
  "data": {
    "id": "a1B2c3D4e5F6g7H8i9J0kL",
    "status": "unpaid",
    "total": "123.45",
    "currency": "USD",
    "custom_payment_id": "742",
    "custom_store_reference": "abc",
    "callback_data": "example data",
    "customer": {
      "name": "John Smit",
      "email": "john.smit@hotmail.com"
    },
    "payment_details": {
      "currency": null
    },
    "redirect_url": "http:\/\/globee.com\/invoice\/a1B2c3D4e5F6g7H8i9J0kL",
    "success_url": "https:\/\/www.example.com/success",
    "cancel_url": "https:\/\/www.example.com/cancel",
    "ipn_url": "https:\/\/www.example.com/globee/ipn-callback",
    "notification_email": null,
    "confirmation_speed": "medium",
    "expires_at": "2018-01-25 12:31:04",
    "created_at": "2018-01-25 12:16:04"
  }
}

Payment Methods

This returns the merchant account's accepted crypto-currencies.

GET/account/payment-methods

Returns the accepted crypto-currencies for your merchant.

cURL Request (example) 
curl -X GET 'https://globee.com/payment-api/v1/account/payment-methods' \
    -H 'Accept: application/json' \
    -H 'X-AUTH-KEY: 1a2b3c4d5e6f7g8h9i0j'
Success Response (example) 
{
  "success": true,
  "data": [
    {
      "id": "BTC",
      "name": "Bitcoin",
      "enabled": true
    },
    {
      "id": "XMR",
      "name": "Monero",
      "enabled": true
    },
    {
      "id": "LTC",
      "name": "Litecoin",
      "enabled": true
    },
    {
      "id": "DOGE",
      "name": "Dogecoin",
      "enabled": false
    },
    {
      "id": "BCH",
      "name": "Bitcoin Cash",
      "enabled": false
    },
    {
      "id": "DCR",
      "name": "Decred",
      "enabled": false
    },
    {
      "id": "LNBT",
      "name": "Bitcoin Lightning",
      "enabled": true
    }
  ]
}

Payment Request Payment Details

This returns the payment details that has already been assigned to the payment request. Optionally the currency id could be provided to only return the details for that currency.

GET/payment-request/{id}/payment-methods

Returns the accepted crypto-currencies and associated address information for the payment-request associated with the given id. If no addresses has been assigned yet, the 'extra' field will be null.

Parameters
Name Value Required Notes
id string Required The payment id that identifies the payment request.
cURL Request (example) 
curl -X GET 'https://globee.com/payment-api/v1/payment-request/a1B2c3D4e5F6g7H8i9J0kL/payment-methods' \
    -H 'Accept: application/json' \
    -H 'X-AUTH-KEY: 1a2b3c4d5e6f7g8h9i0j'
Success Response (example) 
{
  "success": true,
  "data": [
    {
      "id": "BTC",
      "name": "Bitcoin",
      "enabled": true,
      "addresses": {
        "success": true,
        "data": [
          {
            "id": "default",
            "title": "Default",
            "description": null,
            "currency": "BTC",
            "extra": {
              "amount": "0.002089",
              "address": "mgwm4YLsnPaSPfnQ5kdm3URz7ejXKBGxbV",
              "qr_code": "bitcoin:mgwm4YLsnPaSPfnQ5kdm3URz7ejXKBGxbV?amount=0.002089&label=GloBee",
              "ttl": 265
            },
            "link": "/payment-request/2LPzpGjbxdqJbqmw6RZynN/addresses/BTC/default"
          }
        ]
      }
    },
    {
      "id": "XMR",
      "name": "Monero",
      "enabled": true,
      "addresses": {
        "success": true,
        "data": [
          {
            "id": "default",
            "title": "Default",
            "description": null,
            "currency": "XMR",
            "extra": {
              "amount": "0.158232",
              "address": "AABHtMyyHRt1ak1JpjYjR1Ta2tBMGwWK24sAFnhnbnBkcteqhMmVf5e2x8X7vSZ3CTVgYG8RbFiJXCQRTyseAfbkFPN72kpn2ZzL9y2NMP",
              "qr_code": "monero:AABHtMyyHRt1ak1JpjYjR1Ta2tBMGwWK24sAFnhnbnBkcteqhMmVf5e2x8X7vSZ3CTVgYG8RbFiJXCQRTyseAfbkFPN72kpn2ZzL9y2NMP?tx_amount=0.158232&recipient_name=GloBee",
              "ttl": 354
            },
            "link": "/payment-request/2LPzpGjbxdqJbqmw6RZynN/addresses/XMR/default"
          }
        ]
      }
    },
    {
      "id": "LTC",
      "name": "Litecoin",
      "enabled": true,
      "addresses": {
        "success": true,
        "data": [
          {
            "id": "default",
            "title": "Default",
            "description": null,
            "currency": "LTC",
            "extra": null,
            "link": "/payment-request/2LPzpGjbxdqJbqmw6RZynN/addresses/LTC/default"
          }
        ]
      }
    },
    {
      "id": "LNBT",
      "name": "Bitcoin Lightning",
      "enabled": true,
      "addresses": {
        "success": true,
        "data": [
          {
            "id": "default",
            "title": "Lightning Payment Request",
            "description": "Pay using the Lightning Network",
            "currency": "BTC",
            "extra": null,
            "link": "/payment-request/2LPzpGjbxdqJbqmw6RZynN/addresses/LNBT/default"
          },
          {
            "id": "lightning_address",
            "title": "Lightning Node Details",
            "description": "Open a new Lightning Payment Channel with GloBee for faster, cheaper lightning payments.",
            "currency": null,
            "extra": {
              "amount": null,
              "address": "@",
              "qr_code": "@",
              "ttl": null
            },
            "link": "/payment-request/2LPzpGjbxdqJbqmw6RZynN/addresses/LNBT/lightning_address"
          }
        ]
      }
    }
  ]
}
GET/payment-request/{id}/addresses/{currency_id}/{address_id?}

Generates and returns the payment details for a given payment request and payment currency.

Parameters
Name Value Required Notes
id string Required The payment id that identifies the payment request.
currency_id string Required One of the currency id's: BTC, XMR, LTC, DOGE, ETH, XRP, DOT etc.
address_id string Optional The address id if it has been assigned. Examples: 'default', 'lightning_address'.
cURL Request (example) 
curl -X GET 'https://globee.com/payment-api/v1/payment-request/a1B2c3D4e5F6g7H8i9J0kL/addresses/lnbt' \
    -H 'Accept: application/json' \
    -H 'X-AUTH-KEY: 1a2b3c4d5e6f7g8h9i0j'
Success Response (example) 
{
  "success": true,
  "data": {
    "id": "default",
    "title": "Lightning Payment Request",
    "description": "Pay using the Lightning Network",
    "currency": "BTC",
    "extra": {
      "amount": "0.002089",
      "address": "lntb2089u1pdcsrrapp58dm644j0vwm5n2vvfjr2f97uln8dv6ajtm9vaswmjhffyrqk3jpsdq2gakx7sn9v5cqzysxqzuy9uvhyxxkh9whz0m4n6kx9zpe9f9hrxqv7sg3maeh8gvs3mep6lnnclxwkej3vamfzcdhx5kq0lat9vu8ulm7nzdnr44gtzuh6sjrrxsphghnpm",
      "qr_code": "lntb2089u1pdcsrrapp58dm644j0vwm5n2vvfjr2f97uln8dv6ajtm9vaswmjhffyrqk3jpsdq2gakx7sn9v5cqzysxqzuy9uvhyxxkh9whz0m4n6kx9zpe9f9hrxqv7sg3maeh8gvs3mep6lnnclxwkej3vamfzcdhx5kq0lat9vu8ulm7nzdnr44gtzuh6sjrrxsphghnpm",
      "ttl": 900
    },
    "link": "/payment-request/2LPzpGjbxdqJbqmw6RZynN/addresses/LNBT/default"
  }
}
GET/settlements/{id}

Gets settlement details for a payment by an invoice hash

Parameters
Name Value Required Notes
id string Required A hash that identifies an invoice.
cURL Request (example) 
curl -X GET 'https://globee.com/payment-api/v1/settlements/b89rkNdQRWqGNYgaeBX5jx' \
    -H 'Accept: application/json' \
    -H 'X-AUTH-KEY: 1a2b3c4d5e6f7g8h9i0j'
Success Response (example) 
{
  "success": true,
  "data": [
    {
      "transaction_id": "cd2ff5c7d9859e10640b2832be1cc468ff8b94e59801d51a3ebf4b04a49fe525",
      "address": "14wYG2m5MuGyYHVQXLqzSfHWGbv511ckMW",
      "crypto_amount": "0.001397",
      "currency": "Bitcoin"
    },
    {
      "transaction_id": "5ff94377247d1e6fbe2ba1a98d588f9ef0b69f5240c1b28f31e99a174e788c4c",
      "address": "42ghRRZQqP7Wp3zXouRD8gHYhEhkwNfbZDZw6MAHcW9yWwRSaHXmfChZQc1HbjbUAqdEmgQh2QAAWbWTeMRNPYbULjJ99kk",
      "crypto_amount": "0.06539382",
      "currency": "Monero"
    }
  ]
}

# Callback IPN (Instant Payment Notification)

If you provide a ipn_url when creating a payment-request, our system will POST a response to that URL upon successful payment of a payment-request.

The body of this post will be a json object containing the following fields: 

{
  "data": {
    "id": "a1B2c3D4e5F6g7H8i9J0kL",
    "status": "paid",
    "total": "123.45",
    "currency": "USD",
    "custom_payment_id": "742",
    "callback_data": "example data",
    "customer": {
      "name": "John Smit",
      "email": "john.smit@hotmail.com"
    },
    "payment_details": {
      "currency": "BTC"
    },
    "redirect_url": "http:\/\/globee.com\/invoice\/a1B2c3D4e5F6g7H8i9J0kL",
    "success_url": "https:\/\/www.example.com/success",
    "cancel_url": "https:\/\/www.example.com/cancel",
    "ipn_url": "https:\/\/www.example.com/globee/ipn-callback",
    "notification_email": null,
    "confirmation_speed": "medium",
    "expires_at": "2018-01-25 12:31:04",
    "created_at": "2018-01-25 12:16:04"
  }
}