Payment buttons and API description

Payment buttons

In order to receive payments in exchange for goods or services via the PaymentBar gateway, payers should be directed to the URL that was generated beforehand.
One of the easiest ways is an embedding of payment buttons (see Generator) or redirection of the user to the URL generated by this utility.

Code sample:

<a href="https://go.paymentbar.com/api/v2/make?pay_to_btc=161GZJfEqRk3gt2ueuBUdYyVk12BXEuaZe&amount=14.95&note_url=http://example.com/callback.php&shop_name=My%20sample%20webshop" target=_self>Pay by Bitcoin</a>

In order to check whether last payment was processed successful or not, you also need to integrate into your system a script that checks the status of the payment with the help of “check” method that is called when callback from the system has gotten (download sample) – its URL is specified in the “note_url” argument.

Specification for developers

HTTP REQUEST:
GET / POST https://go.paymentbar.com/api/v2/[make|check]?arguments

METHODS:
make, check

“make” method – is responsible for billing

“make” method returns the payment page (if there is no argument in format=json under which data returns in JSON format).

Example:
GET https://go.paymentbar.com/api/v2/make?pay_to_btc=161GZJfEqRk3gt2ueuBUdYyVk12BXEuaZe&amount=14.95&note_url=http://example.com/callback.php&shop_name=My%20sample%20webshop

Obligatory parameters:

pay_to_[btc|ltc|doge] cryptocurrency wallet address where the funds are going to be transferred after they are received from buyer. You need to specify one of the following wallets in the inquiry: pay_to_btc, pay_to_ltc, pay_to_doge.

amount price of the good in USD, minimum $0.05

Non-obligatory parameters:

note_url URL for callback-notifications (two parameters are going to be sent: invoice_id and ctx)

shop_name shop name

desc product description

format json|redirect (default: redirect), redirect – redirects to our payment form, json – invoice information output in JSON format

shop_url shop URL

back_url page URL where the buyer should be directed after successful payment

cancel_url cancel payment page URL

email seller email where the notifications of regular transaction confirmation are going to be sent (up to 6 transactions)

ctx contents of this parameter return by callback in an invariant form. For example, you can specify the id of the good taken from your shop system or user id or a set of data)


Callback-notifications

Callback calls are made with POST method to URL which is specified in “note_url” argument in the following cases:

  • the first appearance of the transaction in blockchain,

  • first six confirmations of transaction,
  • sending of funds to the shop wallet.

There are two parameters in notifications:

invoice_id invoice id in our system,

ctx contents of this parameter is transmitted in an invariant form just like it was set in “make” method.

As soon as notification comes the shop must call the “check” method to check the payment status.

“check” method – is responsible for payment status checking

GET https://go.paymentbar.com/api/v2/check?id=invoice_id

There is only one argument of call – invoice_id which was gotten during callback.

If there is no invoice ID, null returns.

The following features must be certainly checked in reply:

status – paid invoice has one of the following statuses:”fill”, “soft”, “hard”, “closed” (details below),
data.amount – the sum must coincide with the one that was transmitted by “make” method,
data.currencies[N].amount – must coincide with data.currencies[N].filled,
data.currencies[N].confirmations – must be non-zero
data.currencies[N].pay_to – wallet number must coincide with the one that was transmitted by “make” method to be sure of system non-interference.

Depending on invoice status and number of confirmations the shop is able to consider an item to be paid or not by itself. In general, the invoice may be considered as paid, if it gets “hard” status

Parameters in reply:

id invoice ID

status payment status. Possible values:
new – invoice is created
fill – transaction appeared in blockchain
soft – first confirmation has gotten
hard – six confirmations have gotten
closed – funds are transferred to shop wallet
invalid – invoice error is occurred

created payment creation date (GMT+0)

expires exchange rate updating date, if status=new (GMT+0)

data.shop_name Shop name

data.desc product description

data.msg message to buyer

data.lang interface language

data.ttl exchange rate lifetime

data.ctx parameter for callback-URL

data.shop_url shop URL

data.note_url URL for notifications

data.back_url URL for return to shop after payment

data.cancel_url URL for payment cancellation

data.error_url error page URL

data.icon_url shop icon URL

data.email seller email

data.amount amount of money in USD

data.currencies[N].amount must coincide with data.currencies[N].filled

data.currencies[N].confirmations amount of transaction confirmations,

data.currencies[N].pay_to number of your wallet where the payment should be transferred. It must coincide with those that was transmitted by method

data.currencies[N].filled how many get into the wallet

data.currencies[N].pay_from wallet of PaymentBar system where the funds are going to get to including service rate and transaction fee

Reply sample:

{
    "id": "d6767cc37fdk333c6ea52d0f134b8bf3", 
    "status": "new",
    "created": "2015-06-09 08:24:34", 
    "expires": "2015-06-09 08:39:34", 
    "data": {
        "shop_name": "asdad", 
        "desc": "", 
        "msg": null,
        "lang": null, 
        "ttl": 900, 
        "ctx": null, 
        "shop_url": null, 
        "note_url":   "http:\/\/www.example.com\/paymentbar_callback.php",  
        "back_url": null, /
        "cancel_url": null,
        "error_url": null, 
        "icon_url": null, 
        "email": null, 
        "amount": 0.49, 
        "currencies": [
            {   
                "label": "btc",
                "amount":  0.00212029,  
                "pay_to":   "161GZJfEqRk3gt2ueuBUdYyVk12BXEuaZe",
                "pay_from": "1GUgQwkdutm27wLrmFBXfpy6Az2dQ36f5x", 
                "filled": 0, 
                "confirmations": 0 
            },
            { 
                "label": "ltc",
                "amount": 0.27176927,
                "pay_to": "LSA7HpG6khzYXY5mCMEBGbiUHZYqUJQz4A",
                "pay_from": "LKkxCvkpi5EQvTzH1HdHeSEycvCGxQTmUs",
                "filled": 0,
                "confirmations": 0
            },
            { 
                "label": "doge",
                "amount": 3154.16800772,
                "pay_to": "D88Tp4Bkx4nDXRxD2St69s1okBKnHqMUt6",
                "pay_from": "DHNLkAQwjmoVHVzBg2LbwaanBMRtJZS58H",
                "filled": 0,
                "confirmations": 0
            }
        ]
    },
    "created_timestamp": "1433838274",
    "expires_timestamp": "1433839174"
}