Merchantview 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:
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 | /GetRate/?pos_id={pos_id}&invoice_currency={invoice_currency}&invoice_amount={invoice_amount}¤cy={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}¤cy={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}¤cy={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}¤cy={currency}&payment_id={payment_id}&address={address}&reason={reason}&comment={comment} |
returns {cancelled} |
| GET | /AcceptPayment/?pos_id={pos_id}&payment_id={payment_id}¤cy={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}¤cy={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 |
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://Merchantview.com/api/v2/GetRate/?pos_id=POS1&invoice_currency=EUR&invoice_amount=48.25¤cy=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"
}
Example:
https://Merchantview.com/api/v2/StartPayment/?pos_id=POS1&invoice_currency=EUR&payment_id=123e4567-e89b-12d3-a456-426614174000&invoice_amount=48.25¤cy=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://Merchantview.com/api/qr/?d=bitcoin%3A38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69%3Famount%3D0.00701648",
"qr_alt_img": "https://Merchantview.com/api/qr/?d=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69"
}
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://Merchantview.com/api/v2/CheckPayment/?pos_id=POS1¤cy=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"
}
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://Merchantview.com/api/v2/CancelPayment/?pos_id=POS1¤cy=BTC&payment_id=123e4567-e89b-12d3-a456-426614174000&address=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69&reason=other&comment=test
Response:
{
"cancelled": true
}
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://Merchantview.com/api/v2/AcceptPayment/?pos_id=POS1¤cy=BTC&payment_id=1234e456-abab-1234-84bd-3ef32112b60a&address=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69&accepted_amount=0.01000000&accepted_invoice_amount=10.0
Response:
{
"success": true
}
Refunds the payment. The refund_amount parameter must match the refund_amount_opened response received from the CheckPayment call.
Example:
https://Merchantview.com/api/v2/RefundPayment/?pos_id=POS1¤cy=BTC&payment_id=1234e456-abab-1234-84bd-3ef32112b60a&address_out=38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69&refund_amount=0.01000000
Response:
{
"wait_time": "120 minutes"
}
GetTransactions returns an array of transactions for the current merchant.
Example:
https://Merchantview.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"
},
...
]