ForumPay allows merchants to interact with payment gateway platform programmatically via HTTP API (view, add and cancel orders as well as check if a payment was successful). Service URL:
Webhook Notifications URL can be set to notify the merchant when a payments status changes.
API calls are generated with a URL, followed by the endpoint URL and request data. Each API call requires:
For localization you can use the locale parameter:
To assign payment to a specific user, use the parameter:
API calls are authenticated using HTTP Basic access authentication. You can generate your API key in your API Settings.
The API returns results in JSON format.
On error there will be an err element in the result. Err value will contain the error description.
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 | /GetBuyRate/?pos_id={pos_id}&invoice_currency={invoice_currency}&invoice_amount={invoice_amount}¤cy={currency} |
returns {invoice_currency, invoice_amount, currency, wait_time, network_processing_fee, rate, amount_exchange, amount, payment_id} |
| GET | /StartBuyOrder/?pos_id={pos_id}&invoice_currency={invoice_currency}&reference_no={reference_no}&invoice_amount={invoice_amount}¤cy={currency}&address={address}&payment_id={payment_id}&payer_ip_address={payer_ip_address}&payer_id={payer_id}&payer_user_agent={payer_user_agent} |
returns {invoice_currency, invoice_amount, currency, wait_time, network_processing_fee, rate, amount_exchange, amount, payment_id, address} |
| GET | /ConfirmBuyOrder/?pos_id={pos_id}&address={address}&payment_id={payment_id} |
returns {address, currency} |
| GET | /CheckPayment/?pos_id={pos_id}¤cy={currency}&payment_id={payment_id}&address={address} |
returns {reference_no, inserted, invoice_amount, type, invoice_currency, amount, currency, confirmed, confirmed_time, status, wait_time, transfer_crypto_status, transfer_crypto_date_scheduled, transfer_crypto_transaction_id, state} |
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, ...) - max. 36 characters, allowed characters are: A-Za-z0-9._- |
| payment_id | Payment ID received from GetBuyRate |
| reference_no | Optional reference number for your record (e.g. invoice or order number) |
| invoice_amount | Amount on invoice for FIAT currency |
| invoice_currency | Currency code for FIAT currency on invoice (EUR, USD..) |
| currency | Cryptocurrency symbol (BTC, ETH..) to exchange the fiat into |
| address | The consumers wallet address for the crypto purchased |
| 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 '-') |
| payer_user_agent | Optional payer's User-Agent when API is used for website payments integration |
| transfer_crypto_auth_type | Optional type for transfer crypto authentication. Valid types are "none" (default if not set) and "email_confirmation". None does not require any additional confirmation, "email_confirmation" requires confirmations via email. |
| Output | Meaning |
| invoice_amount | Amount on invoice for FIAT currency |
| invoice_currency | Currency code for FIAT currency on invoice (EUR, USD..) |
| currency | Cryptocurrency symbol (BTC, ETH..) to exchange the fiat into |
| wait_time | Expected time to confirm |
| network_processing_fee | Amount needed to transfer cryptocurrency from merchant to exchange |
| rate | Exchange rate |
| amount_exchange | Amount to exchange to get value on the invoice |
| amount | Total amount to pay |
| payment_id | Payment ID |
| address | The consumers wallet address for the crypto purchased |
| reference_no | Reference number |
| inserted | Date and time of the transaction |
| type | Type of order |
| confirmed | Is transaction successful and confirmed |
| confirmed_time | Time of confirmation |
| status | Payment status description for user |
| state | Payment states: "waiting", "processing", "cancelled", "confirmed" waiting > cancelled waiting > processing > confirmed waiting > processing > cancelled |
| transfer_crypto_status | Transfer crypto status: "approval needed", "pending", "sent" |
| transfer_crypto_date_scheduled | Date when transfer crypto was scheduled |
| transfer_crypto_transaction_id | Transfer crypto blockchain transaction id |
The GetBuyRate API call is used to get buy rate information for the exchange of cryptocurrency to fiat currency.
Example:
https://api.forumpay.com/pay/v2/GetBuyRate/?pos_id=web&invoice_currency=EUR&invoice_amount=5¤cy=BTC
Response:
{
"invoice_currency":"EUR",
"invoice_amount":"50.00",
"currency":"BTC",
"wait_time":"120 minutes",
"network_processing_fee":"0.00016691",
"rate":"37900.3221",
"amount_exchange":"0.00131925",
"amount":"0.00115234",
"payment_id":"123e4567-e89b-12d3-a456-426614174000"
}
The StartBuyOrder API call is used to initiate a buy order/purchase of cryptocurrency.
Example:
https://api.forumpay.com/pay/v2/StartBuyOrder/?pos_id=web&invoice_currency=EUR&invoice_amount=5¤cy=BTC&reference_no=12-23-789&address=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69&payment_id=123e4567-e89b-12d3-a456-426614174000
Response:
{
"invoice_currency":"EUR",
"invoice_amount":"50.00",
"currency":"BTC",
"wait_time":"120 minutes",
"network_processing_fee":"0.00016691",
"rate":"37900.3221",
"amount_exchange":"0.00131925",
"amount":"0.00115234",
"payment_id":"123e4567-e89b-12d3-a456-426614174000",
"address":"38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69"
}
The ConfirmBuyOrder API call is used to confirm that you have received fiat from the consumer. This step is required to complete the transaction and schedule a transaction to send crypto to the consumer's wallet address.
Example:
https://api.forumpay.com/pay/v2/ConfirmBuyOrder/?pos_id=web&payment_id=123e4567-e89b-12d3-a456-426614174000&address=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69
Response:
{
"address":"38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69",
"currency":"BTC"
}
The CheckPayment API call is used to check the status of a buy order.
Example:
https://api.forumpay.com/pay/v2/CheckPayment/?pos_id=web&payment_id=123e4567-e89b-12d3-a456-426614174000¤cy=BTC&address=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69
Response:
{
"reference_no":"12-23-789",
"inserted":"2021-08-06 08:23:24",
"invoice_currency":"EUR",
"invoice_amount":"50.00",
"type":"Buy",
"amount":"0.00115234",
"currency":"BTC",
"confirmed":true,
"confirmed_time":"2021-08-06 08:27:03",
"status":"Confirmed",
"wait_time":"120 minutes",
"transfer_crypto_status":"pending",
"transfer_crypto_date_scheduled":"2021-08-06 08:27:37",
"state":"confirmed"
}