Developers page | ALFAcoins payment processor

Application Programming Interface

API - Application programming interface, IPN - Instant Payment Notification.
If you don't accept the variant with fixed amount payment button, then API+IPN will be glad to help any programmer. Payment, that valid for payment only 15 minutes, can be created by REST/JSON-RPC call. ALFAcoins send notification to merchant on status change for payment. Status definition can be location on statuses page.
All requests are only available via HTTPS, in the interest of security best practices we do not support API calls over HTTP.
We support both REST and JSON-RPC calls. To use JSON-RPC calls please add .json at the end of request.
Add our IP 138.201.230.93 to whitelist.

POST Requests

We support both REST and JSON-RPC calls. JSON-RPC is recommended as we will deprecate REST over time.

Supported Payment Methods (Cryptocurrencies)

Supported cryptocurrencies and other payment methods.



  
  
    Type Code Payment Method Currency Code Confirmations
  
  
    
    bitcoin
    
 Bitcoin
    BTC
    2
  
  
    litecoin
    
 Litecoin
    LTC
    6
  
  
    ethereum
    
 Ethereum
    ETH
    12
  
  
    bitcoincash
    
 Bitcoin Cash
    BCH
    2
  
  
    dash
    
 Dash
    DASH
    6
  
  
    xrp
    
 XRP
    XRP
    1
  
  
    litecointestnet
    
 Litecoin Testnet
    LTCT
    2

Type Code	Payment Method	Currency Code	Confirmations
bitcoin	Bitcoin	BTC	2
litecoin	Litecoin	LTC	6
ethereum	Ethereum	ETH	12
bitcoincash	Bitcoin Cash	BCH	2
dash	Dash	DASH	6
xrp	XRP	XRP	1
litecointestnet	Litecoin Testnet	LTCT	2

BitSend

BitSend is mainly used to send payouts (e.g. salaries, dividents, affiliate payouts or any other types of automated payouts).

URL (JSON): https://www.alfacoins.com/api/bitsend.json
URL (REST): https://www.alfacoins.com/api/bitsend
Method: POST

Data type: REST/JSON

Data required:
  name = Shop Name of API which you assigned when you create the API
  secret_key = Secret key which is given after API was created
  password = MD5 password hash from API with CAPITAL LETTERS
  type = Payment Method Type Code
  options = (array) Client cryptocurrency address for deposit, and additional tags
    i.e. {"address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm"} for Bitcoin, Litecoin, Ethereum, Dash
    {"address": "qFE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm", "legacy_address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm"} for Bitcoin Cash
    {"address": "rExZpwNwwrmFWbX81AqbKJYkq8W6ZoeWE6", "destination_tag": "1294967290"} for XRP
  amount = Deposit amount in merchant's fiat currency (optional)
  coin_amount = Deposit amount in selected cryptocurrency (optional)
  recipient_name = Client Name (for email notification)
  recipient_email = Client email (for email notification)
  reference = Deposit description (for client notification)

Example data (JSON):
{
  "name": "Bitcoin shop",
  "secret_key": "c4ca4238a0b923820dcc509a6f75849b",
  "password": "C81E728D9D4C2F636F067F89CC14862C",
  "type": "bitcoin",
  "options": {"address": "rExZpwNwwrmFWbX81AqbKJYkq8W6ZoeWE6", "destination_tag": "1294967290"},
  "amount": 1.23412341
}

Example success output (JSON):
{
  "id": "[ALFAcoins BitSend ID]"
}

{error: "Error message"}

BitSend Status

BitSend status primary use to get information of bitsend payout

URL (JSON): https://www.alfacoins.com/api/bitsend_status.json
URL (REST): https://www.alfacoins.com/api/bitsend_status
Method: POST

Data type: REST/JSON
Data required:
  name = Shop Name of API which you assigned when you create the API
  secret_key = Secret key which is given after API was created
  password = MD5 password hash from API with CAPITAL LETTERS
  bitsend_id = (int) Bitsend ID

Example data (JSON):
{
  "name": "Bitcoin shop",
  "secret_key": "c4ca4238a0b923820dcc509a6f75849b",
  "password": "C81E728D9D4C2F636F067F89CC14862C",
  "bitsend_id": 34516,
}

Example success output (JSON):
{
  "status": "[ALFAcoins BitSend Status]",
  "coin_amount": "[Coin amount]",
  "rate": "[Rate between currencies]",
  "type": "[Cryptocurrency used for payout]",
  "txid": "[Transaction ID if BitSend has been successful]",
}

{error: "Error message"}

Create Order

Create order for payment

URL (JSON): https://www.alfacoins.com/api/create.json
URL (REST): https://www.alfacoins.com/api/create
Method: POST

Data type: REST/JSON
Data required:
  name = Shop Name of API which you assigned when you create the API
  secret_key = Secret key which is given after API was created
  password = MD5 password hash from API with CAPITAL LETTERS
  type = Payment Method Type Code
  amount = Deposit amount in merchant's fiat currency
  currency = (Optional) Amount currency. If currency is empty merchant's default currency will be used.
  order_id = Merchant's Order ID
  description = (Optional) Description for order
  options = (Optional) Array
          {
            "notificationURL": "[custom Merchant's URL for payment notification]",
            "redirectURL": "[Merchant's page which is shown after payment is made by a customer]",
            "payerName": "[Customer's name for notification]",
            "payerEmail": "[Customer's email for notification]",
            "hide_warning": "[Hide invoice deposit warning (e.g. warning about bitcoin low fee or requirement of xrp destination tag) (use at your own risk!)]"
          }

Example data (JSON):
{
  "name": "Bitcoin shop",
  "secret_key": "c4ca4238a0b923820dcc509a6f75849b",
  "password": "C81E728D9D4C2F636F067F89CC14862C",
  "type": "bitcoin",
  "amount": 1.23412341,
  "order_id": "Order10001",
  "currency": "USD",
  "description": "Payment for t-shirt ALFAcoins size XXL",
  "options": {
                "notificationURL": "https://www.alfacoinshop.com/notification.php",
                "redirectURL": "https://www.alfacoinshop.com/my/orders/success",
                "payerName": "Victor",
                "payerEmail": "[email protected]"
              }
}

Example success output (JSON):
{
  "id": "[ALFAcoins TXN ID]",
  "address": "[Cryptocurrency deposit address chosen in API]",
  "deposit": "(array) Client cryptocurrency address for deposit, and additional tags",
    //i.e. {"address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm"} for Bitcoin, Litecoin, Ethereum, Dash
    //{"address": "qFE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm", "legacy_address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm"} for Bitcoin Cash
    //{"address": "rExZpwNwwrmFWbX81AqbKJYkq8W6ZoeWE6", "destination_tag": "1294967290"} for XRP
  "coin_amount": "[Amount to pay in cryptocurrency]",
  "url": "[ALFAcoins payment URL]",
  "iframe": "[ALFAcoins iframe URL]"
}

You can also use type=all to get addresses and coin amounts for all available types as one object.
{
  "id": "[ALFAcoins TXN ID]",
  "address": "[Cryptocurrency deposit address chosen in API]",
  "deposit": { 
    "bitcoin": {
        "address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm", 
        "raw_address": {
            "address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm",
        }
    },
    // ...
    "bitcoincash": {
        "address": "qqfgj6sn0cx87mfk2qhu473rz3ahhwugmspxmu3zh6", 
        "raw_address": {
            "address": "qqfgj6sn0cx87mfk2qhu473rz3ahhwugmspxmu3zh6",
             "legacy_address": "mhCy5Dx4DCUpwHnRSRzKtzrbaRjvYbTe58"
        }
    },
    // ...
    "xrp": {
        "address": "rHh2BbtJa475dJn2xDPzt6YDGm786FoQ43",
        "raw_address": {
            "address": "rHh2BbtJa475dJn2xDPzt6YDGm786FoQ43",
            "destination_tag": 1315197330
        },
        "coin_amount": "[Amount to pay in cryptocurrency]",}
  },
  
  "url": "[ALFAcoins payment URL]",
  "iframe": "[ALFAcoins iframe URL]"
}


To test notifications without sending an actual payment add additional parameters in options to your request:
"options" : { 
                    "test":1,
                    "status":"completed"
} 

You can also change status for testing to any possible order status (e.g. "paid").
Notification will be sent to your notificationURL.
Example data (JSON):
{
  "name": "Bitcoin shop",
  "secret_key": "c4ca4238a0b923820dcc509a6f75849b",
  "password": "C81E728D9D4C2F636F067F89CC14862C",
  "type": "bitcoin",
  "amount": 1.23412341,
  "order_id": "Order10001",
  "currency": "USD",
  "description": "Payment for t-shirt ALFAcoins size XXL",
  "options": {
                "notificationURL": "https://www.alfacoinshop.com/notification.php",
                "redirectURL": "https://www.alfacoinshop.com/my/orders/success",
                "payerName": "Victor",
                "payerEmail": "[email protected]",
                "test": 1,
                "status": "completed"
              }
}

Example success output (JSON):
{
  "id":-1000,
  "coin_amount":"0.00228900",
  "url":"https://www.alfacoins.com/iframe/TEST"
}

ALFAcoins will send notification to notificationURL specified earlier.
Example notification (JSON):
{
  "status":"completed",
  "coin_requested_amount":"0.12345678",
  "requested_amount":"0.12345678",
  "amount":"0.12345678",
  "rate":"0.12345678",
  "coin_amount":"0.12345678",
  "currency":"EUR",
  "type":"BTC",
  "date":"2018-04-03 12:57:11"
}

You can also create orders in crypto. For that set currency to one of: 'BTC', 'ETH', 'LTC', 'DASH', 'XRP' or 'BCH' and amount in crypto.
Example data (JSON):
{
  "name": "Bitcoin shop",
  "secret_key": "c4ca4238a0b923820dcc509a6f75849b",
  "password": "C81E728D9D4C2F636F067F89CC14862C",
  "type": "bitcoin",
  "amount": 1.23412341,
  "order_id": "BTC order #1",
  "currency": "BTC"
}

{error: "Error message"}

Get Order Status

Get status of created Order

URL (JSON): https://www.alfacoins.com/api/status.json
URL (REST): https://www.alfacoins.com/api/status
Method: POST

Data type: REST/JSON
Data required:
  name = Shop Name of API which you assigned when you create the API
  secret_key = Secret key which is given after API was created
  password = MD5 password hash from API with CAPITAL LETTERS
  txn_id = ALFAcoins TXN ID

Example data (JSON):
{
  "name": "Bitcoin shop",
  "secret_key": "c4ca4238a0b923820dcc509a6f75849b",
  "password": "C81E728D9D4C2F636F067F89CC14862C",
  "txn_id": 1005
}

Example success output (JSON):
{
  "status": "[Payment status]",
  "deposit": "(array) Client cryptocurrency address for deposit, and additional tags",
    //i.e. {"address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm"} for Bitcoin, Litecoin, Ethereum, Dash
    //{"address": "qFE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm", "legacy_address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm"} for Bitcoin Cash
    //{"address": "rExZpwNwwrmFWbX81AqbKJYkq8W6ZoeWE6", "destination_tag": "1294967290"} for XRP
  "coin_requested_amount": "[Requested amount in cryptocurrency]",
  "requested_amount": "[Requested amount in fiat]",
  "amount": "[Received amount]",
  "rate": "[Rate between selected cryptocurrency and fiat]",
  "coin_amount": "[Received amount in cryptocurrency]",
  "currency": "[Merchant fiat currency]",
  "type": "[Cryptocurrency name]",
  "date": "[Payment renewal time]",
  "url": "[ALFAcoins payment URL]",
  "iframe": "[ALFAcoins iframe URL]"
}

{error: "Error message"}

Statistics

Get your account current balances and volume statistics

URL (JSON): https://www.alfacoins.com/api/stats.json
URL (REST): https://www.alfacoins.com/api/stats
Method: POST

Data type: REST/JSON
Data required:
  name = Shop Name of API which you assigned when you create the API
  secret_key = Secret key which is given after API was created
  password = MD5 password hash from API with CAPITAL LETTERS

Example data (JSON):
{
  "name": "Bitcoin shop",
  "secret_key": "c4ca4238a0b923820dcc509a6f75849b",
  "password": "C81E728D9D4C2F636F067F89CC14862C",
}

Example success output (JSON):
{
  "balances": {
                "BTC": "[Bitcoin balance]",
                "LTC": "[Litecoin balance]",
                "ETH": "[Ethereum balance]",
                "USD": "[USD Balance]"
              },
  "volume": "[Order's volume]",
  "pending": "[Amount sums of payments that waits for confirmation]",
}

{error: "Error message"}

Order Refund

Order refund. Refund can be issued only on order with completed status.

URL (JSON): https://www.alfacoins.com/api/refund.json
URL (REST): https://www.alfacoins.com/api/refund
Method: POST

Data type: REST/JSON
Data required:
  name = Shop Name of API which you assigned when you create the API
  secret_key = Secret key which is given after API was created
  password = MD5 password hash from API with CAPITAL LETTERS
  txn_id = ALFAcoins TXN ID
  options = (array) Client cryptocurrency address for deposit, and additional tags
    i.e. {"address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm"} for Bitcoin, Litecoin, Ethereum, Dash
    {"address": "qFE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm", "legacy_address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm"} for Bitcoin Cash
    {"address": "rExZpwNwwrmFWbX81AqbKJYkq8W6ZoeWE6", "destination_tag": "1294967290"} for XRP
  amount = (Optional) Amount to refund, must be less Order amount, If omitted full amount will be refunded
  new_rate = (Optional) Use current time rates for fiat to cryptocurrency conversion or use order's rate

Example data (JSON):
{
  "name": "Bitcoin shop",
  "secret_key": "c4ca4238a0b923820dcc509a6f75849b",
  "password": "C81E728D9D4C2F636F067F89CC14862C",
  "txn_id": 1005,
  "address": "1FE7bSYsXSMrdXTCdRUWUB6jGFFba74fzm",
  "amount": 2
}

Example success output (JSON):
{
  "result": "Refund is pending"
}

{error: "Error message"}

GET Requests

We support both REST and JSON-RPC calls. JSON-RPC is preferred over REST.

Limits

Get all gate limits for order creation.

URL (JSON): https://www.alfacoins.com/api/limits.json
URL (REST): https://www.alfacoins.com/api/limits?base=USD
Method: GET

Data type: REST/JSON

Example Request (JSON):
https://www.alfacoins.com/api/limits.json?base=USD

Example Output (JSON):
{"bitcoin": {"min_crypto_amount":0.0001, "min_fiat_amount": 1, "max_crypto_amount":10, "max_fiat_amount":10000}, ...}

Fees

Get all gate fees for deposit and withdrawal. API representation of prices information.

URL (JSON): https://www.alfacoins.com/api/fees.json
URL (REST): https://www.alfacoins.com/api/fees
Method: GET

Data type: REST/JSON

Example Request (JSON):
https://www.alfacoins.com/api/fees.json

Example Output (JSON):
{"bitcoin": {"deposit":{"commission":"0.99%","network_fee":"0 BTC"},"withdrawal":{"commission":"0%","network_fee":"0.00011 BTC"},"bitsend":{"commission":"0.99%","network_fee":"0.00011 BTC"}, ...}

Rate

Get currency rate for specific currency pair

URL (JSON): https://www.alfacoins.com/api/rate/[pair].json
URL (REST): https://www.alfacoins.com/api/rate/[pair]
Method: GET

Data type: REST/JSON

Data required:
  [pair] = Cryptocurrency and fiat Pair, e.g. BTC_USD

Example Request (JSON):
https://www.alfacoins.com/api/rate/BTC_USD.json

Example Success Output (JSON):
["628.51000000"]

{error: "Error message"}

Rates

Get currency rates for all available currency pairs

URL (JSON): https://www.alfacoins.com/api/rates.json
Method: GET

Data type: JSON

Example Request (JSON):
https://www.alfacoins.com/api/rates.json

Example Success Output (JSON):
{
  "BTC":[
          {"code":"USD","rate":628.54},
          {"code":"EUR","rate":579.940948}
        ],
  "LTC":[
          {"code":"USD","rate":3.76613},
          {"code":"EUR","rate":3.474931}
        ],
  "ETH":[
          {"code":"USD","rate":12},
          {"code":"EUR","rate":11.072154}
        ]
}

Rates as dictionary

Get all available currency rates for all available currency pairs as JSON dictionary

URL (JSON): https://www.alfacoins.com/api/rates.dict
Method: GET

Data type: JSON

Example Request (JSON):
https://www.alfacoins.com/api/rates.dict

Example Success Output (JSON):
{
  "BTC": {"USD": 628.54, "EUR": 579.940948},
  "LTC":  {"USD": 3.76613, "EUR": 3.474931}
}

Order Status / IPN

IPN - instant payment notification. When order status changes - ALFAcoins sends a payment notification to the notificationURL.

Order Status

New

This status is used for freshly created payments.

Paid

This status indicates that the invoice has been paid, but payment is yet to be confirmed on the blockchain. NOTE: for final confirmed payment status, see: Completed.

Partially paid

This status indicates that the payment has been partially made (paid amount is less than amount specified in the payment).

Expired

This status indicates that the payment wasn't made within 15 minutes.

Completed

This status indicates that the invoice has been fully paid and confirmed on the blockchain.

Refunded

This status indicates that the payment has been refunded to your customer.

Notification

When order status changes - ALFAcoins sends notification to the notificationURL using POST method with the following format:

id = Number of payment
hash = Payment hash for checking incoming data that consists of
  hash = strtoupper(md5(name:coin_received_amount:received_amount:currency:id:order_id:status:modified:password))
  where:
  name = API name
  password = API uppercase of md5 of password, strtoupper(md5("MD5 of password API in the uppercase."))
received_amount = Received in fiat
currency = Fiat currency (i.e. USD/EUR)
coin_received_amount = Received amount of cryptocurrency
order_id = Merchant's Order ID
status = Current payment status
modified = Last date and time when payment changed

CMS Integration Plugins

Accept payments on your WordPress website with ALFAcoins. No programming required.

WooCommerce plugin

Plugin is available for download at https://wordpress.org/plugins/alfacoins-for-woocommerce/ or https://github.com/ALFAcoins/alfacoins-for-woocommerce.
Follow these steps to install the plugin on your WordPress site:

Download the plugin zip file.
Login to your WordPress Admin. Click on "Plugins | Add New" from the left hand menu.
Click on the “Upload” option, then click “Choose File” to select the zip file from your computer. Once selected, press “OK” and press the "Install Now" button.
Activate the plugin on Plugins page.
Open the settings page for WooCommerce and click the "Payment Gateways" tab.
Click on the sub tab for "ALFAcoins"
Configure your settings.

If you have any troubles, you have found any bugs or you have something to say us, please leave your message on support page.

API Libraries

Library for interacting with ALFAcoins API.

PHP Library

alfacoins-api-php is a PHP Library for interacting with ALFAcoins API.

alfacoins-api-php provides cryptocurrency payment integration on your website via ALFAcoins.

alfacoins-api-php allows you to integrate payments with the following cryptocurrencies:

Bitcoin (BTC)
Ethereum (ETH)
XRP (XRP)
Bitcoin Cash (BCH)
Litecoin (LTC)
Dash (DASH)

Installation

alfacoins-api-php is available on Github, Packagist (using semantic versioning), and installation via composer is the recommended way to install alfacoins-api-php. Just add this line to your composer.json file:

"alfacoins/alfacoins-api-php": "~v1.0"

or run

composer require alfacoins/alfacoins-api-php

Note that the vendor folder and the vendor/autoload.php script are generated by composer; they are not part of alfacoins-api-php.

Alternatively, if you're not using composer, copy the contents of the alfacoins-api-php folder somewhere and load each class file manually:

<?php
// include once ALFAcoins Private API class
require_once '../src/privateAPI.php';
require_once '../src/Exception.php';
use ALFAcoins\ALFAcoins_privateAPI;
use ALFAcoins\ALFAcoins_Exception;

To work with unstable version simply clone this repository:

git clone https://github.com/alfacoins/alfacoins-api-php
cd alfacoins-api-php/

Getting Started

See the examples directory for examples of how to use this library.

Python Library

alfacoins-api-python is a Python (3.6+) Library for interacting with ALFAcoins API by Arash Fatahzade.

alfacoins-api-python provides cryptocurrency payment integration on your website via ALFAcoins.

alfacoins-api-python allows you to integrate payments with the following cryptocurrencies:

Bitcoin (BTC)
Ethereum (ETH)
XRP (XRP)
Bitcoin Cash (BCH)
Litecoin (LTC)
Dash (DASH)

Installation

alfacoins-api-python is available at Github or through PyPi. To install the package you need to have Python 3.6+ and pip installed:

pip3.6 install alfacoins_api_python

Getting Started

See the Getting started section for examples of how to use this library.