× #message#
×

Warning

API Installation Manual

Introduction

API

ForumPay allows users to interact with payment gateway platform programmatically via HTTP API (view, add and cancel payments as well as check if payment was successful). Service URL:

  • https://forumpay.com/api/v2/

Webhook / Instant Payment Notification (IPN)

Webhook Notifications URL can be set to notify when payments status changes.


Performing a call

API calls are generated with URL, followed by endpoint URL and request data. Each API call requires:

  • pos_id

For localization you can use locale parameter:

  • locale

Authentication

API calls are authenticated using HTTP Basic access authentication. You can generate your API key in your Account.


Error handling

On error there will be err element in result. Err value contains error description.


API reference

API calls are performed by sending a HTTP request to URL starting with link, followed by endpoint URL and request data.

Method Request Response
GET /GetRate/?pos_id={pos_id}&invoice_currency={invoice_currency}&invoice_amount={invoice_amount}&currency={currency}&accept_zero_confirmations={accept_zero_confirmations} returns {invoice_amount, invoice_currency, currency, rate, amount_exchange, network_processing_fee, amount, fast_transaction_fee, fast_transaction_fee_currency, wait_time}
GET /StartPayment/?pos_id={pos_id}&invoice_currency={invoice_currency}&invoice_amount={invoice_amount}&currency={currency}&reference_no={reference_no} &accept_zero_confirmations={accept_zero_confirmations} returns {payment_id, invoice_amount, invoice_currency, currency, rate, amount_exchange, network_processing_fee, amount, fast_transaction_fee, fast_transaction_fee_currency, wait_time, address, payment_deeplink, payment_deeplink_alt, qr, qr_alt, qr_img, qr_alt_img, access_token, access_url}
GET /CheckPayment/?pos_id={pos_id}&currency={currency} &payment_id={payment_id}&address={address} returns {reference_no, invoice_amount, invoice_currency, currency, amount, payment, confirmations, min_confirmations, confirmed, confirmed_time, cancelled, cancelled_time, wait_time, status, inserted, access_url, unconfirmed_invoice_amount}
GET /CancelPayment/?pos_id={pos_id}&currency={currency} &payment_id={payment_id}&address={address} returns {cancelled}
GET /AcceptPayment/?pos_id={pos_id}&invoice_no={invoice_no}&currency= {currency}&address={address}&accepted_amount={accepted_amount} &accepted_invoice_amount={accepted_invoice_amount} returns {success}
GET /GetCurrencyList/ returns [{currency, description}...]
GET /GetTransactions/?offset={offset}&limit={limit} returns [{status, pos_id, payment_id, invoice_currency, invoice_amount, currency, amount, address, type, payment, refund, refund_amount_opened, refund_status, invoice_date, inserted, confirmed, cancelled, double_spending_alert, accept_zero_confirmations, item_name, access_token}...]

Replace {text} with request data: (e.g {pos_id} -> POS1, {invoice_currency} -> EUR)

Parameter Meaning
pos_id Point of service identification number for your reference (e.g. POS1, WEB1, ...)
payment_id Payment ID received from StartPayment
reference_no Optional reference number for your record (e.g. invoice or order number)
invoice_no -- deprecated --
invoice_currency Currency code for FIAT currency on invoice (EUR, USD..)
invoice_amount Amount on invoice for FIAT currency
accepted_amount Amount of payment that is being accepted
accepted_invoice_amount Amount of payment being accepted for FIAT currency (should match unconfirmed_invoice_amount)
currency Cryptocurrency symbol (BTC, ETH..)
accept_zero_confirmations Confirms small payment on zero confirmations (use only when POS is under video surveillance)
user Set user id (available for customers with multiple user accounts)
offset How many payments to skip (optional, default 0)
limit Limit how many payments to request (optional, default 20, max 50)
locale Set locale string for requested localization
Output Meaning
rate Exchange rate
amount_exchange Amount to exchange to get value on the invoice
network_processing_fee Amount needed to transfer cryptocurrency from merchant to exchange
amount Total amount to pay
fast_transaction_fee Minimum TX fee/Gas price for fast transacion.
fast_transaction_fee_currency Currency for fast_transaction_fee (e.g.: BTC/byte, Gwei/Gas)
address Address for payment
qr String for qr code that includes cryptocurrency, address and amount
qr_alt Alternative string for qr code for legacy wallets including address only
qr_img URL for qr code image download
qr_alt_img URL for qr_alt code image download
access_token Access token for check payment access
access_url Public URL for check payment preview
payment Received amount of payment
unconfirmed_invoice_amount FIAT currency value of amount that was either underpaid or was paid after cancellation
confirmations Received confirmations of payment
min_confirmations Minimum confirmations to wait (this is informal data. Always wait till confirmed=true)
wait_time Expected time to confirm
confirmed Is transaction successful and confirmed
confirmed_time Time of confirmation
cancelled Is cancellation successful
cancelled_time Time of cancellation
status Status info for user about payment status

Return values

API returns results in JSON format.


Get rate

Display informational rate and amount to customer. Should be refreshed on GUI every five seconds till StartPayment is called.

Example:

https://forumpay.com/api/v2/GetRate/?pos_id=POS1&invoice_currency=EUR&invoice_amount=43.21&currency=BTC&accept_zero_confirmations=true

Response:

{
"invoice_amount": "48.25",
"invoice_currency": "EUR",
"currency": "BTC",
"rate": "6467.18",
"amount_exchange": "0.00701574",
"network_processing_fee": "0.00000152",
"amount": "0.00701726",
"fast_transaction_fee": "0.00000009",
"fast_transaction_fee_currency": "BTC/Byte",
"wait_time": "5 seconds"
}

Start payment

StartPayment is called when customer confirms that will pay in crypto. New address is generated and returned. On return invoice should be finished and transfer window displayed in one edge.

Example:

https://forumpay.com/api/v2/StartPayment/?pos_id=POS1&invoice_currency=EUR&invoice_amount=43.21&currency=BTC&reference_no=12-23-456&accept_zero_confirmations=true

Response:

{
"invoice_amount": "48.25",
"invoice_currency": "EUR",
"currency": "BTC",
"rate": "6467.35",
"amount_exchange": "0.00701496",
"network_processing_fee": "0.00000152",
"amount": "0.00701648",
"fast_transaction_fee": "0.00000009",
"fast_transaction_fee_currency": "BTC/Byte",
"wait_time": "5 seconds",
"address": "38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69",
"qr": "bitcoin:38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69?amount=0.00843504",
"qr_alt": "38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69",
"qr_img": "https://forumpay.com/api/qr/?d=bitcoin%3A38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69%3Famount%3D0.00701648",
"qr_alt_img": "https://forumpay.com/api/qr/?d=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69"
}

Check payment

CheckPayment checks the payment to blockchain and returns if transaction is confirmed or not. It should be refreshed periodically till confirmed=true or CancelPayment must be called if payment will not be made.

Example:

https://forumpay.com/api/v2/CheckPayment/?pos_id=POS1&currency=BTC&payment_id=123e4567-e89b-12d3-a456-426614174000&address=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69

Response:

{
"reference_no": "12-23-456",
"invoice_amount": "48.25",
"invoice_currency": "EUR",
"currency": "BTC",
"amount": "0.00668125",
"payment": "0.00000000",
"confirmations": 0,
"min_confirmations": 0,
"confirmed": false,
"status": "Waiting for transaction.",
"wait_time": "5 seconds"
}

Cancel payment

It is very important that payment is Canceled if transfer will not be made from any reason.

Example:

https://forumpay.com/api/v2/CancelPayment/?pos_id=POS1&currency=BTC&payment_id=123e4567-e89b-12d3-a456-426614174000&address=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69

Response:

{
"cancelled": true
}

Accept payment

Accepts the payment if paid amount is too low. Parameter accepted_amount must match the payment response from CheckPayment call.

Example:

https://forumpay.com/api/v2/AcceptPayment/?pos_id=POS1&currency=BTC&invoice_no=1234e456-abab-1234-84bd-3ef32112b60a&address=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69&accepted_amount=0.01000000

Response:

{
"success": true
}

Get a list of currencies

GetCurrencyList returns array of currencies for current user.

Example:

https://forumpay.com/api/v2/GetCurrencyList/

Response:

[
{"currency":"BTC","description":"Bitcoin"},
{"currency":"LTC","description":"Litecoin"},
{"currency":"ETH","description":"Ethereum"}
]

Get a list of transactions

GetTransactions returns array of transactions for current user.

Example:

https://forumpay.com/api/v2/GetTransactions/?offset=0&limit=20

Response:

[
{
"status": "Confirmed",
"pos_id": "POS1",
"payment_id": "123e4567-e89b-12d3-a456-426614174000",
"invoice_currency": "EUR",
"invoice_amount": "100",
"currency": "BTC",
"amount": "0.01729569",
"address": "38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69",
"type": "Sell",
"payment": 0.01729569,
"refund": "",
"refund_amount_opened": "",
"refund_status": null,
"invoice_date": null,
"inserted": "2020-03-27 11:00:00",
"confirmed": null,
"cancelled": "2020-03-27 11:00:00",
"double_spending_alert": null,
"accept_zero_confirmations": false,
"item_name": "",
"access_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
...
]

Webhook / Instant Payment Notification (IPN)

Setup webhook notifications URL to be notified when payment status changes.

Payment data is sent in JSON format in the HTTP message body.

Your server URL:

You can setup your webhook notifications URL in your profile under payment settings.

HTTP message body data:

{
"pos_id":"POS1",
"currency":"BTC",
"payment_id":"123e4567-e89b-12d3-a456-426614174000",
"reference_no":"12-23-456",
"address":"38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69"
}

Use a CheckPayment API call to get status information about the payment.
Security warning: when using a reference_no always validate if matches with reference_no in CheckPayment API response.


×