Developer Documentation

Introduction

Welcome to Open API Developer Documentation. Our platform allows merchants to interact with our payment gateway programmatically via HTTP API, enabling you to view, add, and cancel payments as well as check payment status.

Service URL

https://api.demoURL.com/v2/

Webhook / Instant Payment Notification (IPN)

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

API Overview

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

pos_id - Point of service identification number for your reference (e.g. POS1, WEB1, ...)

Optional parameters:

locale - For localization
user - To assign payment to a specific user

Authentication

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

Example Authentication Header

Authorization: Basic base64(username:api_key)

API Reference

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

Method	Endpoint	Description
GET	`/GetRate/`	Get exchange rate and payment amount information
GET	`/StartPayment/`	Initialize a new payment transaction
GET	`/CheckPayment/`	Check payment status and confirmations
GET	`/CancelPayment/`	Cancel a pending payment
GET	`/AcceptPayment/`	Accept an underpayment
GET	`/RefundPayment/`	Process a payment refund
GET	`/GetCurrencyList/`	Get list of supported currencies
GET	`/GetTransactions/`	Get list of merchant transactions

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.

Endpoint

GET /GetRate/

Parameters

pos_id - Point of service identification
invoice_currency - Currency code for FIAT currency on invoice (EUR, USD, etc.)
invoice_amount - Amount on invoice for FIAT currency
currency - Cryptocurrency symbol (BTC, ETH, etc.)
accept_zero_confirmations - Confirms small payment with zero confirmations
require_kyt_for_confirmation - Require KYT check to succeed before confirming

Example Request

https://api.demoURL.com/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"
}

Start Payment

Initialize a new payment transaction and get payment details including address and QR codes.

Endpoint

GET /StartPayment/

Parameters

pos_id - Point of service identification
payment_id - Payment ID received from GetRate
invoice_currency - Currency code for FIAT currency
invoice_amount - Amount on invoice for FIAT currency
currency - Cryptocurrency symbol
reference_no - Optional reference number for your records
accept_zero_confirmations - Enable zero confirmations
payer_ip_address - The IP address associated with the payer
payer_user_agent - User agent string
require_kyt_for_confirmation - Require KYT check

Example Request

https://api.demoURL.com/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

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://api.demoURL.com/api/qr/?d=bitcoin%3A38wGZr2xLgbHWsYrsNCER1C9mZkNHwyd69%3Famount%3D0.00701648",
  "qr_alt_img": "https://api.demoURL.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.

Endpoint

GET /CheckPayment/

Parameters

pos_id - Point of service identification
currency - Cryptocurrency symbol
payment_id - Payment ID received from StartPayment
address - Address for payment

Example Request

https://api.demoURL.com/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"
}

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.

Endpoint

GET /CancelPayment/

Parameters

pos_id - Point of service identification
currency - Cryptocurrency symbol
payment_id - Payment ID received from StartPayment
address - Address for payment
reason - Reason for cancellation
comment - Additional comment

Example Request

https://api.demoURL.com/v2/CancelPayment/?pos_id=POS1¤cy=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.

Endpoint

GET /AcceptPayment/

Parameters

pos_id - Point of service identification
payment_id - Payment ID received from StartPayment
currency - Cryptocurrency symbol
address - Address for payment
accepted_amount - Amount of payment that is being accepted
accepted_invoice_amount - Amount of payment being accepted for FIAT currency

Example Request

https://api.demoURL.com/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
}

Refund Payment

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

Endpoint

GET /RefundPayment/

Parameters

pos_id - Point of service identification
payment_id - Payment ID received from StartPayment
currency - Cryptocurrency symbol
address_out - The target address that should receive the refunded amount
refund_amount - Amount of cryptocurrency that should be refunded

Example Request

https://api.demoURL.com/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"
}

Get Transactions

GetTransactions returns an array of transactions for the current merchant.

Endpoint

GET /GetTransactions/

Parameters

offset - Number of records to skip
limit - Maximum number of records to return

Example Request

https://api.demoURL.com/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"
  }
]

Error Handling

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

Error Response Example

{
  "err": "Invalid API key or authentication failed"
}

Common Error Codes

401 - Unauthorized (Invalid API key)
400 - Bad Request (Invalid parameters)
404 - Not Found (Invalid endpoint)
500 - Internal Server Error

Webhooks

Webhooks allow you to receive real-time notifications when payment statuses change. Configure your webhook URL in your merchant dashboard to receive instant payment notifications.

Webhook Events

payment.confirmed - Payment has been confirmed
payment.cancelled - Payment has been cancelled
payment.underpaid - Payment received but amount is less than expected
payment.refunded - Payment has been refunded

Webhook Payload Example

{
  "event": "payment.confirmed",
  "payment_id": "123e4567-e89b-12d3-a456-426614174000",
  "pos_id": "POS1",
  "status": "confirmed",
  "amount": "0.00701648",
  "currency": "BTC",
  "timestamp": "2024-01-15T10:30:00Z"
}

Need Help?

If you need assistance with our API integration or have questions about the documentation, our developer support team is here to help.

Documentation

Comprehensive guides and tutorials for all API endpoints.

Code Examples

Ready-to-use code samples in multiple programming languages.

Contact Developer Support