Crypto Payments: Merchant Integration

Integrate cryptocurrency payments using Cyclebit, our enterprise grade digital currency processor.

Create a Payment

Endpoint

POST /api/payment

Base URL: https://secure.cyclebit.io

Authentication

API requests are authenticated using an API key passed in the Authorization header.

Request Body

Field	Type	Mandatory	Description
`amount`	String	Yes	Amount of the payment.
`currency`	String	Yes	Fiat currency in which the payment amount is set.
`custom_id`	String	No	Unique identifier for the transaction, specific to the merchant.
`email`	String	No	Email address of the customer.
`description`	String	No	Description of the transaction.
`redirect_url`	String	No	URL to redirect the customer after the payment is completed.
`callback_url`	String	No	URL to receive callback (webhook) notifications for payment status.

Example Request

{
  "amount": "99.99",
  "currency": "USD",
  "custom_id": "TESTID12345",
  "email": "customer@cyclebit.com",
  "description": "Test description",
  "redirect_url": "https://www.cyclebit.com/",
  "callback_url": "https://www.cyclebit.com/"
}

Response Body

Field	Type	Description
`ok`	Boolean	Indicates if the request was successful.
`result`	Object	The result object.
`id`	String	The ID of the transaction.
`successUrl`	String	The URL to redirect the customer to for completing the payment.

Example Response

{
    "ok": true,
    "result": {
        "id": "Z2MFRBX8KPRN",
        "successUrl": "https://secure.cyclebit.io/payment/?id=Z2MFRBX8KPRN"
    }
}

Checking Payment Status

Get Transaction Details

Retrieves the payment details for a specific transaction. The response structure depends on the transaction status.

GET /api/orders/{transaction_id}/payment

Response Body (Common Fields)

Field	Type	Description
`status`	String	The status of the payment (e.g., CREATED, IN_PROGRESS, COMPLETED).
`merchant`	String	The merchant involved in the payment.
`img`	String	The image associated with the payment.
`description`	String	A description of the payment.
`redirectUrl`	String	The URL to redirect for the payment.
`customId`	String	A custom identifier for the payment.
`currencySign`	String	Fiat currency sign for the payment.
`currencySymbol`	String	Fiat currency symbol for the payment.
`email`	String	Customer email associated with the payment.
`price`	String	Price of the payment in fiat currency.
`possible`	Array	Array of possible cryptocurrency/token payment options.
`id`	String	The identifier of the payment option.
`symbol`	String	The symbol of the payment option.
`imgLink`	String	The image link for the payment option.

Example Response (Status: CREATED)

{
    "ok": true,
    "result": {
        "status": "CREATED",
        "merchant": "Demo Store",
        "price": "100.5",
        "possible": [
            {
                "id": "ITEZD7BTH012",
                "symbol": "BTC",
                "imgLink": "https://icons.cyclebit.com/btc.png"
            }
        ]
    }
}

Example Response (Status: IN_PROGRESS)

{
    "ok": true,
    "result": {
        "status": "IN_PROGRESS",
        "merchant": "Demo Store",
        "symbol": "USDT_TRC_20",
        "address": "TUM6XsLCLSVPzRhmJNqk6p2zuhn9ug2y8K",
        "price": "100.5",
        "rate": "1.00",
        "amount": "106.63384",
        "transactionFee": "6.133840",
        "deepLink": "tron:TUM6XsLCLSVPzRhmJNqk6p2zuhn9ug2y8K?amount=106.63384"
    }
}

Example Response (Status: COMPLETED)

{
    "ok": true,
    "result": {
        "status": "COMPLETED",
        "merchant": "Demo Store",
        "description": "Test payment"
    }
}

Example Response (Status: UNDERPAID / OVERPAID / HIGH_RISK)

{
    "ok": true,
    "result": {
        "status": "UNDERPAID",
        "merchant": "Demo Store",
        "description": "Test payment"
    }
}

Webhook Notifications

Cyclebit sends a webhook notification to your configured `callback_url` each time the transaction status changes.

When you receive a webhook, your system should call the Get Transaction Details endpoint to retrieve the latest status and verify the transaction details.

Webhook Request Format

{
  "order_id": "NCQC2T3HS97X"
}

Responding to Webhooks

Your system must reply with an HTTP 200 status code to acknowledge receipt of the webhook. If Cyclebit does not receive a 200 OK, it will attempt to resend the notification.