NAV Navbar
Logo
HTTP cURL

Introduction

Bitspark is the pioneer of the worlds first cash in, cash out Blockchain powered remittance platform that enables Money Transfer Operators (MTOs) and Individuals to send money quicker, cheaper and to more destinations than ever before.

The Bitspark API is designed for anyone to leverage Bitspark’s many payment destinations and methods - particularly in countries and areas traditionally under-served by existing payment channels and integrate easily into whatever product or service you intend to build with it.

General

URL

http://api.bitspark.io

Authentication

Bitspark uses API keys to allow access to the API. You can generate your keys at our API page.

Bitspark expects for the Key and Sign to be included in all auth API requests to the server in a Headers that looks like the following:

Headers

REQUEST

GET /v1/call_example HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "http://api.bitspark.io/v1/call_example" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE (fail)

{
  "errors": [
    {
      "code": 401,
      "error_code": "request_unauthorized",
      "message": [
        "Unauthorized"
      ]
    }
  ]
}
Key Value Description
Key YOUR_API_KEY Your personal API-KEY length of 40 hex characters.
Sign COMPUTED_HMAC Genarated with your API-SECRET HMAC-SHA512 Signature in Hex format.

Signature

You can use some programming language to generate HMAC signature:
Ruby example:

# ----- URL encoding -----
require 'cgi'
require 'openssl'

class String
  def to_query(key)
    "#{CGI.escape(key.to_s)}=#{CGI.escape(to_s)}"
  end
end
class Hash
  def to_query(namespace = nil)
    collect do |key, value|
      unless (value.is_a?(Hash) || value.is_a?(Array)) && value.empty?
        value.to_query(namespace ? "#{namespace}[#{key}]" : key)
      end
    end.compact.sort! * '&'
  end
end

def calculate_hmac(api_secret, data)
  OpenSSL::HMAC.new(api_secret, OpenSSL::Digest::SHA512.new).update(data).to_s
end
# ----- URL encoding -----

api_secret = 'your_api_secret'
request_url = 'http://api.bitspark.io/v1/call_example?attribute=value1&attributes[attribute]=v@lue'
encoded_form_data = ''

# ----- POST requests only -----
form_data = {
  attribute: 'value',
  attributes: {
    attribute: 'v@lue'
  }
}

encoded_form_data = form_data.to_query # => "attribute=value&attributes%5Battribute%5D=v%40lue"
# ----- POST requests only  -----

calculate_hmac(api_secret, encoded_form_data + request_url)
# => "bb4882ac67b7815b4bf36b1fa99d95c95237db21353b95873fff008e76c2c204
#     95d746ae47cedf766d8cf6ee72eab25bac7972d3ebf397a84586e0fb0f371306"

# OR vice versa, both are correct
calculate_hmac(api_secret, request_url + encoded_form_data)
# => "64110ab16e3efed24e2f7bdd11c3682c477b09e9d38dcc7438d2ea15cc895134
#     4990ad5301748c60c64489ca463ad526d50aa75230846a3898554f8b8f4d98f1"

To generate COMPUTED_HMAC follow next steps:

http://api.bitspark.io/v1/call_example

http://api.bitspark.io/v1/call_example?attribute=value1&attributes[attribute]=v@lue

Key Value Encoded key-value pairs
attribute value attribute=value
attributes[attribute] v@lue attributes%5Battribute%5D=v%40lue

attribute=value&attributes%5Battribute%5D=v%40lue

attribute=value&attributes%5Battribute%5D=v%40luehttp://api.bitspark.io/v1/call_example?attribute=value1&attributes[attribute]=v@lue

OR this:

http://api.bitspark.io/v1/call_example?attribute=value1&attributes[attribute]=v@lueattribute=value&attributes%5Battribute%5D=v%40lue

Postman

This pre-request script allows you easily generate COMPUTED_HMAC and use it for all authenticated API requests.

function toHex(str) {
    var hex = encodeURIComponent(str);
    hex = hex.replace(/!/, '%21')
             .replace("'", '%27')
             .replace('(', '%28')
             .replace(')', '%29')
             .replace('*', '%2A')
             .replace('~', '%7E')
             .replace(/%20/g, '+');
    return hex;
}

function parseParams(params) {
    var result = "";
    for (var key in params) {
        if (result !== '') {
            result += "&";
        }
        result += encodeURI(key) + "=" + toHex(params[key]);
    }
    return alphabeticalSort(result);
}

function alphabeticalSort(str) {
    return str.split('&').sort().join('&');
}

function generateAuthSign(request, secret) {
    if (request.method == 'GET' || !request.data) {
        request.data = ''; 
    } else {
        request.data = parseParams(request.data);
    }

    var requestData = [request.url, request.data].join('');
    return CryptoJS.HmacSHA512(requestData, secret).toString();
}

SECRET_KEY = pm.request.headers.find(header => header.key == 'Secret').value;
pm.environment.set("SIGNATURE", generateAuthSign(request, SECRET_KEY));

To simplify API using you can import Postman Bitspark Public Collection:

Key, Secret and Sign should be included in all authenticated API requests to the server in a Headers that look like the following:

Key Value Description
Key YOUR_CLIENT_API_KEY Your personal API-KEY length of 40 hex characters.
Secret YOUR_SECRET_API_KEY Your personal SECRET-KEY length of 40 hex characters.
Sign {{SIGNATURE}} Genarated with your API-SECRET HMAC-SHA512 Signature in Hex format.
Already defined by pre-request script

Pagination

REQUEST

GET /v1/call_example?pagination[offset]=1&pagination[limit]=20 HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET "http://api.bitspark.io/v1/call_example?pagination[offset]=1&pagination[limit]=20"
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "call_examples",
      "attributes": {
        "attribute": "string",
        "empty": null
      }
    },
    "..."
  ],
  "meta": {
    "total_count": 100,
    "total_pages": 5,
    "prev_page": null,
    "next_page": 2
  }
}

REQUEST PARAMS

Key Required Type Default Description
pagination[offset] true [integer] 1 Number of current page
pagination[limit] false [integer] 20 Number of records per pages

RESPONSE DETAILS

Key Type Description
total_count [integer] Total count of all records
total_pages [integer] Total count of pages
prev_page [integer] Number of previous page ( returns null if there is no previous page )
next_page [integer] Number of next page ( returns null if there is no next page )

Public

Money Shops

All Money Shops

REQUEST

GET /v1/money_shops?location[lat]=40.7143528&location[lng]=-74.0059731 HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/money_shops?location[lat]=40.7143528&location[lng]=-74.0059731" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "money_shops",
      "attributes": {
        "name": "Company Name One",
        "address": "350 5th Ave, New York, NY 10118, USA",
        "lat": 40.7484401,
        "lng": -73.9856639,
        "image_url": "https://bitspark-upload-staging.s3.amazonaws.com/uploads/profile/image/ffffffff-ffff-ffff-ffff-ffffffffffff/image.jpg",
        "distance": "2.8389379740525107"
      }
    },
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "money_shops",
      "attributes": {
        "name": "Company Name Two",
        "address": "183 Queen's Rd E, Wan Chai, Hong Kong",
        "lat": 22.2744158,
        "lng": 114.1711181,
        "image_url": null,
        "distance": "2.8389379740525107"
      }
    },
    "..."
  ]
}

ENDPOINT

/money_shops

DESCRIPTION

This endpoint retrieves all money shops sorted by distance to your location. If location is not specified, it is sorted by distance to Hong Kong.

REQUEST PARAMS

Key Required Type Default Description
location[lat] false [decimal] 22.2799146 Latitude coordinate of your location
location[lng] false [decimal] 114.1715395 Longitude coordinate of your location

RESPONSE DETAILS

Key Type Description
name [string] Money shop company name
address [string] Money shop adress
lat [decimal] Latitude coordinate of money shop location
lng [decimal] Longitude coordinate of money shop location
image_url [string] URL to money shop image
distance [decimal] distance between shop location and your location (in kilometers)

Specific Money Shop

REQUEST

GET /v1/money_shops/ffffffff-ffff-ffff-ffff-ffffffffffff HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/money_shops/ffffffff-ffff-ffff-ffff-ffffffffffff" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "money_shops",
    "attributes": {
      "name": "Company Name One",
      "address": "350 5th Ave, New York, NY 10118, USA",
      "lat": 40.7484401,
      "lng": -73.9856639,
      "image_url": "https://bitspark-upload-staging.s3.amazonaws.com/uploads/profile/image/ffffffff-ffff-ffff-ffff-ffffffffffff/image_one.jpg",
      "topup_commissions": [
        {
          "currency": "HKD",
          "fee": "0.0"
        },
        {
          "currency": "USD",
          "fee": "1.1"
        },
        "..."
      ]
    }
  }
}

ENDPOINT

/money_shops/:money_shop_id

DESCRIPTION

This endpoint retrieves a specific money shop.

RESPONSE DETAILS

Key Type Description
name [string] Money shop company name
address [string] Money shop adress
lat [decimal] Latitude coordinate of money shop location
lng [decimal] Longitude coordinate of money shop location
image_url [string] URL to money shop image
topup_commissions [array of hashes] Top up commissions of this shop for every available currencies
topup_commissions[][currency] [string] Commission currency code
topup_commissions[][fee] [decimal] Commision amount of money

Destinations

Available Destinations

REQUEST

GET /v1/static/destination_data?include=destination_info HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/static/destination_data?include=destination_info" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "destinations",
      "attributes": {
        "code": "destination_code",
        "name": "Destination Name",
        "currency_name": "PHP",
        "available": true,
        "fields": [
          "province",
          "provider",
          "validations",
          "delivery_method"
        ]
      },
      "relationships": {
        "destination_info": {
          "data": {
            "id": "destination_code",
            "type": "destination_infos"
          }
        }
      }
    },
    "..."
  ],
  "included": [
    {
      "id": "destination_code",
      "type": "destination_infos",
      "attributes": {
        "provinces": [
          {
            "name": "Province Name",
            "delivery_methods": [
              "delivery_method_code",
              "..."
            ],
            "code": "province_code"
          },
          "..."
        ],
        "delivery_methods": [
          {
            "name": "Delivery Method Name",
            "providers": [
              "provider_code_one",
              "..."
            ],
            "code": "delivery_method_code"
          },
          "..."
        ],
        "providers": [
          {
            "name": "Provider Name",
            "code": "provider_code"
          },
          "..."
        ]
      }
    },
    "..."
  ]
}

ENDPOINT

/static/destination_data

DESCRIPTION

This endpoint retrieves all available destinations with all info about it.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Set it to destination_info to include detailed destination data

RESPONSE DETAILS

Key Type Description
code [string] Destination name code
name [string] Destination name
currency_name [string] Destination currency name
available [boolean] Returns true if destination available, so always returns true
fields [array] List of required fields for validations
relationships[destination_info][provinces] [array of hashes] List of all available provinces with delivery_methods
relationships[destination_info][delivery_methods] [array of hashes] List of all available delivery_methods with providers
relationships[destination_info][providers] [array of hashes] List of all available providers
relationships[destination_info][account_types] [array of hashes] List of all available bank account types for this Destinaiton

Currencies

Available Currencies

REQUEST

GET /v1/static/currencies HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/static/currencies" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "currencies",
      "attributes": {
        "code": "hkd",
        "name": "HKD",
        "account": true,
        "currency_type": "banknote",
        "banknote": true,
        "bitspark_deposit_credentials": {
          "iban": "CZ8801000001152130170277",
          "bank_name": "Komercni Banka, a.s.",
          "reference": "9120255451",
          "swift_code": "KOMBCZPP",
          "bank_address": "Na Prikope 33 cp. 969 114 07 Praha 1",
          "account_number": "",
          "beneficiary_name": "Valoris HK Limited",
          "account_holder_address": "5- 109 Argyle Street Richmond Commercial , Kowloon, 00000, Hong Kong"
        },
        "precision": 2
      }
    },
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "currencies",
      "attributes": {
        "code": "usd",
        "name": "USD",
        "account": true,
        "currency_type": "banknote",
        "banknote": true,
        "bitspark_deposit_credentials": {},
        "precision": 2
      }
    },
    "..."
  ]
}

ENDPOINT

/static/currencies

DESCRIPTION

This endpoint retrieves all available currencies.

RESPONSE DETAILS

Key Type Description
code [string] Currency name code
name [string] Currency name
account [boolean] Returns true if currency available, so always returns true
currency_type [string] Specifies currency type. Can be cryptocurrency or banknote.
banknote [boolean] Returns true if currency is of banknote type.
bitspark_deposit_credentials [hash] Returns Bitspark deposit credentials for this currency
precision [integer] Currency precision

Send Money Info

Validation Rules

REQUEST

GET /v1/static/validation_rules?filter[destination]=ffffffff-ffff-ffff-ffff-ffffffffffff&filter[province]=province_code&filter[delivery_method]=delivery_method_code&filter[provider]=provider_code HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/static/validation_rules?filter[destination]=ffffffff-ffff-ffff-ffff-ffffffffffff&filter[province]=province_code&filter[delivery_method]=delivery_method_code&filter[provider]=provider_code" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "1",
      "type": "fields_data",
      "attributes": {
        "object_type": "transfer",
        "level": "level_code",
        "code": "bank",
        "dependency_levels": [
          {
            "destinations": [
              "ffffffff-ffff-ffff-ffff-ffffffffffff"
            ]
          },
          {
            "delivery_methods": [
              "delivery_method_code"
            ]
          }
        ],
        "lower_levels": [
          "lower_level_code"
        ],
        "fields_info": {
          "validation_rules": [
            {
              "field": "field_name",
              "data": {
                "required": true,
                "decimal": true,
                "integer": true,
                "minvalue": 100
              }
            },
            {
              "field": "relation.field_name",
              "data": {
                "letters": true,
                "phone": true,
                "email": true
              }
            },
            "..."
          ],
          "possible_fields": [
            "field_name",
            "relation.field_name",
            "..."
          ],
          "required_fields": [
            "field_name",
            "..."
          ]
        }
      }
    },
    "..."
  ]
}

ENDPOINT

/static/validation_rules

DESCRIPTION

This endpoint retrieves validation rules for Send Money endpoint.

REQUEST PARAMS

Key Required Type Default Description
filter[destination] false [string] none Destination ID
filter[province] false [string] none Province code
filter[delivery_method] false [string] none Delivery method code
filter[provider] false [string] none Provider code

RESPONSE DETAILS

Key Type Description
object_type [string] Validation object type, "transfer" in this case
level [string] Validation level code (can be one of: "destinations", "providers", "delivery_methods")
code [string] Delivery method code (can be one of: "pickup", "bank", "")
dependency_levels [array of hashes] Validation dependency levels ( can be an empty array [])
dependency_levels[][destinations] [array] List of destination IDs
dependency_levels[][delivery_methods] [array] List of delivery method codes
lower_levels [array of strings] Validation dependency levels ( can be one of: [], ["delivery_methods"], ["providers"])
fields_info [hash] Validation info for each Send Money form-data field
fields_info[possible_fields] [array of strings] Possible form-data fields for Send Money endpoint
fields_info[required_fields] [array of strings] Required form-data fields for Send Money endpoint
fields_info[validation_rules] [array of hashes] Validation rules for each Send Money form-data field
fields_info[validation_rules][field] [string] Field name, can be a field of ralation (with dot)
fields_info[validation_rules][data] [hash] Actual validation rules of form-data field, can be any subhash of next key-value pairs
fields_info[validation_rules][data][required] [boolean] Returns true if field is required
fields_info[validation_rules][data][decimal] [boolean] Returns true if field must be decimal format
fields_info[validation_rules][data][integer] [boolean] Returns true if field must be integer format
fields_info[validation_rules][data][minvalue] [integer] Returns minimum value for decimal or integer fields
fields_info[validation_rules][data][letters] [boolean] Returns true if field must be include only letters
fields_info[validation_rules][data][phone] [boolean] Returns true if field must be phone format
fields_info[validation_rules][data][email] [boolean] Returns true if field must be email format

Amount to Pay

REQUEST

GET /v1/static/amount_to_pay?account_currency=usd&transfer[amount]=11.11&transfer[destination_id]=ffffffff-ffff-ffff-ffff-ffffffffffff&transfer[delivery_method]=delivery_method_code&transfer[provider]=provider_code&transfer[province]=province_code HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/static/amount_to_pay?account_currency=usd&transfer[amount]=11.11&transfer[destination_id]=ffffffff-ffff-ffff-ffff-ffffffffffff&transfer[delivery_method]=delivery_method_code&transfer[provider]=provider_code&transfer[province]=province_code" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": {
    "id": "99999999999999",
    "type": "payment_data",
    "attributes": {
      "total_amount_to_pay": 0.99,
      "transaction_fee": 0.0
    }
  }
}

ENDPOINT

/static/amount_to_pay

DESCRIPTION

This endpoint retrieves precalculated amount to pay for Send Money endpoint. Please check Authnticated section for similar endpoint with more information.

REQUEST PARAMS

Key Required Type Default Description
account_currency true [string] nope Account currency to calculate amount in ( should be one of Available Currencies codes )
transfer[amount] true [decimal] nope Amount of money to be payed ( should be greater than 0.0)
transfer[destination_id] true [uuid] nope Destination ID for send money to
transfer[delivery_method] false [string] nope Delivery method code
transfer[provider] false [string] nope Provider code
transfer[province] false [string] nope Province code

RESPONSE DETAILS

Key Type Description
total_amount_to_pay [decimal] Total amount to pay
transaction_fee [decimal] transaction fee

Authenticated

Personal Info

Account

REQUEST

GET /v1/accounts/me?account_currency=usd&include=currency HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/accounts/me?account_currency=usd&include=currency" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE (success)

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "accounts",
    "attributes": {
      "balance": "0.0",
      "shop_commission": "0.0",
      "balance_threshold": "0.0"
    },
    "relationships": {
      "currency": {
        "data": {
          "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
          "type": "currencies"
        }
      }
    }
  },
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "currencies",
      "attributes": {
        "code": "usd",
        "name": "USD",
        "account": true,
        "currency_type": "banknote",
        "banknote": true,
        "bitspark_deposit_credentials": {
          "iban": "CZ8801000001152130170277",
          "bank_name": "Komercni Banka, a.s.",
          "reference": "9120255451",
          "swift_code": "KOMBCZPP",
          "bank_address": "Na Prikope 33 cp. 969 114 07 Praha 1",
          "account_number": "",
          "beneficiary_name": "Valoris HK Limited",
          "account_holder_address": "5- 109 Argyle Street Richmond Commercial , Kowloon, 00000, Hong Kong"
        },
        "precision": 2
      }
    }
  ]
}

RESPONSE (fail)

{
  "errors": [
    {
      "code": 400,
      "error_code": "bad_request",
      "message": [
        "Invalid Account Currency"
      ]
    }
  ]
}

ENDPOINT

/accounts/me

DESCRIPTION

This endpoint retrieves info about one of your accounts.

REQUEST PARAMS

Key Required Type Default Description
account_currency true [string] none Currency of account you want to retrieve ( should be one of Available Currencies codes )
include false [string] none Set it to currency to include currency info

RESPONSE DETAILS

Key Type Description
balance [decimal] Account balance
shop_commission [decimal] Shop commission
balance_threshold [decimal] Balance threshold
relationships[currency][code] [string] Account currency name
relationships[currency][name] [string] Account currency code
relationships[currency][account] [boolean] Returns true if currency available
relationships[currency][currency_type] [string] currency_type
relationships[currency][banknote] [boolean] Returns true if currency is of banknote type.
relationships[currency][bitspark_deposit_credentials] [hash] Returns Bitspark deposit credentials for this currency
relationships[currency][precision] [integer] Currency precision

Update Account

REQUEST

PUT /v1/accounts/cccccccc-cccc-cccc-cccc-cccccccccccc HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
data%5Battributes%5D%5Bshop_commission%5D=0.0data%5Battributes%5D%5Bbalance_threshold%5D=0.0
curl -X PUT "https://api.bitspark.io/v1/accounts/cccccccc-cccc-cccc-cccc-cccccccccccc" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'data%5Battributes%5D%5Bshop_commission%5D=0.0&data%5Battributes%5D%5Bbalance_threshold%5D=0.0'

RESPONSE (success)

{
  "data": {
    "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
    "type": "accounts",
    "attributes": {
      "balance": "1234.5678",
      "shop_commission": "0.0",
      "balance_threshold": "0.0"
    },
    "relationships": {
      "currency": {
        "data": {
          "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
          "type": "currencies"
        }
      }
    }
  }
}

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "Account can't be blank",
        "Balance threshold is not a number",
        "Shop commission is not a number"
      ]
    }
  ]
}

ENDPOINT

/accounts/:id

DESCRIPTION

This endpoint updates account.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Can be any subset of: currency

FORM DATA

Key Required Type Default Description
data[attributes][shop_commission] false [decimal] Additional commission that will be applied to Top Up and Send Money ( should be greater than or equal to 0.0)
data[attributes][balance_threshold] false [decimal] Indicator of low balance ( should be greater than or equal to 0.0). It will send email notification when account.balance < account balance_threshold. Disabled when equal to 0.0.

Profile

REQUEST

GET /v1/users/me?include=profile.identity_document,active_account.currency HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/users/me?include=profile.identity_document,active_account.currency" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE (success)

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "users",
    "attributes": {
      "login": "your@email.example"
    },
    "relationships": {
      "profile": {
        "data": {
          "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
          "type": "profiles"
        }
      },
      "active_account": {
        "data": {
          "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
          "type": "accounts"
        }
      }
    },
    "links": {
      "self": "http://api.bitspark.io/v1/users/me"
    }
  },
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "profiles",
      "attributes": {
        "first_name": "First",
        "middle_name": "mid",
        "last_name": "Last",
        "residence_country": "CHN",
        "contact_number": "+123456789012",
        "company_name": "Company One",
        "address": "350 5th Ave, New York, NY 10118, USA",
        "referral_code": "000",
        "reference_code": "000",
        "show_on_map": true,
        "image": {
          "image": {
            "url": "/uploads/profile/image/eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee/eee.jpg",
            "thumb": {
              "url": "/uploads/profile/image/eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee/thumb_eee.jpg"
            },
            "avatar": {
              "url": "/uploads/profile/image/eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee/avatar_eee.jpg"
            }
          }
        },
      },
      "relationships": {
        "identity_document": {
          "data": {
            "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
            "type": "identity_documents"
          }
        }
      }
    },
    {
      "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
      "type": "identity_documents",
      "attributes": {
        "id_number": "123456789",
        "value": "id_card",
        "proof_url": "https://bitspark-upload-staging.s3.amazonaws.com/uploads/profile/proof/eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee/proof.jpg",
        "approved": false
      }
    },
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "accounts",
      "attributes": {
        "balance": "0.0",
        "shop_commission": "0.0",
        "balance_threshold": "0.0"
      },
      "relationships": {
        "currency": {
          "data": {
            "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
            "type": "currencies"
          }
        }
      }
    },
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "type": "currencies",
      "attributes": {
        "code": "hkd",
        "name": "HKD",
        "account": true,
        "currency_type": "banknote",
        "banknote": true,
        "bitspark_deposit_credentials": {
          "iban": "CZ8801000001152130170277",
          "bank_name": "Komercni Banka, a.s.",
          "reference": "9120255451",
          "swift_code": "KOMBCZPP",
          "bank_address": "Na Prikope 33 cp. 969 114 07 Praha 1",
          "account_number": "",
          "beneficiary_name": "Valoris HK Limited",
          "account_holder_address": "5- 109 Argyle Street Richmond Commercial , Kowloon, 00000, Hong Kong"
        },
        "precision": 2
      }
    }
  ]
}

ENDPOINT

/users/me

DESCRIPTION

This endpoint retrieves info about your profile.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Can be any subset of: profile, profile.identity_document, active_account, active_account.currency

RESPONSE DETAILS

Key Type Description
login [string] Your login ( can be email or contact_number)
relationships[profile][first_name] [string] Your first name
relationships[profile][middle_name] [string] Your middle name
relationships[profile][last_name] [string] Your last name
relationships[profile][residence_country] [string] Your residence country ( should be one of ISO 3166-1 ALPHA-3 country codes )
relationships[profile][contact_number] [string] Your contact number
relationships[profile][company_name] [string] Your company name
relationships[profile][address] [string] Your address
relationships[profile][referral_code] [string] Referral Code
relationships[profile][reference_code] [string] Reference Code
relationships[profile][show_on_map] [boolean] Show on map
relationships[profile][image] [hash] Profile image
relationships[identity_document][id_number] [string] Your ID number
relationships[identity_document][value] [string] Your ID type ( can be id_card or passport)
relationships[identity_document][proof_url] [string] URL to your ID proof
relationships[identity_document][approved] [boolean] Returns true if document approved by admin
relationships[active_account][balance] [decimal] Account balance
relationships[active_account][shop_commission] [decimal] Shop commission
relationships[active_account][balance_threshold] [decimal] Balance threshold
relationships[currency][code] [string] Account currency name
relationships[currency][name] [string] Account currency code
relationships[currency][account] [boolean] Returns true if currency available
relationships[currency][currency_type] [string] currency_type
relationships[currency][banknote] [boolean] Returns true if currency is of banknote type.
relationships[currency][bitspark_deposit_credentials] [hash] Returns Bitspark deposit credentials for this currency
relationships[currency][precision] [integer] Currency precision

Update Profile

REQUEST

POST /v1/users HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
data%5Btype%5D=profilesdata%5Battributes%5D%5Bfirst_name%5D=Firstdata%5Battributes%5D%5Blast_name%5D=Lastdata%5Brelationships%5D%5Bidentity_document%5D%5Bdata%5D%5Btype%5D=identity_documentsdata%5Brelationships%5D%5Bidentity_document%5D%5Bdata%5D%5Battributes%5D%5Bvalue%5D=passportdata%5Brelationships%5D%5Buser%5D%5Bdata%5D%5Btype%5D=usersdata%5Brelationships%5D%5Buser%5D%5Bdata%5D%5Battributes%5D%5Bcurrent_password%5D=12345678
curl -X POST "https://api.bitspark.io/v1/users" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'data%5Btype%5D=profiles&data%5Battributes%5D%5Bfirst_name%5D=First&data%5Battributes%5D%5Blast_name%5D=Last&data%5Brelationships%5D%5Bidentity_document%5D%5Bdata%5D%5Btype%5D=identity_documents&data%5Brelationships%5D%5Bidentity_document%5D%5Bdata%5D%5Battributes%5D%5Bvalue%5D=passport&data%5Brelationships%5D%5Buser%5D%5Bdata%5D%5Btype%5D=users&data%5Brelationships%5D%5Buser%5D%5Bdata%5D%5Battributes%5D%5Bcurrent_password%5D=12345678'

RESPONSE is the same as for Profile with all included data

ENDPOINT

/users

DESCRIPTION

With this endpoint you can update your profile info.

FORM DATA

Key Required Type Description
data[type] true [string] Profile’s type ( must be profiles)
data[attributes][first_name] true [string] Your first name
data[attributes][middle_name] false [string] Your middle name
data[attributes][last_name] true [string] Your last name
data[attributes][residence_country] false [string] Your residence country ( should be one of ISO 3166-1 ALPHA-3 country codes )
data[attributes][contact_number] false [string] Your contact number
data[attributes][company_name] false [string] Your company name
data[attributes][currency_id] false [string] Account currency ID ( should be one of Available Currencies ID’s )
data[attributes][address] false [string] Your address
data[relationships][identity_document][data][type] true [string] Identity Document’s type ( must be identity_documents)
data[relationships][identity_document][data][attributes][id_number] false [string] Your ID number
data[relationships][identity_document][data][attributes][value] true [string] Your ID type ( should be one of: id_card, passport)
data[relationships][identity_document][data][attributes][proof] false [file] Your ID proof ( file should be one of next types: jpg, jpeg, gif, png, bmp, pdf)
data[relationships][user][data][type] true [string] User’s type ( must be users)
data[relationships][user][data][attributes][current_password] true [string] Your current password
data[relationships][user][data][attributes][password] false [string] New password
data[relationships][user][data][attributes][password_confirmation] false [string] New password confirmation

RESPONSE DETAILS

Detailed amount to pay

Amount to Pay V2

REQUEST

GET /v2/static/amount_to_pay?account_currency=usd&transfer[amount]=11.11&transfer[destination_id]=ffffffff-ffff-ffff-ffff-ffffffffffff&transfer[delivery_method]=delivery_method_code&transfer[provider]=provider_code&transfer[province]=province_code HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET \
  'https://api.bitspark.io/v2/static/amount_to_pay?account_currency=usd&transfer[amount]=11.11&transfer[amount_to_send]=11.11&transfer[destination_id]=1' \
  -H 'Key: YOUR_CLIENT_KEY' \
  -H 'Secret: YOUR_SECRET_KEY' \
  -H 'Sign: SIGN' \
  -H 'cache-control: no-cache'

RESPONSE

{
  "data": {
    "id": "99999999999999",
    "type": "payment_data",
    "attributes": {
      "total_amount_to_pay": 0.99,
      "transaction_fee": 0.0
    }
  }
}

ENDPOINT

/v2/static/amount_to_pay

DESCRIPTION

This endpoint retrieves precalculated amount to pay for Send Money endpoint.

REQUEST PARAMS

Key Required Type Default Description
account_currency true [string] nope Account currency to calculate amount in ( should be one of Available Currencies codes )
transfer[amount] true [decimal] nope Amount of money to be payed ( should be greater than 0.0)
transfer[amount_to_send] true [decimal] nope Amount of money that user wants to transact in user currency
transfer[destination_id] true [uuid] nope Destination ID for send money to
transfer[delivery_method] false [string] nope Delivery method code
transfer[provider] false [string] nope Provider code
transfer[province] false [string] nope Province code

RESPONSE DETAILS

Key Type Description
total_amount_to_pay_in_user_currency [decimal] Total amount to pay as is in user currency
total_amount_to_pay_in_destination_currency [decimal] Total amount to pay as is in destination currency
transaction_fee_in_user_currency [decimal] Transaction fee as is in user currency
transaction_fee_in_destination_currency [decimal] Transaction fee as is in destination currency

Amount to Pay V3

REQUEST

GET /v3/calculations/amount_to_pay/calculate?account_currency=usd&transfer[amount]=11.11&transfer[destination_id]=ffffffff-ffff-ffff-ffff-ffffffffffff&transfer[delivery_method]=delivery_method_code&transfer[provider]=provider_code&transfer[province]=province_code HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET \
  'https://api.bitspark.io/v3/calculations/amount_to_pay/calculate?account_currency=usd&transfer[amount]=11.11&transfer[destination_id]=ffffffff-ffff-ffff-ffff-ffffffffffff' \
  -H 'Key: YOUR_CLIENT_KEY' \
  -H 'Secret: YOUR_SECRET_KEY' \
  -H 'Sign: SIGN' \
  -H 'cache-control: no-cache'

RESPONSE

{
  "data": {
    "id": "99999999999999",
    "type": "payment_data",
    "attributes": {
      "total_amount_to_pay_in_user_currency": 1.0093194576974538,
      "total_amount_to_pay_in_destination_currency": 1225.5806007651602,
      "transaction_fee_in_user_currency": 0.00004574786500381053,
      "transaction_fee_in_destination_currency": 0.05555,
      "payment_service_fee_in_destination_currency": 0.15073492500000008,
      "payment_service_fee_in_user_currency": 0.00012413683168783994,
      "destination_amount": 11.11
    }
  }
}

ENDPOINT

/v3/calculations/amount_to_pay/calculate

DESCRIPTION

This endpoint retrieves precalculated amount to pay for Send Money endpoint.

REQUEST PARAMS

Key Required Type Default Description
account_currency true [string] nope Account currency to calculate amount in ( should be one of Available Currencies codes )
transfer[amount] true [decimal] nope Amount of money to be payed ( should be greater than 0.0)
transfer[amount_to_send] false [decimal] nope Amount of money that user wants to transact in user currency
transfer[destination_id] true [uuid] nope Destination ID for send money to
transfer[delivery_method] false [string] nope Delivery method code
transfer[provider] false [string] nope Provider code
transfer[province] false [string] nope Province code

RESPONSE DETAILS

Key Type Description
total_amount_to_pay_in_user_currency [decimal] Total amount to pay as is in user currency
total_amount_to_pay_in_destination_currency [decimal] Total amount to pay as is in destination currency
transaction_fee_in_user_currency [decimal] Transaction fee as is in user currency
transaction_fee_in_destination_currency [decimal] Transaction fee as is in destination currency
payment_service_fee_in_destination_currency [decimal] Transaction cable fee as is in destination currency
payment_service_fee_in_user_currency [decimal] Transaction cable fee as is in destination currency
destination_amount [decimal] Amount to be sent to destination point

Amount to Pay V4

REQUEST

GET /v4/calculations/amount_to_pay/calculate?account_currency=usd&transfer[amount]=11.11&transfer[destination_id]=ffffffff-ffff-ffff-ffff-ffffffffffff&transfer[delivery_method]=delivery_method_code&transfer[provider]=provider_code&transfer[province]=province_code HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET \
  'https://api.bitspark.io/v4/calculations/amount_to_pay/calculate?account_currency=usd&transfer[amount]=11.11&transfer[amount_to_send]=11.11&transfer[destination_id]=ffffffff-ffff-ffff-ffff-ffffffffffff' \
  -H 'Key: YOUR_CLIENT_KEY' \
  -H 'Secret: YOUR_SECRET_KEY' \
  -H 'Sign: SIGN' \
  -H 'cache-control: no-cache'

RESPONSE

{
  "data": {
    "id": "99999999999999",
    "type": "payment_data",
    "attributes": {
      "total_amount_to_pay_in_user_currency": 1.0093448333521935,
      "total_amount_to_pay_in_destination_currency": 1222.283297230666,
      "transaction_fee_in_user_currency": 0.00004587243040934162,
      "transaction_fee_in_destination_currency": 0.05555,
      "payment_service_fee_in_destination_currency": 0.15073492500000008,
      "payment_service_fee_in_user_currency": 0.00012447483991574854,
      "destination_amount": 11.11,
      "limits_info": "5 000 000 IDR per day"
    }
  }
}

ENDPOINT

/v4/calculations/amount_to_pay/calculate

DESCRIPTION

This endpoint retrieves precalculated amount to pay for Send Money endpoint.

REQUEST PARAMS

Key Required Type Default Description
account_currency true [string] nope Account currency to calculate amount in ( should be one of Available Currencies codes )
transfer[amount] true [decimal] nope Amount of money to be payed ( should be greater than 0.0)
transfer[amount_to_send] true [decimal] nope Amount of money that user wants to transact in user currency
transfer[destination_id] true [uuid] nope Destination ID for send money to
transfer[delivery_method] false [string] nope Delivery method code
transfer[provider] false [string] nope Provider code
transfer[province] false [string] nope Province code

RESPONSE DETAILS

Key Type Description
total_amount_to_pay_in_user_currency [decimal] Total amount to pay as is in user currency
total_amount_to_pay_in_destination_currency [decimal] Total amount to pay as is in destination currency
transaction_fee_in_user_currency [decimal] Transaction fee as is in user currency
transaction_fee_in_destination_currency [decimal] Transaction fee as is in destination currency
payment_service_fee_in_destination_currency [decimal] Transaction cable fee as is in destination currency
payment_service_fee_in_user_currency [decimal] Transaction cable fee as is in destination currency
destination_amount [decimal] Amount to be sent to destination point
limits_info [string] Provider_limits_info

Fees

DESCRIPTION

Fees is used in system for calculating commission per transaction. Currently supported transaction types are deposit, withdaw, top_up.

Each transaction type has specific fees which also can be global or individual per user.

User can set only individual fees, global fees set by admin. Currently it makes sense to set individual fee for top_up as it will be profit for top_up agent user. Also there is commission profit split(by default 50%) with Bitspark and top_up agent user.

A percentage type fees calculates commission as percentage of transaction amount.

Base commission calculation logic is sum of all active global and individual(that related to user) fees.

All Fees

REQUEST

GET /v1/fees HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/fees" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "fees_top_ups",
      "attributes": {
        "fee_type": "static",
        "from": "0.0",
        "to": "1000000000000000.0",
        "amount": "0.0",
        "active": false,
        "global": true,
        "created_at": "2018-10-16T11:47:25.474Z",
        "updated_at": "2018-10-16T11:47:25.474Z"
      },
      "relationships": {
        "currency": {
          "data": {
            "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
            "type": "currencies"
          }
        },
        "user": {
          "data": null
        }
      }
    },
    "..."
  ]
}

ENDPOINT

/v1/fees

DESCRIPTION

This endpoint retrieves all fees related to your user. Currently supported fees type: TopUp, Deposit, Withdraw.

REQUEST PARAMS

Key Required Type Description
filter[currency] false [string] Can be any of available currencies in system. It is allowed to specify the currency id or code.
filter[active] false [boolean] Can be any true or false. It will return only currently active if true.
filter[fee_model_type] false [string] Can be any one of: Deposit, Withdraw, TopUp
filter[amount] false [decimal] This will return only records which cover the amount.

RESPONSE DETAILS

Key Type Description
fee_type [string] Fee type. Could be static or percentage.
from [decimal] Start range amount. Transaction amount must be bigger than or equal to from and less than to for applying a fee object to transaction.
to [decimal] End range amount. Transaction amount must be bigger than or equal to from and less than to for applying a fee object to transaction.
amount [decimal] Fee amount that will be applied to transaction. In case of percentage fee_type it will indicate the percentage fee(min: 0%, max: 100%).
active [boolean] Indicator of active/disabled. If false - object will not be involved in fee calculation process.
global [boolean] Indicator of global/individual. If false - object related only for specific user from object’s relationships. User can only fetch global fees and fees that belongs to his account.

Show Fee

REQUEST

GET /v1/fees/ffffffff-ffff-ffff-ffff-ffffffffffff HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/fees/ffffffff-ffff-ffff-ffff-ffffffffffff" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "fees_top_ups",
    "attributes": {
      "fee_type": "static",
      "from": "0.0",
      "to": "1000000000000000.0",
      "amount": "0.0",
      "active": false,
      "global": true,
      "created_at": "2018-10-16T11:47:25.474Z",
      "updated_at": "2018-10-16T11:47:25.474Z"
    },
    "relationships": {
      "currency": {
        "data": {
          "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
          "type": "currencies"
        }
      },
      "user": {
        "data": null
      }
    }
  }
}

ENDPOINT

/v1/fees/:fee_id

DESCRIPTION

This endpoint retrieves a specific fee object.

RESPONSE DETAILS

Create Fee

REQUEST

POST /v1/fees HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
data%5Battributes%5D%5Bamount%5D=10data%5Battributes%5D%5Bcurrency%5D=usddata%5Battributes%5D%5Bfee_model_type%5D=top_up
curl -X POST "http://api.bitspark.io/v1/fees" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'data%5Battributes%5D%5Bamount%5D=10&data%5Battributes%5D%5Bcurrency%5D=usd&data%5Battributes%5D%5Bfee_model_type%5D=top_up'

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "fees_top_ups",
    "attributes": {
      "fee_type": "static",
      "from": "0.0",
      "to": "1000000000000000.0",
      "amount": "10.0",
      "active": true,
      "global": false,
      "created_at": "2018-10-16T11:47:25.474Z",
      "updated_at": "2018-10-16T11:47:25.474Z"
    },
    "relationships": {
      "currency": {
        "data": {
          "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
          "type": "currencies"
        }
      },
      "user": {
        "data": null
      }
    }
  }
}

ENDPOINT

/v1/fees

DESCRIPTION

This endpoint creates new fee.

FORM DATA

Key Required Type Description
data[type] false [string] Fee’s type. Could be fees_top_ups, fees_deposits, fees_withdraws.
data[attributes][amount] true [string] Fee amount. By default(only one supported through API currently) fee type is static, this means that this amount will be applied to transaction as fee.
data[attributes][currency] true [string] Can be any of available currencies in system. It is allowed to specify the currency id or code.
data[attributes][fee_model_type] true [string] Only top_up possible currently.

RESPONSE DETAILS

Recipients

All Recipients

REQUEST

GET /v1/recipients HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/recipients" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "recipients",
      "attributes": {
        "first_name": "First",
        "middle_name": "mid",
        "last_name": "Last",
        "email": "some@email.example",
        "phone_number": "+123456789012",
        "alt_phone_number": null,
        "address": "350 5th Ave, New York, NY 10118, USA",
        "bank_branch": "Bank Branch Name",
        "beneficiary_name": "Beneficiary Name",
        "bank_account_number": "111111111111",
        "cnic": null,
        "iban": null
      }
    },
    "..."
  ]
}

ENDPOINT

/v1/recipients

DESCRIPTION

This endpoint retrieves all your send money recipients.

RESPONSE DETAILS

Key Type Description
first_name [string] Recipient’s first name
middle_name [string] Recipient’s middle name
last_name [string] Recipient’s last name
email [string] Recipient’s email
phone_number [string] Recipient’s valid phone number
alt_phone_number [string] Recipient’s alternative phone number
address [string] Recipient’s adsress
bank_branch [string] Recipient’s bank branch
beneficiary_name [string] Recipient’s beneficiary
bank_account_number [string] Recipient’s bank account number
bank_account_type [string] Recipient’s bank account type, should be one of [current, saving]
cnic [string] Computerized National Identity Card
iban [string] International bank account number

Show Recipient

REQUEST

GET /v1/recipients/ffffffff-ffff-ffff-ffff-ffffffffffff HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/recipients/ffffffff-ffff-ffff-ffff-ffffffffffff" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "user_recipients",
    "attributes": {
      "first_name": "First",
      "middle_name": "mid",
      "last_name": "Last",
      "email": "some@email.example",
      "phone_number": "+8611444455555",
      "alt_phone_number": "+8622444455555",
      "address": "350 5th Ave, New York, NY 10118, USA",
      "bank_branch": "Bank Branch name",
      "beneficiary_name": "Beneficiary Name",
      "bank_account_number": "111111111111",
      "cnic": null,
      "iban": null
    }
  }
}

ENDPOINT

/v1/recipients/:recipient_id

DESCRIPTION

This endpoint retrieves a specific recipient.

RESPONSE DETAILS

Create Recipient

REQUEST

POST /v1/recipients HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
data%5Btype%5D=user_recipientsdata%5Battributes%5D%5Bfirst_name%5D=Firstdata%5Battributes%5D%5Blast_name%5D=Lastdata%5Battributes%5D%5Bphone_number%5D=%2B8611444455555data%5Battributes%5D%5Bbank_branch%5D=Bank+Branch+namedata%5Battributes%5D%5Bbeneficiary_name%5D=Beneficiary+Namedata%5Battributes%5D%5Bbank_account_number%5D=111111111111
curl -X POST "https://api.bitspark.io/v1/recipients"
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'data%5Btype%5D=user_recipients&data%5Battributes%5D%5Bfirst_name%5D=First&data%5Battributes%5D%5Blast_name%5D=Last&data%5Battributes%5D%5Bphone_number%5D=%2B8611444455555&data%5Battributes%5D%5Bbank_branch%5D=Bank%20Branch%20name&data%5Battributes%5D%5Bbeneficiary_name%5D=Beneficiary%20Name&data%5Battributes%5D%5Bbank_account_number%5D=111111111111'

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "user_recipients",
    "attributes": {
      "first_name": "First",
      "middle_name": "mid",
      "last_name": "Last",
      "email": "some@email.example",
      "phone_number": "+8611444455555",
      "alt_phone_number": "+8622444455555",
      "address": "350 5th Ave, New York, NY 10118, USA",
      "bank_branch": "Bank Branch name",
      "beneficiary_name": "Beneficiary Name",
      "bank_account_number": "111111111111",
      "cnic": null,
      "iban": null
    }
  }
}

ENDPOINT

/v1/recipients

DESCRIPTION

This endpoint creates new recipient.

FORM DATA

Key Required Type Description
data[type] true [string] Recipient’s type ( must be user_recipients)
data[attributes][first_name] true [string] Recipient’s first name
data[attributes][middle_name] false [string] Recipient’s middle name
data[attributes][last_name] true [string] Recipient’s last name
data[attributes][email] false [string] Recipient’s email
data[attributes][phone_number] true [string] Recipient’s valid phone number
data[attributes][alt_phone_number] false [string] Recipient’s alternative phone number
data[attributes][address] false [string] Recipient’s address
data[attributes][bank_branch] true (only for bank transfers) [string] Recipient’s bank branch
data[attributes][beneficiary_name] true (only for bank transfers) [string] Recipient’s beneficiary
data[attributes][bank_account_number] true (only for bank transfers) [string] Recipient’s bank account number
data[attributes][cnic] false [string] Computerized National Identity Card
data[attributes][iban] false [string] International bank account number

RESPONSE DETAILS

Update Recipient

REQUEST

PUT /v1/recipients/ffffffff-ffff-ffff-ffff-ffffffffffff HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
data%5Btype%5D=user_recipientsdata%5Battributes%5D%5Bfirst_name%5D=Firstdata%5Battributes%5D%5Blast_name%5D=Lastdata%5Battributes%5D%5Bphone_number%5D=%2B8611444455555data%5Battributes%5D%5Bbank_branch%5D=Bank+Branch+namedata%5Battributes%5D%5Bbeneficiary_name%5D=Beneficiary+Namedata%5Battributes%5D%5Bbank_account_number%5D=111111111111
curl -X PUT "https://api.bitspark.io/v1/recipients/ffffffff-ffff-ffff-ffff-ffffffffffff" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'data%5Btype%5D=user_recipients&data%5Battributes%5D%5Bfirst_name%5D=First&data%5Battributes%5D%5Blast_name%5D=Last&data%5Battributes%5D%5Bphone_number%5D=%2B8611444455555&data%5Battributes%5D%5Bbank_branch%5D=Bank%20Branch%20name&data%5Battributes%5D%5Bbeneficiary_name%5D=Beneficiary%20Name&data%5Battributes%5D%5Bbank_account_number%5D=111111111111'

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "user_recipients",
    "attributes": {
      "first_name": "First One1",
      "middle_name": "mid mAn",
      "last_name": "Last another",
      "email": "some@email.exampleq",
      "phone_number": "+8611444455555",
      "alt_phone_number": "+8622444455555",
      "address": "350 5th Ave, New York, NY 10118, USA",
      "bank_branch": "Bank Branch name",
      "bank_branch_address": null,
      "beneficiary_name": "Beneficiary Name",
      "bank_account_number": "111111111111",
      "cnic": null,
      "iban": null
    }
  }
}

ENDPOINT

/v1/recipients/:recipient_id

DESCRIPTION

With this endpoint you can update specific recipient info.

FORM DATA

RESPONSE DETAILS

Delete Recipient

REQUEST

DELETE /v1/recipients/ffffffff-ffff-ffff-ffff-ffffffffffff HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X DELETE "http://api.bitspark.io/v1/recipients/ffffffff-ffff-ffff-ffff-ffffffffffff" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

ENDPOINT

/v1/recipients/:recipient_id

DESCRIPTION

With this endpoint you can delete specific recipient.

RESPONSE DETAILS

Transactions

Transfers History V1

REQUEST

GET /v1/transactions/remittances?include=transfer_recipient HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/transactions/remittances?include=transfer_recipient" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "transfers",
      "attributes": {
        "status": {
          "code": "unknown",
          "message": "Unknown"
        },
        "amount": "11.11",
        "currency": "VND",
        "exchange_rate": "22222.22222",
        "destination_country": "Vietnam",
        "tracking_number": null,
        "tracking_number_possible": false
      },
      "relationships": {
        "transfer_recipient": {
          "data": {
            "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
            "type": "transfer_recipients"
          }
        }
      }
    },
    "..."
  ],
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "transfer_recipients",
      "attributes": {
        "first_name": "qwe",
        "middle_name": null,
        "last_name": "qwe",
        "email": null,
        "phone_number": "123",
        "alt_phone_number": null,
        "address": null,
        "bank_branch": null,
        "bank_branch_address": null,
        "beneficiary_name": "1",
        "bank_account_number": "1",
        "cnic": null,
        "iban": null
      }
    },
    "..."
  ]
}

ENDPOINT

/v1/transactions/remittances

DESCRIPTION

This endpoint retrieves all created transfers with details.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Set it to transfer_recipient to include all transfers’ recipients

RESPONSE DETAILS

Key Type Description
status[code] [string] Transfer status code
status[message] [string] Transfer status message
amount [decimal] Sent amount of money
currency [string] Destination currency
exchange_rate [decimal] Send money exchange rate
destination_country [string] Destination country
tracking_number [string] Transfer tracking number
tracking_number_possible [string] Returns true if tracking_number will be present
relationships[transfer_recipient] [hash] See All Recipients for response details.

Transfers History V2

REQUEST

GET /v2/transactions/remittances?include=transfer_recipient HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v2/transactions/remittances?include=transfer_recipient" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "transfers",
      "attributes": {
        "status": {
          "group": "Unknown",
          "code": "unknown",
          "message": "Unknown",
          "info": "Unknown"
        },
        "amount": "11.11",
        "amount_to_send": "0.0",
        "currency": "VND",
        "account_currency": "USD",
        "exchange_rate": "1.0",
        "destination_country": "Vietnam",
        "receipt_info": {
          "principal": null,
          "cable_charge": "28.0",
          "pickup_fee": null,
          "payment_service_fee": null,
          "amount_due": "545.0",
          "landed_amount": "3000.0"
        },
        "transaction_number": "TF-180301-111-1111",
        "tracking_number": null,
        "tracking_number_possible": false,
        "created_at": "2018-01-01",
        "updated_at": "2018-01-01"
      },
      "relationships": {
        "transfer_recipient": {
          "data": {
            "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
            "type": "transfer_recipients"
          }
        }
      }
    },
    "..."
  ],
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "transfer_recipients",
      "attributes": {
        "first_name": "First",
        "middle_name": null,
        "last_name": "Last",
        "email": "some@email.example",
        "phone_number": "+8611444455555",
        "alt_phone_number": null,
        "address": "350 5th Ave, New York, NY 10118, USA",
        "bank_branch": "Bank Branch name",
        "beneficiary_name": "Beneficiary Name",
        "bank_account_number": "111111111111",
        "bank_account_type": "current",
        "cnic": null,
        "iban": null
      }
    },
    "..."
  ]
}

ENDPOINT

/v2/transactions/remittances

DESCRIPTION

This endpoint retrieves all created transfers with details.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Set it to transfer_recipient to include all transfers’ recipients

RESPONSE DETAILS

Key Type Description
status[group] [string] Group of code status
status[code] [string] Transfer status code ( should be one of Transfer statuses list codes )
status[message] [string] Transfer status message
status[info] [string] Additional status message
amount [decimal] Sent amount of money
amount_to_send [decimal] Amount of money that user wants to transact in user currency
currency [string] Destination currency
account_currency [string] Account currency to withraw from ( should be one of Available Currencies codes )
exchange_rate [decimal] Send money exchange rate
destination_country [string] Destination country
receipt_info [hash] Receipt info
transaction_number [string] Transaction identifier
tracking_number [string] Transfer tracking number
tracking_number_possible [string] Returns true if tracking_number will be present
created_at [string] Created at
updated_at [string] Updated at
relationships[transfer_recipient] [hash] See All Recipients for response details.

Transactions History

REQUEST

GET /v1/transactions/history HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/transactions/history" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "mobile_payments",
      "attributes": {
        "account_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
        "amount": 151,
        "status": {
          "group": "failed",
          "code": "declined",
          "message": "Cancelled",
          "info": "Your tracking number will be available soon"
        },
        "payment_type": "Transfer",
        "currency": "PHP",
        "basic_info": {
            "recipient_name": "Roma test Adff",
            "recipient_contact_number": "+111111",
            "address": "iaddress"
        },
        "created_at": "2018-03-15T14:24:26.689Z"
      }
    },
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "mobile_payments",
      "attributes": {
          "account_id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
          "amount": 33,
          "status": {
              "code": "pending",
              "message": "Pending"
          },
          "payment_type": "BankDeposit",
          "currency": "USD",
          "basic_info": {
              "txid": "1111111"
          },
          "created_at": "2018-03-13T16:53:43.383Z"
      }
    }
  ]
}

ENDPOINT

/v1/transactions/history

DESCRIPTION

This endpoint retrieves all created transactions with details.

TRANSACTION GENERAL RESPONSE DETAILS

Key Type Description
status[code] [string] Transaction status code
status[message] [string] Transaction status message
account_id [uuid] Account id with which transaction where committed
amount [decimal] Sent amount of money
currency [string] Destination currency
payment_type [string] Transaction type
created_at [string] Created at

DEPOSIT SPECIFIC DETAILS

Key Type Description
basic_info [string] Deposit Txid or btc address

WITHDRAW SPECIFIC DETAILS

Key Type Description
basic_info [string] Withdraw Txid

TOPUP SPECIFIC DETAILS

Key Type Description
basic_info [string] Recipient address

TRANSFER SPECIFIC DETAILS

Key Type Description
status[group] [string] Group of code status
status[code] [string] Transfer status code ( should be one of Transfer statuses list codes )
status[message] [string] Transfer status message
status[info] [string] Additional status message
basic_info[recipient_name] [string] Recipient full name
basic_info[recipient_contact_number] [string] Recipient contact number
basic_info[address] [string] Recipient address
basic_info[txid] [string] txid

Show Remmitance

REQUEST

GET /v1/transactions/remittances/ffffffff-ffff-ffff-ffff-ffffffffffff HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/transactions/remittances/ffffffff-ffff-ffff-ffff-ffffffffffff" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "transfers",
    "attributes": {
      "status": {
        "group": "pending",
        "code": "payment_commited_successfully",
        "message": "Payment commited",
        "info": ""
      },
      "amount": "151.0",
      "amount_to_send": "0.0",
      "currency": "PHP",
      "account_currency": "USD",
      "exchange_rate": "1.0",
      "destination_country": "Philippines",
      "receipt_info": {},
      "transaction_number": "TF-180315-668-X9YZ",
      "tracking_number": null,
      "tracking_number_possible": true,
      "created_at": "2018-03-15T14:24:26.689Z",
      "updated_at": "2018-03-15T14:25:01.359Z"
    },
    "relationships": {
      "transfer_recipient": {
        "data": {
          "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
          "type": "transfer_recipients"
        }
      }
    }
  }
}

ENDPOINT

/v1/transactions/remittances/:remittance_id

DESCRIPTION

This endpoint retrieves a specific remittance.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Set it to transfer_recipient to include all transfers’ recipients

RESPONSE DETAILS

Send Money

REQUEST

POST /v1/transactions/send_money HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
account_currency=usddata%5Btype%5D=transfersdata%5Battributes%5D%5Bamount%5D=100data%5Battributes%5D%5Bdelivery_method%5D=delivery_method_codedata%5Battributes%5D%5Bprovider%5D=province_codedata%5Brelationships%5D%5Bdestination%5D%5Bdata%5D%5Btype%5D=destinationsdata%5Brelationships%5D%5Bdestination%5D%5Bdata%5D%5Battributes%5D%5Bid%5D=ffffffff-ffff-ffff-ffffffffffffdata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Btype%5D=recipientsdata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bbank_account_number%5D=bank_account_numberdata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bbeneficiary_name%5D=beneficiary_namedata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bfirst_name%5D=first_namedata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Blast_name%5D=last_namedata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bphone_number%5D=phone_numberdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Btype%5D=sendersdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bfirst_name%5D=first_namedata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bmiddle_name%5D=middle_namedata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Blast_name%5D=last_namedata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bid_number%5D=id_numberdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Baddress%5D=addressdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bphone_number%5D=phone_numberdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Balt_phone_number%5D=alt_phone_number
curl -X POST "https://api.bitspark.io/v1/transactions/send_money" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'account_currency=usd&data%5Btype%5D=transfers&data%5Battributes%5D%5Bamount%5D=100&data%5Battributes%5D%5Bdelivery_method%5D=delivery_method_code&data%5Battributes%5D%5Bprovider%5D=province_code&data%5Brelationships%5D%5Bdestination%5D%5Bdata%5D%5Btype%5D=destinations&data%5Brelationships%5D%5Bdestination%5D%5Bdata%5D%5Battributes%5D%5Bid%5D=ffffffff-ffff-ffff-ffffffffffff&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Btype%5D=recipients&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bbank_account_number%5D=bank_account_number&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bbeneficiary_name%5D=beneficiary_name&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bfirst_name%5D=first_name&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Blast_name%5D=last_name&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bphone_number%5D=phone_number&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Btype%5D=senders&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bfirst_name%5D=first_name&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bmiddle_name%5D=middle_name&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Blast_name%5D=last_name&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bid_number%5D=id_number&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Baddress%5D=address&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bphone_number%5D=phone_number&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Balt_phone_number%5D=alt_phone_number'

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "transfers",
    "attributes": {
      "status": {
        "group": "pending",
        "code": "unknown",
        "message": "Processing",
        "info": ""
      },
      "amount": "1.0",
      "amount_to_send": "0.0",
      "currency": "IDR",
      "account_currency": "USD",
      "exchange_rate": null,
      "destination_country": "Indonesia",
      "receipt_info": {},
      "transaction_number": "TF-180622-2247-TK8F",
      "tracking_number": null,
      "tracking_number_possible": false,
      "callback_url": "example.com",
      "created_at": "2018-06-22T10:18:30.046Z",
      "updated_at": "2018-06-22T10:18:30.046Z"
    },
    "relationships": {
      "transfer_recipient": {
        "data": {
          "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
          "type": "transfer_recipients"
        }
      }
    }
  },
  "included": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "transfer_recipients",
      "attributes": {
        "first_name": "qwe",
        "middle_name": null,
        "last_name": "qwe",
        "email": null,
        "phone_number": "+380938740945",
        "alt_phone_number": null,
        "address": null,
        "bank_branch": null,
        "bank_branch_address": null,
        "beneficiary_name": "1",
        "bank_account_number": "1",
        "cnic": null,
        "iban": null
      }
    }
  ]
}

ENDPOINT

/v1/transactions/send_money

DESCRIPTION

This endpoint creates new transfer.

FORM DATA

Key Required Type Description
account_currency true [string] Account currency for send money from (should be one of Available Currencies codes)
data[type] true [string] Transfer’s type ( must be transfers)
data[attributes][amount] true [decimal] Amount of Destination currency to be sent ( should be greater than 0.0)
data[attributes][delivery_method] true [string] Delivery method code
data[attributes][provider] true [string] Provider code
data[attributes][province] false [string] Province code
data[attributes][callback_url] false [string] URL which will get object after his status update. You should respond with text OK and success status 20* to callback, in other case it will re-send callback again in 2, 4, 6, 8, 10 minutes
data[relationships][destination][data][type] true [string] Destination’s type ( must be destinations)
data[relationships][destination][data][attributes][id] true [uuid] Destination ID for send money to
data[relationships][destination][data][attributes][code] true [string] Destination code for send money to ( not required if ID specified )
data[relationships][recipient][data][type] true [string] Recipient’s type ( must be recipients)
data[relationships][recipient][data][attributes] true/false [hash] See Create Recipient for Recipient’s FORM DATA details.
data[relationships][sender][data][type] true/false [string] Sender’s type ( must be senders)
data[relationships][sender][data][attributes][first_name] true/false [string] Sender’s first name
data[relationships][sender][data][attributes][middle_name] true/false [string] Sender’s middle name
data[relationships][sender][data][attributes][last_name] true/false [string] Sender’s last name
data[relationships][sender][data][attributes][id_number] true/false [string] Sender’s ID number
data[relationships][sender][data][attributes][address] true/false [string] Sender’s address
data[relationships][sender][data][attributes][phone_number] true/false [string] Sender’s phone number
data[relationships][sender][data][attributes][alt_phone_number] true/false [string] Sender’s alternative phone number

RESPONSE DETAILS

Send Domestic Money

REQUEST

POST /v1/transactions/send_domestic_money HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
account_currency=usddata%5Btype%5D=transfersdata%5Battributes%5D%5Bamount%5D=100data%5Battributes%5D%5Bdelivery_method%5D=delivery_method_codedata%5Battributes%5D%5Bprovider%5D=province_codedata%5Brelationships%5D%5Bdestination%5D%5Bdata%5D%5Btype%5D=destinationsdata%5Brelationships%5D%5Bdestination%5D%5Bdata%5D%5Battributes%5D%5Bid%5D=ffffffff-ffff-ffff-ffffffffffffdata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Btype%5D=recipientsdata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bbank_account_number%5D=bank_account_numberdata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bbeneficiary_name%5D=beneficiary_namedata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bfirst_name%5D=first_namedata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Blast_name%5D=last_namedata%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bphone_number%5D=phone_numberdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Btype%5D=sendersdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bfirst_name%5D=first_namedata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bmiddle_name%5D=middle_namedata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Blast_name%5D=last_namedata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bid_number%5D=id_numberdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Baddress%5D=addressdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bphone_number%5D=phone_numberdata%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Balt_phone_number%5D=alt_phone_numberdata%5Battributes%5D%5Bdomestic_payment_id%5D=ffffffff-ffff-ffff-ffffffffffff
curl -X POST "https://api.bitspark.io/v1/transactions/send_domestic_money" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'account_currency=usd&data%5Btype%5D=transfers&data%5Battributes%5D%5Bamount%5D=100&data%5Battributes%5D%5Bdelivery_method%5D=delivery_method_code&data%5Battributes%5D%5Bprovider%5D=province_code&data%5Brelationships%5D%5Bdestination%5D%5Bdata%5D%5Btype%5D=destinations&data%5Brelationships%5D%5Bdestination%5D%5Bdata%5D%5Battributes%5D%5Bid%5D=ffffffff-ffff-ffff-ffffffffffff&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Btype%5D=recipients&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bbank_account_number%5D=bank_account_number&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bbeneficiary_name%5D=beneficiary_name&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bfirst_name%5D=first_name&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Blast_name%5D=last_name&data%5Brelationships%5D%5Brecipient%5D%5Bdata%5D%5Battributes%5D%5Bphone_number%5D=phone_number&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Btype%5D=senders&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bfirst_name%5D=first_name&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bmiddle_name%5D=middle_name&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Blast_name%5D=last_name&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bid_number%5D=id_number&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Baddress%5D=address&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Bphone_number%5D=phone_number&data%5Brelationships%5D%5Bsender%5D%5Bdata%5D%5Battributes%5D%5Balt_phone_number%5D=alt_phone_number&data%5Battributes%5D%5Bdomestic_payment_id%5D=ffffffff-ffff-ffff-ffffffffffff'

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "transfers",
    "attributes": {
      "status": {
        "group": "pending",
        "code": "unknown",
        "message": "Processing",
        "info": ""
      },
      "amount": "1.0",
      "amount_to_send": "0.0",
      "currency": "IDR",
      "account_currency": "USD",
      "exchange_rate": null,
      "destination_country": "Indonesia",
      "receipt_info": {},
      "transaction_number": "TF-180622-2247-TK8F",
      "tracking_number": null,
      "tracking_number_possible": false,
      "created_at": "2018-06-22T10:18:30.046Z",
      "updated_at": "2018-06-22T10:18:30.046Z"
    },
    "relationships": {
      "transfer_recipient": {
        "data": {
          "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
          "type": "transfer_recipients"
        }
      }
    }
  },
  "included": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "transfer_recipients",
      "attributes": {
        "first_name": "qwe",
        "middle_name": null,
        "last_name": "qwe",
        "email": null,
        "phone_number": "+380938740945",
        "alt_phone_number": null,
        "address": null,
        "bank_branch": null,
        "bank_branch_address": null,
        "beneficiary_name": "1",
        "bank_account_number": "1",
        "cnic": null,
        "iban": null
      }
    }
  ]
}

ENDPOINT

/v1/transactions/send_domestic_money

DESCRIPTION

This endpoint creates new transfer.

FORM DATA

See Send Money for FORM DATA details. Additional

Key Required Type Description
data[attributes][domestic_payment_id] [string] Domestic Payment ID

RESPONSE DETAILS

Payments

Create Withdraw

REQUEST (USD account)

POST /v2/payments/withdraw HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
account_currency=usddata%5Btype%5D=withdrawdata%5Battributes%5D%5Btxid%5D=txiddata%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Bname%5D=bank_namedata%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Bbeneficiary_name%5D=beneficiary_namedata%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Baccount_number%5D=account_numberdata%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Bswift_code%5D=swift_codedata%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Baddress%5D=address
curl -X POST "https://api.bitspark.io/v2/payments/withdraw" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'account_currency=usd&data%5Btype%5D=withdraw&data%5Battributes%5D%5Btxid%5D=txid&data%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Bname%5D=bank_name&data%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Bbeneficiary_name%5D=beneficiary_name&data%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Baccount_number%5D=account_number&data%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Bswift_code%5D=swift_code&data%5Brelationships%5D%5Bbank_detail%5D%5Bdata%5D%5Battributes%5D%5Baddress%5D=address'

RESPONSE (USD account)

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "withdraws",
    "attributes": {
      "amount": "100.0",
      "txid": "12335352",
      "callback_url": "example.com",
      "status": {
        "code": "pending",
        "message": "Pending"
      }
    },
    "relationships": {
      "bank_detail": {
        "data": {
          "type": "bank_details",
          "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee"
        }
      },
      "account": {
        "data": {
          "type": "accounts",
          "id": "dddddddd-dddd-dddd-dddd-dddddddddddd"
        }
      }
    }
  },
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "bank_details",
      "attributes": {
        "name": "HSBC",
        "beneficiary_name": "Eve Moneypenny",
        "account_number": "123123123",
        "address": "85 Albert Embankment, Vauxhall, London",
        "swift_code": "1234321"
      }
    }
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "accounts",
      "attributes": {
        "balance": "87597.8195418990169122",
        "shop_commission": "12.0",
        "balance_threshold": "0.0"
      },
      "relationships": {
        "currency": {
          "data": {
            "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
            "type": "currencies"
          }
        }
      }
    },
    {
      "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
      "type": "currencies",
      "attributes": {
        "code": "usd",
        "name": "USD",
        "account": true
      }
    },

  ]
}

REQUEST (Bitcoin account)

POST /v1/transactions/withdraw HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
account_currency=btcdata%5Btype%5D=withdrawdata%5Battributes%5D%5Bamount%5D=100data%5Battributes%5D%5Bwallet_address%5D=wallet_address
curl -X POST "https://api.bitspark.io/v2/payments/withdraw" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d "account_currency=btc&data%5Btype%5D=withdraw&data%5Battributes%5D%5Bamount%5D=100&data%5Battributes%5D%5Bwallet_address%5D=wallet_address'

RESPONSE (Bitcoin account)

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "withdraws",
    "attributes": {
      "amount": "100.0",
      "wallet_address": "3J98t1WpEZ73CNmQviecrnyiWrnqRhWNLy"
    },
    "relationships": {
      "account": {
        "data": {
          "type": "accounts",
          "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee"
        }
      }
    }
  },
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "accounts",
      "attributes": {
        "balance": "100.0",
        "shop_commission": "1.0",
        "balance_threshold": "0.0"
      },
      "relationships": {
        "currency": {
          "data": {
            "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
            "type": "currencies"
          }
        }
      }
    },
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "currencies",
      "attributes": {
        "code": "btc",
        "name": "BTC",
        "account": true
      }
    }
  ]
}

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": "Insufficient funds on account"
    }
  ]
}

ENDPOINT

/v2/payments/withdraw

DESCRIPTION

Withdraw money from specified account.

FORM DATA

Key Required Type Description
account_currency true [string] Account currency to withraw from (should be one of Available Currencies codes)
data[type] true [string] Withdraw’s type ( should be withdraw)
data[attributes][txid] true [string] User’s Txid
data[attributes][amount] true [string] Amount of money to be withdraw ( should be greater than 0.0)
data[attributes][callback_url] false [string] URL which will get object after his status update. You should respond with text OK and success status 20* to callback, in other case it will re-send callback again in 2, 4, 6, 8, 10 minutes
data[relationships][bank_detail][data][type] false [string] Bank Detail’s type ( should be bank_details)
data[relationships][bank_detail][data][attributes][name] true [string] Bank name
data[relationships][bank_detail][data][attributes][beneficiary_name] true [string] User’s Beneficiary Name
data[relationships][bank_detail][data][attributes][account_number] true [string] User’s Account Number
data[relationships][bank_detail][data][attributes][swift_code] true [string] User’s Swift Code
data[relationships][bank_detail][data][attributes][address] true [string] User’s Address
data[attributes][bitcoin_address] false [string] User’s Personal Bitcoin Address
data[attributes][gauth_token] false [string] GAuth confirmation token (only if 2FA enabled)

Pending BTC deposits

REQUEST

GET /v2/payments/pending_btc_deposits HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v2/payments/pending_btc_deposits" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "btc_deposits",
      "attributes": {
        "amount": null,
        "txid": null,
        "callback_url": null,
        "status": {
          "code": "unknown",
          "message": "Unknown"
        },
        "bitcoin_address": "1KYjqpDx6LnyuQFQ5591iTMJgASUdju5uM",
        "address": "1KYjqpDx6LnyuQFQ5591iTMJgASUdju5uM"
      },
      "relationships": {
        "account": {
          "data": {
            "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
            "type": "accounts"
          }
        }
      }
    }
  ]
}

ENDPOINT

/v2/payments/pending_btc_deposits

DESCRIPTION

Return all BTC deposits where status pending

REQUEST PARAMS

No special params required, pagination possible as for other collections.

Show Payment V1

REQUEST

GET /v1/transactions/payments/ffffffff-ffff-ffff-ffff-ffffffffffff HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/transactions/payments/ffffffff-ffff-ffff-ffff-ffffffffffff" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "bank_deposits",
    "attributes": {
      "amount": "1.0",
      "txid": "123",
      "callback_url": "example.com",
      "status": {
        "code": "pending",
        "message": "Pending"
      },
      "deposit_credentials": {
        "iban": "CZ00000000000000",
        "bank_name": "Komercni Banka, a.s.",
        "reference": "999999999",
        "swift_code": "KOMBCZPP",
        "bank_address": "Na Prikope 33 cp. 969 114 07 Praha 1",
        "account_number": "",
        "beneficiary_name": "Valoris HK Limited",
        "account_holder_address": "5- 109 Argyle Street Richmond Commercial , Kowloon, 00000, Hong Kong"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
          "type": "accounts"
        }
      }
    }
  }
}

ENDPOINT

/v1/transactions/payments/:id

DESCRIPTION

This endpoint retrieves a specific payment.

Show Payment V2

REQUEST

GET /v2/payments/ffffffff-ffff-ffff-ffff-ffffffffffff HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v2/payments/ffffffff-ffff-ffff-ffff-ffffffffffff" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "bank_deposits",
    "attributes": {
      "amount": "1.0",
      "txid": "123",
      "callback_url": "example.com",
      "status": {
        "code": "pending",
        "message": "Pending"
      },
      "deposit_credentials": {
        "iban": "CZ00000000000000",
        "bank_name": "Komercni Banka, a.s.",
        "reference": "999999999",
        "swift_code": "KOMBCZPP",
        "bank_address": "Na Prikope 33 cp. 969 114 07 Praha 1",
        "account_number": "",
        "beneficiary_name": "Valoris HK Limited",
        "account_holder_address": "5- 109 Argyle Street Richmond Commercial , Kowloon, 00000, Hong Kong"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
          "type": "accounts"
        }
      }
    }
  }
}

ENDPOINT

/v2/payments/:id

DESCRIPTION

This endpoint retrieves a specific payment.

Create Deposit V2

REQUEST

POST /v2/payments/deposit HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
account_currency=usddata%5Btype%5D=depositsdata%5Battributes%5D%5Bamount%5D=100
curl -X POST "https://api.bitspark.io/v2/payments/deposit" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'account_currency=usd&data%5Btype%5D=deposits&data%5Battributes%5D%5Bamount%5D=100'

RESPONSE (USD account)

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "deposits",
    "attributes": {
      "amount": "1.0",
      "txid": "DWK9PITB",
      "callback_url": "example.com",
      "status": {
        "code": "pending",
        "message": "Pending"
      },
      "deposit_credentials": {
        "iban": "CZ8801000001152130170277",
        "bank_name": "Komercni Banka, a.s.",
        "reference": "9120255451",
        "swift_code": "KOMBCZPP",
        "bank_address": "Na Prikope 33 cp. 969 114 07 Praha 1",
        "account_number": "",
        "beneficiary_name": "Valoris HK Limited",
        "account_holder_address": "5- 109 Argyle Street Richmond Commercial , Kowloon, 00000, Hong Kong"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "type": "accounts",
          "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee"
        }
      }
    }
  },
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "accounts",
      "attributes": {
        "balance": "87497.8195418990169122",
        "shop_commission": "12.0",
        "balance_threshold": "0.0"
      },
      "relationships": {
        "currency": {
          "data": {
            "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
            "type": "currencies"
          }
        }
      }
    },
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "currencies",
      "attributes": {
        "code": "usd",
        "name": "USD",
        "account": true
      }
    }
  ]
}

RESPONSE (Bitcoin account)

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "deposits",
    "attributes": {
      "amount": "100.0",
      "txid": "1PSKC85N",
      "callback_url": "example.com",
      "bitcoin_address": "1q2W3e4R5t6Y7u8I9o0P1q2W3e4R5t6Y7u"
    },
    "relationships": {
      "account": {
        "data": {
          "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
          "type": "accounts"
        }
      }
    }
  },
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "accounts",
      "attributes": {
        "balance": "100.0",
        "shop_commission": "1.0",
        "balance_threshold": "0.0"
      },
      "relationships": {
        "currency": {
          "data": {
            "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
            "type": "currencies"
          }
        }
      }
    },
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "currencies",
      "attributes": {
        "code": "btc",
        "name": "BTC",
        "account": true
      }
    }
  ]
}

ENDPOINT

/v2/payments/deposit

DESCRIPTION

Deposit money to specified account.

FORM DATA

Key Required Type Description
account_currency true [string] Account currency to deposit to ( should be one of Available Currencies codes )
data[type] true [string] Deposit’s type ( should be deposits)
data[attributes][amount] true [decimal] Amount of money to be deposited ( should be greater than 0.0)
data[attributes][generate_new_address] false [string] Only possible for BTC currency deposit. If set true - will generate new BTC deposit with uniq address even if not used deposit addresses present. By default max possible not used deposit addresses - 5 per user(if need more - contact support)
data[attributes][callback_url] false [string] URL which will get object after his status update. You should respond with text OK and success status 20* to callback, in other case it will re-send callback again in 2, 4, 6, 8, 10 minutes

Create Deposit V3

REQUEST

POST /v3/payments/deposit HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
data%5Btype%5D=depositdata%5Battributes%5D%5Bamount%5D=100data%5Battributes%5D%5Bcurrency%5D=usd
curl -X POST "https://api.bitspark.io/v3/payments/deposit" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'data%5Btype%5D=deposit&data%5Battributes%5D%5Bamount%5D=100&data%5Battributes%5D%5Bcurrency%5D=usd'

RESPONSE

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "bank_deposits",
    "attributes": {
      "amount": "1.0",
      "txid": "123",
      "callback_url": "example.co,",
      "status": {
        "code": "pending",
        "message": "Pending"
      },
      "deposit_credentials": {
        "iban": "CZ00000000000000",
        "bank_name": "Komercni Banka, a.s.",
        "reference": "999999999",
        "swift_code": "KOMBCZPP",
        "bank_address": "Na Prikope 33 cp. 969 114 07 Praha 1",
        "account_number": "",
        "beneficiary_name": "Valoris HK Limited",
        "account_holder_address": "5- 109 Argyle Street Richmond Commercial , Kowloon, 00000, Hong Kong"
      }
    },
    "relationships": {
      "account": {
        "data": {
          "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
          "type": "accounts"
        }
      }
    }
  }
}

ENDPOINT

/v3/payments/deposit

DESCRIPTION

Deposit money to specified account.

FORM DATA

Key Required Type Description
data[type] true [string] Deposit’s type ( should be deposit)
data[attributes][amount] true [decimal] Amount of money to be deposited ( should be greater than 0.0)
data[attributes][currency] true [string] Any deposit available currency
data[attributes][generate_new_address] false [string] Only possible for BTC currency deposit. If set true - will generate new BTC deposit with uniq address even if not used deposit addresses present. By default max possible not used deposit addresses - 5 per user(if need more - contact support)
data[attributes][callback_url] false [string] URL which will get object after his status update. You should respond with text OK and success status 20* to callback, in other case it will re-send callback again in 2, 4, 6, 8, 10 minutes

Upload

REQUEST

PUT /v2/payments/ffffffff-ffff-ffff-ffff-ffffffffffff/upload?data[attributes][data_proof_attributes][proof]=[File]' HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X PUT "https://api.bitspark.io/v2/payments/ffffffff-ffff-ffff-ffff-ffffffffffff/upload?data[attributes][data_proof_attributes][proof]=[File]" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE (success)

{ "Success": "200 OK" }

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "BTC deposits has no proofs to be uploaded",
        "Proff can't be empty",
        "Payment proof proof You are not allowed to upload \"log\" files, allowed types: jpg, jpeg, gif, png, bmp, pdf"
      ]
    }
  ]
}

ENDPOINT

/v2/payments/:payment_id/upload

DESCRIPTION

This endpoint gives you ability to upload document proof for deposit with ID.

REQUEST PARAMS

Key Required Type Description
data[attributes][data_proof_attributes][proof] true [file] Your Deposit proof ( file should be one of next types: jpg, jpeg, gif, png, bmp, pdf)

Cancel

REQUEST

PUT /v2/payments/ffffffff-ffff-ffff-ffff-ffffffffffff/cancel HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
curl -X PUT "https://api.bitspark.io/v2/payments/ffffffff-ffff-ffff-ffff-ffffffffffff/cancel" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache"

RESPONSE (success)

{ "Success": "200 OK" }

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "Payment can not be canceled",
        "Payment cancel: Something went wrong."
      ]
    }
  ]
}

ENDPOINT

/v2/payments/:payment_id/cancel

DESCRIPTION

This endpoint cancels existing pending deposit by it’s ID.

Exchanges

Exchange Money

REQUEST

POST /v1/exchanges/exchange_currencies HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_HMAC
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
amount=1currency_from=usdcurrency_to=hkd
curl -X POST "https://api.bitspark.io/v1/exchanges/exchange_currencies"
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_HMAC" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'amount=1&currency_from=usd&currency_to=hkd'

RESPONSE (success)

{
  "data": {
    "id": "99999999999999",
    "type": "exchange_transaction_data",
    "attributes": {
      "status": "completed",
      "created_at": "2016-01-01T01:01:01.111+00:00",
      "fee": "0.00",
      "base_amount": "1.00",
      "quoted_amount": "7.65",
      "rate": "7.75515",
      "commission": "0.10"
    }
  }
}

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "Insufficient funds on account",
        "Invalid value for transaction"
      ]
    }
  ]
}

ENDPOINT

/v1/exchanges/exchange_currencies

DESCRIPTION

This endpoint exchanges money between your accounts. You can preview current exchange rate with Internal Exchange Rate endpoint.

REQUEST PARAMS

Key Required Type Description
amount true [decimal] Amount of money to be exchanged ( should be greater than 0.0)
currency_from true [string] Account currency from which will be sent money
currency_to true [string] Account currency to which will be recieved money

RESPONSE DETAILS

Key Type Description
status [string] Current status of exchange
created_at [date] Creation date of exchange
fee [decimal] Exchange fee
base_amount [decimal] Sent amount of money in currency_from
quoted_amount [decimal] Recieved amount of money in currency_to
rate [decimal] Actual exchange rate in wich exchange was performed
commission [decimal] Exchange commission

Exchange Money Rate

REQUEST

GET /v3/exchanges/exchange_rate?currency_from=usd&currency_to=eur&cached_rate=false&amount=1000 HTTP/1.1
Host: api.bitspark.io
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v3/exchanges/exchange_rate?currency_from=usd&currency_to=eur&cached_rate=false&amount=1000" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": {
      "id": "70279503147120",
      "type": "exchange_rate",
      "attributes": {
          "invoice_currency": "BTC",
          "payment_currency": "USD",
          "rate": "6586.357145000000985"
      }
  }
}

ENDPOINT

/v3/exchanges/exchange_rate

DESCRIPTION

This endpoint retrieves specific exchange rate with commission for Exchange Money endpoint.

REQUEST PARAMS

Key Required Type Default Description
currency_from true [string] nope Account currency from convert ( should be one of Available Currencies codes )
currency_to true [string] nope Account currency to convert in
amount false [decimals] nope Amount of money to be exchanged ( should be greater than 0.0 )
cached_rate false [string] true The indicator of whether the rate is cached or not ( if false then real-time rate will be returned )

RESPONSE DETAILS

Key Type Description
invoice_currency [string] Account currency to convert
payment_currency [string] Account currency to convert in
rate [decimal] Exchange rate

Top Ups V1

Top Ups History

REQUEST

GET /v1/top_ups/fffffffff-ffff-ffff-ffff-ffffffffff?include=locked_commision,user_account.currency, HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/top_ups/fffffffff-ffff-ffff-ffff-ffffffffff?include=locked_commision,user_account.currency" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "top_ups",
      "attributes": {
        "status_code": "pending",
        "status_message": "Pending",
        "amount": "10.0",
        "currency": "HKD",
        "shop_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
        "receipt_url": null,
        "performed_by_shop": false,
        "transaction_number": "TU-161007-981-51TF"
      },
      "relationships": {
        "user_account": {
          "data": {
            "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
            "type": "accounts"
          }
        },
        "shop_account": {
          "data": {
            "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
            "type": "accounts"
          }
        },
        "locked_commission": {
          "data": {
            "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
            "type": "locked_commissions"
          }
        }
      }
    },
    "..."
  ],
  "included": [
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "type": "locked_commissions",
      "attributes": {
        "shop_commission": "0.0",
        "bitspark_commission_percentage": "50.0"
      }
    }
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "accounts",
      "attributes": {
        "balance": "100.0",
        "shop_commission": "0.0",
        "balance_threshold": "0.0"
      },
      "relationships": {
        "currency": {
          "data": {
            "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
            "type": "currencies"
          }
        }
      }
    },
    {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "type": "currencies",
      "attributes": {
        "code": "hkd",
        "name": "HKD",
        "account": true
      }
    },
    "..."
  ]
}

ENDPOINT

/v1/top_ups

DESCRIPTION

This endpoint retrieves all created top ups with details.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Can be any subset of: locked_commision, user_account.currency, shop_account.currency
filter[top_up_type] false [string] requested Can be any one of: requested, owned

Create Top Up

REQUEST

POST /v1/top_ups?include=locked_commision,user_account.currency HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
shop_code=ffffffff-ffff-ffff-ffffffffffffcurrency=usddata%5Btype%5D=top_upsdata%5Battributes%5D%5Bamount%5D=10.0
curl -X POST "https://api.bitspark.io/v1/top_ups?include=locked_commision,user_account.currency" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'shop_code=ffffffff-ffff-ffff-ffffffffffff&currency=usd&data%5Btype%5D=top_ups&data%5Battributes%5D%5Bamount%5D=10.0'

RESPONSE (success)

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "top_ups",
    "attributes": {
      "status_code": "pending",
      "status_message": "Pending",
      "amount": "10.0",
      "currency": "USD",
      "shop_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "receipt_url": null,
      "performed_by_shop": false,
      "transaction_number": "TU-180622-2249-PQ3C"
    },
    "relationships": {
      "user_account": {
        "data": {
          "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
          "type": "accounts"
        }
      },
      "shop_account": {
        "data": {
          "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
          "type": "accounts"
        }
      },
      "locked_commission": {
        "data": {
          "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
          "type": "locked_commissions"
        }
      }
    }
  },
  "included": [
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "type": "locked_commissions",
      "attributes": {
        "shop_commission": "0.0",
        "bitspark_commission_percentage": "50.0"
      }
    },
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "accounts",
      "attributes": {
        "balance": "43.4",
        "shop_commission": "0.0",
        "balance_threshold": "0.0"
      },
      "relationships": {
        "currency": {
          "data": {
            "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
            "type": "currencies"
          }
        }
      }
    },
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "currencies",
      "attributes": {
        "code": "usd",
        "name": "USD",
        "account": true,
        "banknote": true,
        "bitspark_deposit_credentials": {
          "iban": "CZ8801000001152130170277",
          "bank_name": "Komercni Banka, a.s.",
          "reference": "9120255451",
          "swift_code": "KOMBCZPP",
          "bank_address": "Na Prikope 33 cp. 969 114 07 Praha 1",
          "account_number": "",
          "beneficiary_name": "Valoris HK Limited",
          "account_holder_address": "5- 109 Argyle Street Richmond Commercial , Kowloon, 00000, Hong Kong"
        },
        "currency_type": "banknote",
        "precision": 2
      }
    }
  ]
}

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "User account already been taken with 'pending' status in scope of specified shop account"
      ]
    }
  ]
}

ENDPOINT

/v1/top_ups

DESCRIPTION

This endpoint creates new top_up.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Can be any subset of: locked_commision, user_account.currency, shop_account.currency

FORM DATA

Key Required Type Default Description
shop_code true [uuid] Shop Identifier from shop’s QR code
currency true [string] Top Up currency ( should be one of Available Currencies codes )
data[type] true [string] Top Up’s type ( must be top_ups)
data[attributes][amount] true [decimal] Amount of money to be received by user ( should be greater than 0.0)

Cancel Top Up

REQUEST

PUT /v1/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/cancel HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X PUT "https://api.bitspark.io/v1/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/cancel" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE (success)

  { "Success": "200 OK" }

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "Top-up can not be canceled"
      ]
    }
  ]
}

ENDPOINT

/v1/top_ups/:top_up_id/cancel

DESCRIPTION

This endpoint cancels existing pending top_up by it’s ID.

Approve Top Up

REQUEST

PUT /v1/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/approve HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X PUT "http://api.bitspark.io/v1/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/approve" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE (success)

  { "Success": "200 OK" }

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "Top-up can not be approved"
      ]
    }
  ]
}

ENDPOINT

/v1/top_ups/:top_up_id/approve

DESCRIPTION

This endpoint approve existing top_up by it’s ID.

Decline Top Up

REQUEST

PUT /v1/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/decline HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X PUT "http://api.bitspark.io/v1/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/decline" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE (success)

  { "Success": "200 OK" }

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "Top-up can not be declined"
      ]
    }
  ]
}

ENDPOINT

/v1/top_ups/:top_up_id/decline

DESCRIPTION

This endpoint declines existing top_up by it’s ID.

Get Top Up

REQUEST

GET /v1/top_ups/fffffffff-ffff-ffff-ffff-ffffffffff?include=locked_commision,user_account.currency, HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/top_ups/fffffffff-ffff-ffff-ffff-ffffffffff?include=locked_commision,user_account.currency" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE

{
"data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "top_ups",
    "attributes": {
      "status_code": "pending",
      "status_message": "Pending",
      "amount": "10.0",
      "currency": "HKD",
      "shop_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "receipt_url": null,
      "performed_by_shop": false,
      "transaction_number": "TU-161007-981-51TF"
    },
    "relationships": {
      "user_account": {
        "data": {
          "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
          "type": "accounts"
        }
      },
      "shop_account": {
        "data": {
          "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
          "type": "accounts"
        }
      },
      "locked_commission": {
        "data": {
          "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
          "type": "locked_commissions"
        }
      }
    }
  },
  "included": [
    {
      "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "type": "locked_commissions",
      "attributes": {
        "shop_commission": "0.0",
        "bitspark_commission_percentage": "50.0"
      }
    }
    {
      "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
      "type": "accounts",
      "attributes": {
        "balance": "100.0",
        "shop_commission": "0.0",
        "balance_threshold": "0.0"
      },
      "relationships": {
        "currency": {
          "data": {
            "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
            "type": "currencies"
          }
        }
      }
    },
    {
      "id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "type": "currencies",
      "attributes": {
        "code": "hkd",
        "name": "HKD",
        "account": true
      }
    },
    "..."
  ]
}

ENDPOINT

/v1/top_ups/:top_up_id

DESCRIPTION

This endpoint get existing top_up by it’s ID.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Can be any subset of: locked_commision, user_account.currency, shop_account.currency

Top Ups V2

Top Ups History

REQUEST

GET /v2/top_ups/fffffffff-ffff-ffff-ffff-ffffffffff?include=transaction_fee,currency, HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v2/top_ups/fffffffff-ffff-ffff-ffff-ffffffffff?include=transaction_fee,currency" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
      "type": "top_ups",
      "attributes": {
        "status_code": "pending",
        "status_message": "Pending",
        "amount": "10.0",
        "shop_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
        "receipt_url": null,
        "performed_by_shop": false,
        "transaction_number": "TU-161007-981-51TF"
      },
      "relationships": {
        "user_account": {
          "data": {
            "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
            "type": "accounts"
          }
        },
        "shop_account": {
          "data": {
            "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
            "type": "accounts"
          }
        },
        "transaction_fee": {
          "data": {
            "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
            "type": "fees_transactions"
          }
        },
        "currency": {
          "data": {
            "id": "gggggggg-gggg-gggg-gggg-gggggggggggg",
            "type": "currencies"
          }
        }
      }
    },
    "..."
  ],
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "fees_transactions",
      "attributes": {
        "amount": "0.0",
        "bitspark_percentage": "50.0"
      }
    },
    {
      "id": "gggggggg-gggg-gggg-gggg-gggggggggggg",
      "type": "currencies",
      "attributes": {
        "code": "hkd",
        "name": "HKD",
        "account": true
      }
    },
    "..."
  ]
}

ENDPOINT

/v2/top_ups

DESCRIPTION

This endpoint retrieves all created top ups with details.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Can be any subset of: transaction_fee, user_account, shop_account, currency
filter[top_up_type] false [string] requested Can be any one of: requested, owned

Create Top Up

REQUEST

POST /v2/top_ups?include=transaction_fee,currency HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded
shop_code=ffffffff-ffff-ffff-ffffffffffffcurrency=usddata%5Btype%5D=top_upsdata%5Battributes%5D%5Bamount%5D=10.0
curl -X POST "https://api.bitspark.io/v2/top_ups?include=transaction_fee,currency" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache" \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'shop_code=ffffffff-ffff-ffff-ffffffffffff&currency=usd&data%5Btype%5D=top_ups&data%5Battributes%5D%5Bamount%5D=10.0'

RESPONSE (success)

{
  "data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "top_ups",
    "attributes": {
      "status_code": "pending",
      "status_message": "Pending",
      "amount": "10.0",
      "shop_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "receipt_url": null,
      "performed_by_shop": false,
      "transaction_number": "TU-180622-2249-PQ3C"
    },
    "relationships": {
      "user_account": {
        "data": {
          "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
          "type": "accounts"
        }
      },
      "shop_account": {
        "data": {
          "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
          "type": "accounts"
        }
      },
      "transaction_fee": {
        "data": {
          "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
          "type": "fees_transactions"
        }
      },
      "currency": {
        "data": {
          "id": "gggggggg-gggg-gggg-gggg-gggggggggggg",
          "type": "currencies"
        }
      }
    }
  },

  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "fees_transactions",
      "attributes": {
        "amount": "0.0",
        "bitspark_percentage": "50.0"
      }
    },
    {
      "id": "gggggggg-gggg-gggg-gggg-gggggggggggg",
      "type": "currencies",
      "attributes": {
        "code": "hkd",
        "name": "HKD",
        "account": true,
        "banknote": true,
        "bitspark_deposit_credentials": {
          "iban": "CZ8801000001152130170277",
          "bank_name": "Komercni Banka, a.s.",
          "reference": "9120255451",
          "swift_code": "KOMBCZPP",
          "bank_address": "Na Prikope 33 cp. 969 114 07 Praha 1",
          "account_number": "",
          "beneficiary_name": "Valoris HK Limited",
          "account_holder_address": "5- 109 Argyle Street Richmond Commercial , Kowloon, 00000, Hong Kong"
        },
        "currency_type": "banknote",
        "precision": 2
      }
    }
  ]
}

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "User account already been taken with 'pending' status in scope of specified shop account"
      ]
    }
  ]
}

ENDPOINT

/v2/top_ups

DESCRIPTION

This endpoint creates new top_up.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Can be any subset of: transaction_fee, user_account, shop_account, currency

FORM DATA

Key Required Type Default Description
shop_code true [uuid] Shop Identifier from shop’s QR code
currency true [string] Top Up currency ( should be one of Available Currencies codes )
data[type] true [string] Top Up’s type ( must be top_ups)
data[attributes][amount] true [decimal] Amount of money to be received by user ( should be greater than 0.0)

Cancel Top Up

REQUEST

PUT /v2/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/cancel HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X PUT "https://api.bitspark.io/v2/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/cancel" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE (success)

  { "Success": "200 OK" }

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "Top-up can not be canceled"
      ]
    }
  ]
}

ENDPOINT

/v2/top_ups/:top_up_id/cancel

DESCRIPTION

This endpoint cancels existing pending top_up by it’s ID.

Approve Top Up

REQUEST

PUT /v2/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/approve HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X PUT "http://api.bitspark.io/v2/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/approve" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE (success)

  { "Success": "200 OK" }

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "Top-up can not be approved"
      ]
    }
  ]
}

ENDPOINT

/v2/top_ups/:top_up_id/approve

DESCRIPTION

This endpoint approve existing top_up by it’s ID.

Decline Top Up

REQUEST

PUT /v2/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/decline HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X PUT "http://api.bitspark.io/v2/top_ups/ffffffff-ffff-ffff-ffff-ffffffffffff/decline" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache" \

RESPONSE (success)

  { "Success": "200 OK" }

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": [
        "Top-up can not be declined"
      ]
    }
  ]
}

ENDPOINT

/v2/top_ups/:top_up_id/decline

DESCRIPTION

This endpoint declines existing top_up by it’s ID.

Get Top Up

REQUEST

GET /v2/top_ups/fffffffff-ffff-ffff-ffff-ffffffffff?include=transaction_fee,currency, HTTP/1.1
Host: api.bitspark.io
Key: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X GET "http://api.bitspark.io/v2/top_ups/fffffffff-ffff-ffff-ffff-ffffffffff?include=transaction_fee,currency" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE

{
"data": {
    "id": "ffffffff-ffff-ffff-ffff-ffffffffffff",
    "type": "top_ups",
    "attributes": {
      "status_code": "pending",
      "status_message": "Pending",
      "amount": "10.0",
      "shop_id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "receipt_url": null,
      "performed_by_shop": false,
      "transaction_number": "TU-161007-981-51TF"
    },
    "relationships": {
      "user_account": {
        "data": {
          "id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
          "type": "accounts"
        }
      },
      "shop_account": {
        "data": {
          "id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
          "type": "accounts"
        }
      },
      "fees_transactions": {
        "data": {
          "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
          "type": "locked_commissions"
        }
      },
      "currency": {
        "data": {
          "id": "gggggggg-gggg-gggg-gggg-gggggggggggg",
          "type": "currencies"
        }
      }
    }
  },
  "included": [
    {
      "id": "eeeeeeee-eeee-eeee-eeee-eeeeeeeeeeee",
      "type": "fees_transactions",
      "attributes": {
        "amount": "0.0",
        "bitspark_percentage": "50.0"
      }
    },
    {
      "id": "gggggggg-gggg-gggg-gggg-gggggggggggg",
      "type": "currencies",
      "attributes": {
        "code": "hkd",
        "name": "HKD",
        "account": true
      }
    },
    "..."
  ]
}

ENDPOINT

/v2/top_ups/:top_up_id

DESCRIPTION

This endpoint get existing top_up by it’s ID.

REQUEST PARAMS

Key Required Type Default Description
include false [string] none Can be any subset of: transaction_fee, user_account, shop_account, currency

Memos

All memos (BTS, ZEPH)

REQUEST

GET /v1/memos HTTP/1.1
Host: api.bitspark.io
KEY: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/memos" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN" \
    -H "Cache-Control: no-cache"

RESPONSE

{
  "data": [
    {
      "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
      "type": "memos",
      "attributes": {
        "code": "ffffffffff",
        "is_used": "false",
        "created_at": "2012-12-12 12:12:12.579Z"
      },
      "relationships": {
        "user": {
          "data": {
            "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
            "type": "users"
          }
        },
        "currency": {
          "data": null
        }
      }
    },
    "..."
  ]
}

ENDPOINT

/v1/memos

DESCRIPTION

This endpoint retrieves all user memos for BTS and ZEPH currencies.

REQUEST PARAMS

Key Required Type Default Description
is_used false [boolean] none Filter by is_used field

RESPONSE DETAILS

Key Type Description
code [string] Memo code
is_used [boolean] Returns true if memo already in use
created_at [date] Creation date of memo
relationships[user] [hash] User that belongs to memo

All addresses (BTC, ETH)

REQUEST

GET /v1/deposit_addresses HTTP/1.1
Host: api.bitspark.io
KEY: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X GET "https://api.bitspark.io/v1/deposit_addresses" \
    -H "Cache-Control: no-cache" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN"

RESPONSE

{
  "data": [
    {
      "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
      "type": "memos",
      "attributes": {
        "code": "ffffffffff",
        "is_used": "false",
        "created_at": "2012-12-12 12:12:12.579Z"
      },
      "relationships": {
        "user": {
          "data": {
            "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
            "type": "users"
          }
        },
        "currency": {
          "data": {
            "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
            "type": "currencies"
          }
        }
      }
    },
    "..."
  ]
}

ENDPOINT

/v1/deposit_addresses

DESCRIPTION

This endpoint retrieves all user addresses for BTC & ETH currencies.

REQUEST PARAMS

Key Required Type Default Description
is_used false [boolean] none Filter by is_used field
currency false [string] none Filter by currency

RESPONSE DETAILS

Key Type Description
code [string] Address
is_used [boolean] Returns true if address already in use
created_at [date] Creation date of address
relationships[user] [hash] User that belongs to address
relationships[currency] [hash] Currency that belongs to address

Generate memo (BTS, ZEPH)

REQUEST

POST /v1/memos HTTP/1.1
Host: api.bitspark.io
KEY: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X POST "https://api.bitspark.io/v1/memos" \
    -H "Cache-Control: no-cache" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN"

RESPONSE

{
  "data": [
    {
      "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
      "type": "memos",
      "attributes": {
        "code": "ffffffffff",
        "is_used": "false",
        "created_at": "2012-12-12 12:12:12.579Z"
      },
      "relationships": {
        "user": {
          "data": {
            "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
            "type": "users"
          }
        },
        "currency": {
          "data": null
        }
      }
    }
  ]
}

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": "Too many unused memos generated"
    }
  ]
}

ENDPOINT

/v1/memos

DESCRIPTION

This endpoint generate user memo for BTS and ZEPH currencies.

RESPONSE DETAILS

Generate address (BTC, ETH)

REQUEST

POST /v1/deposit_addresses?currency=btc HTTP/1.1
Host: api.bitspark.io
KEY: YOUR_API_KEY
Sign: COMPUTED_SIGN
Cache-Control: no-cache
curl -X POST "https://api.bitspark.io/v1/deposit_addresses?currency=btc" \
    -H "Cache-Control: no-cache" \
    -H "Key: YOUR_API_KEY" \
    -H "Sign: COMPUTED_SIGN"

RESPONSE

{
  "data": [
    {
      "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
      "type": "memos",
      "attributes": {
        "code": "ffffffffff",
        "is_used": "false",
        "created_at": "2012-12-12 12:12:12.579Z"
      },
      "relationships": {
        "user": {
          "data": {
            "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
            "type": "users"
          }
        },
        "currency": {
          "data": {
            "id": "fffffffff-ffff-ffff-ffff-fffffffffff",
            "type": "currencies"
          }
        }
      }
    }
  ]
}

RESPONSE (fail)

{
  "errors": [
    {
      "code": 422,
      "error_code": "unprocessable_request",
      "message": "Too many unused memos generated"
    }
  ]
}

ENDPOINT

/v1/deposit_addresses

DESCRIPTION

This endpoint generate user address for BTC & ETH currencies.

REQUEST PARAMS

Key Required Type Default Description
currency true [string] none Account currency for which will be created address

RESPONSE DETAILS

Transfer statuses list

The Bitspark API uses following status codes for transfers:

Status Meaning From statuses
unknown Initial status, presented only a few seconds after a new transfer is initialized
performing Async worker starts to perform a transfer. unknown
remittance_received_successfully Success remittance calculation response that is received external payment provider. performing
remittance_received_unsuccessfully Unsuccess remittance calculation. performing
payment_created_successfully Payment created successfully on external payment provider side. remittance_received_successfully
payment_created_unsuccessfully Payment created unsuccessfully on external payment provider side(can be presented because of some additional validation on external provider side or external provider currently unavailable). remittance_received_successfully
insufficient_funds Not enough funds to perform a transfer. performing, payment_created_successfully, proved, confirmed
payment_commited_successfully Successfully confirmed previously created payment on external payment provider. payment_created_successfully
payment_commited_unsuccessfully Unsuccessfully confirmed previously created payment on external payment provider. payment_created_successfully
declined Cancelled/declined by external service or admin. payment_commited_successfully, accepted, refund
accepted Transfer is successfully accepted by external payment service. payment_commited_successfully
confirmed Transfer is confirmed by external service or by admin. payment_commited_successfully, accepted
proved Transfer is successfully finalized. After 10 days confirmed and accepted transfers will be changed to proved status automatically. confirmed, accepted
failed Transfer finalization fails.
payout_failed Error when external service successfully received payment but cannot perform send money to selected the origin.
refund_requested Refund requested. payment_created_successfully, payment_commited_successfully, accepted, confirmed
refund_responce_received Bitspark system receive a callback with refund created from external service(not all external services send callbacks about refund). refund_requested
refund_confirmed Refund is confirmed by admin or external service(if possible). It means that funds refunded to Bitspark user’s balance. refund_requested, refund_responce_received
refund_rejected Refund is rejected by admin or external service. Funds are not returned, for details contact admin. refund_requested, refund_responce_received
suspicious Transfer is detected as suspicious. For /v1/transactions/remittances Transfers History this status is payment_created_successfully payment_created_successfully, payment_commited_successfully, accepted confirmed
amount_too_small An amount is too small to make a transfer. performing

Errors

The Bitspark API uses the following error codes:

Code Error Code Meaning
400 bad_request Bad Request – Invalid request body.
400 money_exchange_error Transaction failed.
400 payment_cancel_error Payment cancel: Something went wrong.
400 payment_deposit_error Deposit: Something went wrong. Please check request body.
400 payment_withdraw_error Withdraw: Something went wrong. Please check request body.
400 payment_cancel_error Payment cancel: Something went wrong.
400 top_up_error Top-up: Something went wrong. Please check request body.
400 send_money_error Send Money: Something went wrong. Please check request body.
400 send_domestic_money_error Send Domestic Money: Something went wrong. Please check request body.
401 unauthorized YOUR_API_KEY or COMPUTED_HMAC is wrong
403 forbidden Access Denied
403 insufficient_permissions You have insufficient permissions to access this endpoint.
404 not_found Could not find record
406 not_acceptable Specified request format not matches Json-API specifications
422 unprocessable_entity The record with specified attributes could not be processed.
500 internal_server_error We had a problem with our server. Try again later.
501 invalid_logger_error Invalid logger
501 not_specified_error Not specified
503 service_unavailable We’re temporarially offline for maintanance. Please try again later.