SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX -
SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX - SANDBOX -
× #message#
×

Warning

API Manual

Introduction

API

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

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

Webhook / Instant Payment Notification (IPN)

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


Performing a call

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

  • pos_id

For localization you can use the locale parameter:

  • locale

To assign payment to a specific user, use the parameter:

  • user

Authentication

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


Return values

The API returns results in JSON format.


Error handling

On error there will be an err element in the result. Err value will contain the error description.


API reference

API calls are performed by sending a HTTP request to the URL starting with a link, followed by the 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}&require_kyt_for_confirmation={require_kyt_for_confirmation} 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}&payment_id={payment_id}&invoice_amount={invoice_amount}&currency={currency}&reference_no={reference_no}&accept_zero_confirmations={accept_zero_confirmations}&payer_ip_address={payer_ip_address}&payer_id={payer_id}&auto_accept_underpayment={auto_accept_underpayment}&auto_accept_underpayment_min={auto_accept_underpayment_min}&auto_accept_overpayment={auto_accept_overpayment}&payer_user_agent={payer_user_agent}&require_kyt_for_confirmation={require_kyt_for_confirmation} 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, 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, state, status, inserted, access_url, unconfirmed_amount, unconfirmed_invoice_amount, refund_amount_opened, refund, refund_status, blocked_alert_level}
GET /CancelPayment/?pos_id={pos_id}&currency={currency}&payment_id={payment_id}&address={address}&reason={reason}&comment={comment} returns {cancelled}
GET /AcceptPayment/?pos_id={pos_id}&payment_id={payment_id}&currency={currency}&address={address}&accepted_amount={accepted_amount}&accepted_invoice_amount={accepted_invoice_amount} returns {success}
GET /RefundPayment/?pos_id={pos_id}&payment_id={payment_id}&currency={currency}&address_out={address_out}&refund_amount={refund_amount} returns {wait_time}
GET /GetCurrencyList/?invoice_currency={invoice_currency} returns [{currency, description, zero_confirmations_enabled, currency_fiat, rate}...]
GET /GetTransactions/?offset={offset}&limit={limit} returns [{state, status, pos_id, payment_id, invoice_currency, invoice_amount, currency, amount, address, type, payment, refund, refund_amount_opened, refund_status, inserted, confirmed, cancelled, double_spending_alert, accept_zero_confirmations, item_name, access_token, payer_ip_address, payer_id}...]

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_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 (should match unconfirmed_amount)
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 with zero confirmations (use only when POS is under video surveillance)
require_kyt_for_confirmation Require KYT check to succeed before confirming the payment (optional, default false)
refund_amount Amount of cryptocurrency that should be refunded (should match refund_amount_opened)
address_out The target address that should receive the refunded amount minus networking fees
payer_ip_address The IP address associated with the payer
payer_id Optional merchant-side payer identifier (max. 64 characters, allowed: 'A'-'Z', 'a'-'z', '0'-'9', '.', '_' and '-')
auto_accept_underpayment Optional: automatically modify invoice_amount and accept the payment if paid amount is lower than requested (allowed values: 'true' or 'false')
auto_accept_underpayment_min Optional: only apply auto_accept_underpayment setting if the paid amount corresponds to at least this value (in invoice_currency)
auto_accept_overpayment Optional: automatically modify invoice_amount and accept the payment if paid amount is higher than requested (allowed values: 'true' or 'false')
payer_user_agent Optional payer's User-Agent when API is used for website payments integration
user Set sub-merchant this payment belongs to (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
reason Optional: consumer's reason for payment cancellation. (Choices: qr_code_problem, no_wallet, curious, bad_rate, other)
comment Optional: additional comment for cancellation reason
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_amount Cryptocurrency value of amount that was either underpaid or was paid after cancellation
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)
refund_amount_opened Refund amount (if refund is possible)
wait_time Expected time to confirm
confirmed Is transaction successful and confirmed
confirmed_time Time of confirmation
success Indicates successful operation
cancelled Is cancellation successful
cancelled_time Time of cancellation
blocked_alert_level Alert level if payment is blocked ("severe", "high", "medium", "low" or "unknown")
state Payment states:
"waiting", "processing", "cancelled", "confirmed", "zero_confirmed", "underpayment", "blocked"

 waiting > cancelled
 waiting > processing [> zero_confirmed] > confirmed
 waiting > processing > cancelled
 waiting > underpayment > cancelled

Accepting underpayments or payments received after cancellation:
  ... > underpayment > processing > ...
  ... > cancelled > processing > ...
status Payment status description for user
zero_confirmations_enabled If currency supports zero confirmations
currency_fiat Invoice currency
stats_token Authentication token that can be used to send payment progress data to statistics collector

Get rate

Displays information on the rate and amount to the customer. Should be refreshed on the GUI every five seconds until StartPayment is called.

Example:

https://sandbox.forumpay.com/api/v2/GetRate/?pos_id=POS1&invoice_currency=EUR&invoice_amount=48.25&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",
"payment_id":"123e4567-e89b-12d3-a456-426614174000"
}

Start payment

StartPayment is called when the customer confirms that they will pay in crypto. A new address is generated and returned.

Example:

https://sandbox.forumpay.com/api/v2/StartPayment/?pos_id=POS1&invoice_currency=EUR&payment_id=123e4567-e89b-12d3-a456-426614174000&invoice_amount=48.25&currency=BTC&reference_no=12-23-456&accept_zero_confirmations=true&payer_ip_address=1.1.1.1&payer_user_agent=Mozilla/5.0%20(Windows%20NT%2010.0;%20Win64;%20x64)%20AppleWebKit/537.36%20(KHTML,%20like%20Gecko)%20Chrome/92.0.4515.159%20Safari/537.36

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",
"payment_id": "123e4567-e89b-12d3-a456-426614174000",
"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 on the blockchain and returns if the transaction has been confirmed or not. It should be refreshed periodically until confirmed=true or CancelPayment must be called if the payment will not be completed.

Example:

https://sandbox.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,
"state": "waiting",
"status": "Waiting for transaction.",
"wait_time": "5 seconds"
}

Cancel payment

You may call Cancel Payment to cancel any payment where the transfer will not be sent for any reason. The payment can not be cancelled when the blockchain transaction is already sent.

Example:

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

Response:

{
"cancelled": true
}

Accept payment

Accepts the payment in the case an under payment is made. The accepted_amount parameter must match the payment response received from the CheckPayment call.

Example:

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

Response:

{
"success": true
}

Refund payment

Refunds the payment. The refund_amount parameter must match the refund_amount_opened response received from the CheckPayment call.

Example:

https://sandbox.forumpay.com/api/v2/RefundPayment/?pos_id=POS1&currency=BTC&payment_id=1234e456-abab-1234-84bd-3ef32112b60a&address_out=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69&refund_amount=0.01000000

Response:

{
"wait_time": "120 minutes"
}

Get a list of currencies

GetCurrencyList returns an array of currencies available to the merchant. Parameter invoice_currency is optional.

Example:

https://sandbox.forumpay.com/api/v2/GetCurrencyList/?invoice_currency=AUD

Response:

[
{"currency":"BTC","description":"Bitcoin","zero_confirmations_enabled":"1","currency_fiat":"AUD","rate":"77179.40"},
{"currency":"LTC","description":"Litecoin","zero_confirmations_enabled":"1","currency_fiat":"AUD","rate":"220.99"},
{"currency":"ETH","description":"Ethereum","zero_confirmations_enabled":"1","currency_fiat":"AUD","rate":"4070.66"},
]

Get a list of transactions

GetTransactions returns an array of transactions for the current merchant.

Example:

https://sandbox.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,
"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"
},
...
]

×