Crypto Payments: Partner Integration

Endpoints for partners integrating Cyclebit crypto payments into their own platforms or POS systems.

Create POS Payment

Initiates a payment transaction from a Point-of-Sale (POS) device, allowing for faster confirmations.

POST /api/payment/pos

Requires an X-Platform-Secret header for authentication.

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 Response

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

Update Transaction Email

Allows a user to set or update the customer email associated with a specific transaction.

PUT /api/orders/{transaction_id}/email

Request Body

Field	Type	Mandatory	Description
`email`	String	No	Email address of the customer.

Example Response

{
    "ok": true,
    "result": true
}

Choose Cryptocurrency

Allows choosing a specific cryptocurrency or token to pay with.

PUT /api/orders/{transaction_id}/chosen

Request Body

Field	Type	Mandatory	Description
`tokenId`	String	Yes	Token ID obtained from the "Get transaction details" response.

Example Response

{
    "ok": true,
    "result": {
        "merchant": "Demo Store",
        "img": "https://secure.cyclebit.com/api/s3/E5N6POO5SGES",
        "description": null,
        "status": "IN_PROGRESS",
        "symbol": "USDT_TRC_20",
        "address": "TUM6XsLCLSVPzRhmJNqk6p2zuhn9ug2y8K",
        "price": "100.5",
        "rate": "1.00",
        "time": "2024-06-16T07:53:20.599Z",
        "tokenAddress": "th9d4xjwcjemh5jvkikrkwek9uugvywjrt",
        "net": "TRX",
        "amount": "106.63384",
        "transactionFee": "6.133840",
        "deepLink": "tron:TUM6XsLCLSVPzRhmJNqk6p2zuhn9ug2y8K?amount=106.63384",
        "currencyId": "LF6DCTQZVZ1J",
        "currencySign": "$",
        "currencySymbol": "USD",
        "localRate": "1",
        "isBack": true
    }
}

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.