Introduction

Arf API is REST based API that allows fast and easy integration. We use HTTPS for transport and return all responses encoded as JSON.
API ENDPOINT
 
https://merchant.arf.one/

Authentication

Arf uses Header for authentication. All requests to our API have to be authenticated and all requests have to be made over HTTPS.

Authentication proceeds with "public key" and "secret key". You can find these keys in your "Settings" page.

These are encoded as HTTP headers named:

-arf-nonce
-arf-publickey
-arf-signature

curl https://merchant.arf.one/events
-H "arf-nonce: 1554916410189"
-H "arf-publickey: public_key"
-H "arf-signature: 148b24e2a8bb75f1922cb348167199f0413ebd950deedb5f7081171524d11599" 

Example for how the signatureis created(Nodejs)

const crypto = require('crypto')
const request = require('request')
 
const publicKey = '...'
const secretKey = '...'
 
const path  = 'events/'
const nonce = Date.now()
const body  = {}
 
    let signature = {
        "body" : body,
        "nonce": nonce,
        "path" : path
    }
 
const sig = crypto.createHmac('sha256',secretKey).update(signature)
   
const sigHex = sig.digest('hex')
 
const options = {
url: `https://merchant.arf.one/${path}`,
method: 'POST',
     
headers: {
        'Content-Type' : 'application/json',
        'arf-nonce'    : nonce,
        'arf-publickey': publicKey,
        'arf-signature': sigHex
      },
     
body: body,
json: true
    }
    request.post(options, (error, response, body) => {
      console.log(body);
    })

Error Handling

Arf API is using HTTP codes to indicate result of API call. Codes in range 2xx indicate success, codes in range 4xx indicate error on your side (something is wrong with your request) and codes in range 5xx indicate error on our side.

If request resulted in error then an error object is returned instead of normal response.

200 OK - Successful request
400 Bad Request - Request has invalid data or is missing a required field
401 Unauthorized - Provided API key is missing or invalid
402 Payment failed - Request was valid but card processing has failed
404 Not Found - Requested object was not found
 
500, 502, 503, 504 Server error - Something went wrong on our side

500, 502, 503, 504 Server error - Something went wrong on our side    

Metadata

Most of updatable objects have metadata attribute that can be used to store custom pairs of key-value data.

This is useful for storing additional structured information associated with given object. Example would be to save user login together with a customer object that represents that user.

Each key must be unique within given metadata object.

"metadata": {
    "param1": "value-1",
    "param2": "value-2"
}

Product

Product represents the monetary value that will be charged to your customer.

Products are used when the charge is a 1-time micro-payment (e.g. an item in a game) or subscription type. 


Arguments

name: string
Name of the product


description: string
Short description of the product (optional)


productId: string
Unique ID of the product.


serviceName: string
The name of the service that your product belongs to. Arf supports multiple services (e.g. different mobile apps) under a single company.


productType: string
        SUB_1_M: 1 month subscription
        SUB_3_M: 3 month subscription
        SUB_6_M: 6 month subscription
        SUB_1_Y: 12 month subscription
        MC:  1-time micro-payment type


price: float
USD Price of the product

{
    "name": "Product 1",
    "description": "Product 1",
    "productId": "Product_1",
    "serviceName": "ABCDE",
    "productType": "SUB_1_M",
    "price": 24.99
}

Purchase

Purchase object is returned to you as a result of related function calls, explained below. It includes necessary information about a single purchase.


Arguments

currency: string
The type of currency the user made the purchase with (e.g. “BTC”)

price: float
The value of the cryptocurrency that the user paid.

rate: float
The USD equivalent of the cryptocurrency that the user paid with at the exact time of the purchase.

purchasedDate: date
The time of the purchase

{
    "currency": "BTC",
    "price": 0.0043,
    "rate": 3929.58,
    "purchasedDate": "2019-03-26T13:06:19.000Z"
}

Subscriptions

Subscription represents manual recurring payment that will result in charge to be created for given customer, always at the customer’s discretion. 

Frequency and amount of these automatic charges is defined by a product. 


Subscriptions are always billed to customer's Bitcoin Wallet.


Arguments


id: string
Identifier of a subscription.


customerId: string
Identifier of the customer who paid for this subscription.


startedDate: Date

The date when the subscription started


endsDate: Date
The date when the subscription ends/ended


product: object
Product


metadata: object
Metadata


purchase: object
Purchase


createdAt: date
The date when the subscription object is created

Request:
/subscriptions
 
Response:
[
    {
        "id": "sub_lamKHQWY8LojNgP7xT64ktT7",
        "customerId": "cust_7JGxv7Z5Oghp7tzf1V8EIIzC",
        "startedDate": "2019-03-19T15:34:03.000Z",
        "endsDate": "2019-03-20T15:34:03.000Z",
        "product": {
            "name": "Product 1",
            "description": "Product 1",
            "serviceName": "ABCDE",
            "productId": "Product_1",
            "productType": "SUB_1_M"
        },
        "metadata": {},
        "purchase": {
            "currency": "BTC",
            "price": 0.00635946,
            "rate": 3929.58,
            "purchasedDate": "2019-03-24T08:23:18.000Z"
        },
        "createdAt": "2019-03-19T15:34:03.000Z"
    },
    {
        "id": "sub_j6s5rF1HXGdnxiO3brOijq7p",
        "customerId": "cust_BdenwoFia2cZCoM1cqnlAK6K",
        "startedDate": "2019-03-26T13:06:19.000Z",
        "endsDate": "2019-04-26T12:06:19.000Z",
        "product": {
            "name": "Product 2",
            "description": "Product 2",
            "serviceName": "ABCDE",
            "productId": "Product_2",
            "productType": "SUB_1_M"
        },
        "metadata": {},
        "purchase": {
            "currency": "BTC",
            "price": 0.0043,
            "rate": 3929.58,
            "purchasedDate": "2019-03-26T13:06:19.000Z"
        },
        "createdAt": "2019-03-26T13:06:19.000Z"
    }
]
 
           
Request:
 
/subscriptions/sub_lamKHQWY8LojNgP7xT64ktT7
 
Response:
[
    {
        "id": "sub_lamKHQWY8LojNgP7xT64ktT7",
        "customerId": "cust_7JGxv7Z5Oghp7tzf1V8EIIzC",
        "startedDate": "2019-03-19T15:34:03.000Z",
        "endsDate": "2019-03-20T15:34:03.000Z",
        "product": {
                "name": "Product 1",
                "description": "Product 1",
                "serviceName": "ABCDE",
                "productId": "Product_1",
                "productType": "SUB_1_M"
        },
        "metadata": {},
        "purchase": {
            "currency": "BTC",
            "price": 0.00635946,
            "rate": 3929.58,
            "purchasedDate": "2019-03-24T08:23:18.000Z"
        },
        "createdAt": "2019-03-19T15:34:03.000Z"
    }
]

Micro payments

Micro-payments are 1-time payments for pre-defined products (e.g. an item in a game)

Arguments

id: string
Identifier of a micro-payment.

customerId: string
Identifier of the customer who made this micro-payment.

product: object
Product

metadata: object
Metadata


purchase: object
Purchase


createdAt: date

The date when the micro-payment object is created.

Request:
/microPayments
 
Response:
[
    {
        "id": "mp_X4kgkjM2ZNX7S2h9QYygFL6p",
        "customerId": "cust_sCyhMjnM9pKGe9ma3MGMh6rz",
        "product": {
            "name": "Product 3",
            "description": "Product 3",
            "serviceName": "ABCDEFG",
            "productId": "Product_3",
            "productType": "MP",
            "price": 9.99
        },
        "metadata": {},
        "purchase": {
            "currency": "BTC",
            "price": 0.00241189,
            "rate": 4141.99,
            "purchasedDate": "2019-04-01T15:02:53.000Z"
        },
        "createdAt": "2019-04-01T15:02:53.000Z"
    },
    {
        "id": "mp_55zXNiKSHgsz5YVcTzMMFSB4",
        "customerId": "cust_sCyhMjnM9pKGe9ma3MGMh6rz",
        "product": {
            "name": "Product 4",
            "description": "Product 4",
            "serviceName": "ABCDEFG",
            "productId": "Product_3",
            "productType": "MP",
            "price": 12.00
        },
        "metadata": {},
        "purchase": {
            "currency": "BTC",
            "price": 0.00289944,
            "rate": 4138.73,
            "purchasedDate": "2019-04-01T16:16:46.000Z"
        },
        "createdAt": "2019-04-01T16:16:46.000Z"
    }
]
 
Request:
/microPayments/mp_X4kgkjM2ZNX7S2h9QYygFL6p
 
Response:
[
    {
        "id": "mp_X4kgkjM2ZNX7S2h9QYygFL6p",
        "customerId": "cust_sCyhMjnM9pKGe9ma3MGMh6rz",
        "product": {
            "name": "Product 3",
            "description": "Product 3",
            "serviceName": "ABCDEFG",
            "productId": "Product_3",
            "productType": "MP",
            "price": 9.99
        },
        "metadata": {},
        "purchase": {
            "currency": "BTC",
            "price": 0.00241189,
            "rate": 4141.99,
            "purchasedDate": "2019-04-01T15:02:53.000Z"
        },
        "createdAt": "2019-04-01T15:02:53.000Z"
    }
]

Events

Events can be used to get notification when something interesting has happened. 

For example creation of new successful purchase will result in PURCHASE_SUCCEEDED event. 


We provide API methods to retrieve a single event and to list multiple events.


It is also possible get notifications about new events by using Webhooks.


Arguments

id: string
Identifier of the event


type: string
Type of the event


data: object

            rate: float
            The USD equivalent of the cryptocurrency that the user paid with 
            at the exact time of the purchase.

            price: float
            The value of the cryptocurrency that the user paid.

            currency: string
            The type of currency the user made the purchase with (e.g. “BTC”)

            metadata: object
            Metadata

            productId: string
            Identifier of the product

            customerId: string        
            Identifier of the customer who made the purchase.

            createdAt: date    
            The date when the event is created.


Request:
/events
 
Response
[
    {
        "id": "event_5qrbFBLVUjt2LSCtjpsEBizp",
        "type": "PURCHASE_SUCCEEDED",
        "data": {
            "rate": 5195.08,
            "price": 0.00481033,
            "currency": "BTC",
            "metadata": {},
            "productId": "Product_2",
            "customerId": "cust_PIiIVSbFqcMelX8ok4GXe52r"
        },
        "createdAt": "2019-04-08T11:23:33.000Z"
    }
]
 
 
Request:
/events/event_5qrbFBLVUjt2LSCtjpsEBizp
 
Response:
[
    {
        "id": "event_5qrbFBLVUjt2LSCtjpsEBizp",
        "type": "PURCHASE_SUCCEEDED",
        "data": {
            "rate": 5195.08,
            "price": 0.00481033,
            "currency": "BTC",
            "metadata": {},
            "productId": "Product_2",
            "customerId": "cust_PIiIVSbFqcMelX8ok4GXe52r"
        },
        "createdAt": "2019-04-08T11:23:33.000Z"
    }
]